blib/lib/AnyEvent/MCP/Server/JSONL.pm

filter: Statementstmt 71.3% 77 / 108 Branchbran 41.3% 24 / 58 Conditioncond 20.8% 10 / 48 MC/DCmcdc 11.5% 3 / 26 Subroutinesub 79.1% 19 / 24 Podpod 100% 4 / 4 totaltotal 51.1% 137 / 268 CC 50 SCAR 37.4
CC
50
Cov
52%
dispatch
170.9
request_idle_exit
56.0
__ANON__
20.0
CRAP 41.9
« blib/lib/AnyEvent/MCP.pm ↑ Summary bin/mcp-ask-user »
1 =head1 NAME
2  
3 AnyEvent::MCP::Server::JSONL - MCP over a newline-delimited byte stream
4  
5 =head1 DESCRIPTION
6  
7 Use this transport for stdio servers or an existing stream connection.
8 It implements L<AnyEvent::MCP::Server> over newline-delimited UTF-8 JSON-RPC:
9 one line is one complete message. Keep diagnostic output off the protocol
10 stream; a banner or log message on stdout is not a JSON-RPC response.
11  
12 Unlike HTTP, replies can complete in a different order from requests.
13 The JSON-RPC ids associate them with the correct calls.
14  
15 =head1 EXAMPLE
16  
17 An application that already owns its tool registry and lifetime can
18 serve one stdio MCP connection:
19  
20 use AnyEvent;
21 use AnyEvent::MCP::Server::JSONL;
22  
23 my $server = AnyEvent::MCP::Server::JSONL->new (
24 toolsets => [$tools],
25 );
26 $server->accept (\*STDIN, \*STDOUT);
27 AE::cv->recv;
28  
29 C<$tools> is an L<AnyEvent::MCP::Server::Toolset>. Keep stdout reserved
30 for MCP messages and write diagnostics to stderr. The application is
31 responsible for its event loop and termination. If you do not need to
32 manage those details, use L<AnyEvent::MCP::Server::Simple/mcp_stdio>.
33 The matching client transport is L<AnyEvent::MCP::Client::JSONL>.
34  
35 =head1 METHODS
36  
37 =over
38  
39 =item $handle = $server->accept ($fh, $fh_out)
40  
41 Starts handling C<$fh>. If C<$fh_out> is supplied, it receives outgoing
42 messages; otherwise C<$fh> is used in both directions. Both handles belong
43 to the server until the connection closes.
44  
45 With separate input/output handles, input EOF waits for pending replies
46 and drains the output before closing. EOF on a bidirectional socket closes
47 it immediately and cancels outstanding requests.
48  
49 C<max_size> limits a buffered incoming message, defaulting to 8 MiB.
50  
51 =item $server->close
52  
53 Closes the server's connections and cancels outstanding requests.
54  
55 =back
56  
57 =head1 EVENTS
58  
59 =over
60  
61 =item on_connection_error => $callback->($server, $handle, $message)
62  
63 Called for stream errors before closing the connection.
64  
65 =item on_connection_close => $callback->($server, $handle)
66  
67 Called after a connection has closed.
68  
69 =item on_close => $callback->($server)
70  
71 Called by C<close> after closing all connections.
72  
73 =back
74  
75 =head1 MANAGED SHUTDOWN
76  
77 =over
78  
79 =item $server->request_idle_exit
80  
81 Requests a managed shutdown, once, from a spawned stdio multibroker child
82 whose peer advertised C<anyevent-mcp/multibroker> version 1. The application
83 decides when it is idle. The method returns true when it sends the notification, or undef when
84 there is no eligible connection or it has already sent one.
85 The broker can ignore the notification. When it sends shutdown, the server
86 answers before draining the stream and closing its connections. Closing
87 the server lets Simple's blocking starter return; an embedding application
88 controls its own process lifetime.
89  
90 C<on_idle_shutdown>, if supplied, is C<$callback->($server)> returning true
91 to accept or false to decline a late shutdown request (for example, if
92 application work has resumed). Outstanding MCP requests also prevent
93 acceptance. A declined shutdown clears the one-shot notification state,
94 allowing a later idle-exit request.
95  
96 =back
97  
98 =cut
99  
100 package AnyEvent::MCP::Server::JSONL;
101  
102 55 ▶use common::sense;
Subroutine BEGIN: called CC=1 SCAR=0.0
103 55 ▶use parent "AnyEvent::MCP::Server";
Subroutine BEGIN: called CC=1 SCAR=0.0
104 55 ▶use AnyEvent::Handle ();
Subroutine BEGIN: called CC=1 SCAR=0.0
105 55 ▶use AnyEvent ();
Subroutine BEGIN: called CC=1 SCAR=0.0
106 55 ▶use JSON::XS ();
Subroutine BEGIN: called CC=1 SCAR=0.0
107 55 ▶use Scalar::Util qw(weaken);
Subroutine BEGIN: called CC=1 SCAR=0.0
108  
109 55 ▶sub accept {
Subroutine accept: called CC=3 SCAR=13.3
Pod documented
110 55 my ($self, $fh, $fh_out) = @_;
111  
112 55 delete $self->{_closed};
113 55 weaken $self;
114  
115 my $handle = AnyEvent::Handle->new (
116 fh => $fh,
117 rbuf_max => $self->{max_size} || 8 * 1024 * 1024,
118 389 ▶ on_read => sub { $self->_read ($_[0]) if $self },
Subroutine __ANON__: called CC=2 SCAR=7.6
Branch: 1 branch
BranchTrueFalseTotal
if $self 389 0 389
119 0 ▶ on_error => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
120 0 my ($handle, $fatal, $message) = @_;
121  
122 0 ▶ $self->event (connection_error => $handle, $message) if $self;
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
123 0 ▶ $self->_close ($handle) if $self;
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
124 },
125 48 ▶ on_eof => sub {
Subroutine __ANON__: called CC=3 SCAR=11.8
126 48 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 0 48 48
127 48 my ($handle) = @_;
128  
129 48 ▶ if ($handle->{mcp_out}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($handle->{'mcp_out'}) { } 48 0 48
130 48 $handle->{mcp_eof} = 1;
131 48 $self->_drain ($handle);
132 } else {
133 0 $self->_close ($handle);
134 }
135 },
136 55 ▶ );
Condition100%2/2
$self->{'max_size'} || 8388608
l!l
352
MC/DC100%1/1
$self->{'max_size'} || 8388608
$self->{'max_size'}
Truth table100%2/2
A
A= $self->{'max_size'}
Aresult
11
00
137  
138 55 ▶ if ($fh_out) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fh_out) 50 5 55
139 50 weaken (my $input = $handle);
140 $handle->{mcp_out} = AnyEvent::Handle->new (
141 fh => $fh_out,
142 0 ▶ on_error => sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
143 0 ▶ $self->event (connection_error => $input, $_[2]) if $self && $input;
Branch: 1 branch
BranchTrueFalseTotal
if $self and $input 0 0 0
Condition0%0/3
$self and $input
!ll&&!rl&&r
000
MC/DC0%0/2
$self and $input
$self $input
Truth table0%0/3
A and B
A= $selfB= $input
ABresult
0X0
100
111
144 0 ▶ $self->close if $self;
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
145 },
146 50 );
147 }
148  
149 55 $handle->{mcp_peer} = {};
150 55 $handle->{mcp_peer}{mcp_handle} = $handle;
151 55 weaken $handle->{mcp_peer}{mcp_handle};
152 55 $self->{connections}{$handle} = $handle;
153  
154 55 $handle
155 }
156  
157 389 ▶sub _read {
Subroutine _read: called CC=1 SCAR=0.1
158 389 my ($self, $handle) = @_;
159  
160 389 weaken $self;
161  
162 389 ▶ $handle->push_read (line => sub {
Subroutine __ANON__: called CC=2 SCAR=7.1
163 389 my ($handle, $line) = @_;
164  
165 389 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 0 389 389
166  
167 389 ++$handle->{mcp_active};
168 $self->json_rpc (
169 $line,
170 387 ▶ sub {
Subroutine __ANON__: called CC=5 SCAR=16.1
171 387 --$handle->{mcp_active};
172 387 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 4 383 387
173  
174 383 ▶ ($handle->{mcp_out} || $handle)->push_write ($_[0] . "\n")
Branch: 1 branch
BranchTrueFalseTotal
if defined $_[0] 373 10 383
Condition66%2/3
$handle->{'mcp_out'} || $handle
l!l&&r!l&&!r
360130
MC/DC0%0/2
$handle->{'mcp_out'} || $handle
$handle->{'mcp_out'} $handle
Truth table66%2/3
A || B
A= $handle->{'mcp_out'}B= $handle
ABresult
1X1
011
000
175 if defined $_[0];
176 383 ▶ $self->_drain ($handle) if $handle->{mcp_eof};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_eof"} 1 382 383
177 },
178 peer => $handle->{mcp_peer},
179 3 ▶ on_notify => sub {
Subroutine __ANON__: called CC=3 SCAR=13.1
180 3 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 0 3 3
181  
182 3 ▶ ($handle->{mcp_out} || $handle)->push_write (JSON::XS::encode_json ($_[1]) . "\n");
Condition33%1/3
$handle->{'mcp_out'} || $handle
l!l&&r!l&&!r
300
MC/DC0%0/2
$handle->{'mcp_out'} || $handle
$handle->{'mcp_out'} $handle
Truth table33%1/3
A || B
A= $handle->{'mcp_out'}B= $handle
ABresult
1X1
011
000
183 },
184 389 );
185 389 });
186 }
187  
188 0 ▶sub request_idle_exit {
Subroutine request_idle_exit: not called CC=7 SCAR=40.3
Pod documented
189 0 my ($self) = @_;
190  
191 return unless $ENV{PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL} eq "stdio"
192 0 ▶ && !$self->{idle_exit_requested};
Branch: 1 branch
BranchTrueFalseTotal
unless $ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" and not $self->{"idle_exit_requested"} 0 0 0
Condition0%0/3
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" and not $self->{"idle_exit_requested"}
!ll&&!rl&&r
000
MC/DC0%0/2
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" and not $self->{"idle_exit_requested"}
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" not $self->{"idle_exit_requested"}
Truth table0%0/3
A and not(B)
A= $ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio"B= not $self->{"idle_exit_requested"}
ABresult
0X0
100
111
193  
194 0 for my $handle (values %{$self->{connections}}) {
195 0 ▶ next if $handle->{mcp_closed} || !$handle->{mcp_peer}{aemcp_multibroker};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} or not $handle->{"mcp_peer"}{"aemcp_multibroker"} 0 0 0
Condition0%0/3
$handle->{"mcp_closed"} or not $handle->{"mcp_peer"}{"aemcp_multibroker"}
l!l&&r!l&&!r
000
MC/DC0%0/2
$handle->{"mcp_closed"} or not $handle->{"mcp_peer"}{"aemcp_multibroker"}
$handle->{"mcp_closed"} not $handle->{"mcp_peer"}{"aemcp_multibroker"}
Truth table0%0/3
A or not(B)
A= $handle->{"mcp_closed"}B= not $handle->{"mcp_peer"}{"aemcp_multibroker"}
ABresult
1X1
011
000
196  
197 0 ▶ ($handle->{mcp_out} || $handle)->push_write (JSON::XS::encode_json ({
Condition0%0/3
$handle->{'mcp_out'} || $handle
l!l&&r!l&&!r
000
MC/DC0%0/2
$handle->{'mcp_out'} || $handle
$handle->{'mcp_out'} $handle
Truth table0%0/3
A || B
A= $handle->{'mcp_out'}B= $handle
ABresult
1X1
011
000
198 jsonrpc => "2.0", method => "anyevent-mcp/idle-exit", params => {},
199 }) . "\n");
200 0 $self->{idle_exit_requested} = 1;
201 0 return 1
202 }
203  
204 undef
205 0 }
206  
207 367 ▶sub dispatch {
Subroutine dispatch: called CC=14 SCAR=51.4
Pod documented
208 367 my ($self, $req) = @_;
209  
210 367 ▶ if ($req->{method} eq "anyevent-mcp/shutdown") {
Branch: 1 branch
BranchTrueFalseTotal
if ($req->{"method"} eq "anyevent-mcp/shutdown") 0 367 367
211 0 my $handle = $req->{peer}{mcp_handle};
212 my $busy = grep $_->{mcp_active} > ($_ == $handle ? 1 : 0),
213 0 ▶ values %{$self->{connections}};
Branch: 1 branch
BranchTrueFalseTotal
$_ == $handle ? : 0 0 0
214 my $accepted = $ENV{PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL} eq "stdio"
215 && $req->{peer}{aemcp_multibroker} && $self->{idle_exit_requested}
216 && !$self->{_idle_shutting_down} && !$busy
217 0 ▶ && (!$self->{on_idle_shutdown} || $self->{on_idle_shutdown}->($self));
Condition0%0/18
$ENV{'PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL'} eq 'stdio' && $req->{'peer'}{'aemcp_multibroker'} && $self->{'idle_exit_requested'} && !$self->{'_idle_shutting_down'} && !$busy && (!$self->{'on_idle_shutdown'} || $self->{'on_idle_shutdown'}->($self))
!ll&&!rl&&r
000
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" and $req->{"peer"}{"aemcp_multibroker"} and $self->{"idle_exit_requested"} and not $self->{"_idle_shutting_down"} and not $busy
!ll&&!rl&&r
000
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" and $req->{"peer"}{"aemcp_multibroker"} and $self->{"idle_exit_requested"} and not $self->{"_idle_shutting_down"}
!ll&&!rl&&r
000
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" and $req->{"peer"}{"aemcp_multibroker"} and $self->{"idle_exit_requested"}
!ll&&!rl&&r
000
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" and $req->{"peer"}{"aemcp_multibroker"}
!ll&&!rl&&r
000
not $self->{"on_idle_shutdown"} or $self->{"on_idle_shutdown"}->($self)
l!l&&r!l&&!r
000
MC/DC0%0/7
$ENV{'PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL'} eq 'stdio' && $req->{'peer'}{'aemcp_multibroker'} && $self->{'idle_exit_requested'} && !$self->{'_idle_shutting_down'} && !$busy && (!$self->{'on_idle_shutdown'} || $self->{'on_idle_shutdown'}->($self))
$ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio" $req->{"peer"}{"aemcp_multibroker"} $self->{"idle_exit_requested"} not $self->{"_idle_shutting_down"} not $busy not $self->{"on_idle_shutdown"} $self->{"on_idle_shutdown"}->($self)
Truth table0%0/8
A and B and C and not(D) and not(E) && not(F) or G
A= $ENV{"PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL"} eq "stdio"B= $req->{"peer"}{"aemcp_multibroker"}C= $self->{"idle_exit_requested"}D= not $self->{"_idle_shutting_down"}E= not $busyF= not $self->{"on_idle_shutdown"}G= $self->{"on_idle_shutdown"}->($self)
ABCDEFGresult
0XXXXXX0
10XXXXX0
110XXXX0
1110XXX0
11110XX0
11111000
111111X1
11111011
218  
219 0 ▶ $req->reply ({ accepted => $accepted ? JSON::XS::true : JSON::XS::false });
Branch: 1 branch
BranchTrueFalseTotal
$accepted ? : 0 0 0
220 0 ▶ $self->{idle_exit_requested} = 0 unless $accepted;
Branch: 1 branch
BranchTrueFalseTotal
unless $accepted 0 0 0
221 0 ▶ if ($accepted) {
Branch: 1 branch
BranchTrueFalseTotal
if ($accepted) 0 0 0
222 0 $self->{_idle_shutting_down} = 1;
223 0 ▶ my $out = $handle->{mcp_out} || $handle;
Condition0%0/3
$handle->{'mcp_out'} || $handle
l!l&&r!l&&!r
000
MC/DC0%0/2
$handle->{'mcp_out'} || $handle
$handle->{'mcp_out'} $handle
Truth table0%0/3
A || B
A= $handle->{'mcp_out'}B= $handle
ABresult
1X1
011
000
224 0 weaken $self;
225 0 ▶ if (length $out->{wbuf}) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $out->{'wbuf'}) { } 0 0 0
226 0 ▶ $out->on_drain (sub { $self->close if $self });
Subroutine __ANON__: not called CC=2 SCAR=17.9
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
227 } else {
228 0 ▶ AnyEvent::postpone (sub { $self->close if $self });
Subroutine __ANON__: not called CC=2 SCAR=17.9
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
229 }
230 }
231  
232 0 return;
233 }
234  
235 367 $self->SUPER::dispatch ($req)
236 }
237  
238 49 ▶sub _drain {
Subroutine _drain: called CC=4 SCAR=13.9
239 49 my ($self, $handle) = @_;
240  
241 49 ▶ return if $handle->{mcp_active} || $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_active"} or $handle->{"mcp_closed"} 1 48 49
Condition66%2/3
$handle->{"mcp_active"} or $handle->{"mcp_closed"}
l!l&&r!l&&!r
1048
MC/DC50%1/2
$handle->{"mcp_active"} or $handle->{"mcp_closed"}
$handle->{"mcp_active"} $handle->{"mcp_closed"}
Truth table66%2/3
A or B
A= $handle->{"mcp_active"}B= $handle->{"mcp_closed"}
ABresult
1X1
011
000
242  
243 48 my $output = $handle->{mcp_out};
244 48 ▶ if (length $output->{wbuf}) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $output->{'wbuf'}) { } 1 47 48
245 1 weaken $self;
246 1 ▶ $output->on_drain (sub { $self->_close ($handle) if $self });
Subroutine __ANON__: called CC=2 SCAR=7.2
Branch: 1 branch
BranchTrueFalseTotal
if $self 1 0 1
247 } else {
248 47 $self->_close ($handle);
249 }
250 }
251  
252 53 ▶sub _close {
Subroutine _close: called CC=5 SCAR=16.1
253 53 my ($self, $handle) = @_;
254  
255 53 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 0 53 53
256 53 $handle->{mcp_closed} = 1;
257  
258 53 ▶ my $requests = delete $handle->{mcp_peer}{requests} || {};
Condition100%2/2
delete $handle->{'mcp_peer'}{'requests'} || {}
l!l
521
MC/DC100%1/1
delete $handle->{'mcp_peer'}{'requests'} || {}
delete $handle->{'mcp_peer'}{'requests'}
Truth table100%2/2
A
A= delete $handle->{'mcp_peer'}{'requests'}
Aresult
11
00
259 53 $_->cancel ("Connection closed") for grep defined, values %$requests;
260  
261 53 delete $self->{connections}{$handle};
262 53 ▶ $handle->{mcp_out}->destroy if $handle->{mcp_out};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_out"} 48 5 53
263 53 $handle->destroy;
264 53 $self->event (connection_close => $handle);
265 }
266  
267 101 ▶sub close {
Subroutine close: called CC=4 SCAR=13.9
Pod documented
268 101 my ($self) = @_;
269  
270 101 ▶ return if $self->{_closed}++;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_closed"}++ 48 53 101
271 53 delete $self->{listener};
272 53 ▶ $self->_close ($_) for values %{$self->{connections} || {}};
Condition50%1/2
$self->{'connections'} || {}
l!l
530
MC/DC0%0/1
$self->{'connections'} || {}
$self->{'connections'}
Truth table50%1/2
A
A= $self->{'connections'}
Aresult
11
00
273 53 $self->event (close =>);
274 }
275  
276 51 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
277 51 $_[0]->close
278 }
279  
280 55 1
« blib/lib/AnyEvent/MCP.pm ↑ Summary bin/mcp-ask-user »