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 56 ▶use common::sense;
Subroutine BEGIN: called CC=1 SCAR=0.0
103 56 ▶use parent "AnyEvent::MCP::Server";
Subroutine BEGIN: called CC=1 SCAR=0.0
104 56 ▶use AnyEvent::Handle ();
Subroutine BEGIN: called CC=1 SCAR=0.0
105 56 ▶use AnyEvent ();
Subroutine BEGIN: called CC=1 SCAR=0.0
106 56 ▶use JSON::XS ();
Subroutine BEGIN: called CC=1 SCAR=0.0
107 56 ▶use Scalar::Util qw(weaken);
Subroutine BEGIN: called CC=1 SCAR=0.0
108  
109 56 ▶sub accept {
Subroutine accept: called CC=3 SCAR=13.3
Pod documented
110 56 my ($self, $fh, $fh_out) = @_;
111  
112 56 delete $self->{_closed};
113 56 weaken $self;
114  
115 my $handle = AnyEvent::Handle->new (
116 fh => $fh,
117 rbuf_max => $self->{max_size} || 8 * 1024 * 1024,
118 410 ▶ on_read => sub { $self->_read ($_[0]) if $self },
Subroutine __ANON__: called CC=2 SCAR=7.6
Branch: 1 branch
BranchTrueFalseTotal
if $self 410 0 410
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 47 ▶ on_eof => sub {
Subroutine __ANON__: called CC=3 SCAR=11.8
126 47 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 0 47 47
127 47 my ($handle) = @_;
128  
129 47 ▶ if ($handle->{mcp_out}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($handle->{'mcp_out'}) { } 47 0 47
130 47 $handle->{mcp_eof} = 1;
131 47 $self->_drain ($handle);
132 } else {
133 0 $self->_close ($handle);
134 }
135 },
136 56 ▶ );
Condition100%2/2
$self->{'max_size'} || 8388608
l!l
353
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 56 ▶ if ($fh_out) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fh_out) 51 5 56
139 51 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 51 );
147 }
148  
149 56 $handle->{mcp_peer} = {};
150 56 $handle->{mcp_peer}{mcp_handle} = $handle;
151 56 weaken $handle->{mcp_peer}{mcp_handle};
152 56 $self->{connections}{$handle} = $handle;
153  
154 56 $handle
155 }
156  
157 410 ▶sub _read {
Subroutine _read: called CC=1 SCAR=0.1
158 410 my ($self, $handle) = @_;
159  
160 410 weaken $self;
161  
162 410 ▶ $handle->push_read (line => sub {
Subroutine __ANON__: called CC=2 SCAR=7.1
163 410 my ($handle, $line) = @_;
164  
165 410 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 0 410 410
166  
167 410 ++$handle->{mcp_active};
168 $self->json_rpc (
169 $line,
170 408 ▶ sub {
Subroutine __ANON__: called CC=5 SCAR=16.1
171 408 --$handle->{mcp_active};
172 408 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 4 404 408
173  
174 404 ▶ ($handle->{mcp_out} || $handle)->push_write ($_[0] . "\n")
Branch: 1 branch
BranchTrueFalseTotal
if defined $_[0] 394 10 404
Condition66%2/3
$handle->{'mcp_out'} || $handle
l!l&&r!l&&!r
381130
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 404 ▶ $self->_drain ($handle) if $handle->{mcp_eof};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_eof"} 1 403 404
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 410 );
185 410 });
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 388 ▶sub dispatch {
Subroutine dispatch: called CC=14 SCAR=51.4
Pod documented
208 388 my ($self, $req) = @_;
209  
210 388 ▶ if ($req->{method} eq "anyevent-mcp/shutdown") {
Branch: 1 branch
BranchTrueFalseTotal
if ($req->{"method"} eq "anyevent-mcp/shutdown") 0 388 388
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 388 $self->SUPER::dispatch ($req)
236 }
237  
238 48 ▶sub _drain {
Subroutine _drain: called CC=4 SCAR=13.9
239 48 my ($self, $handle) = @_;
240  
241 48 ▶ return if $handle->{mcp_active} || $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_active"} or $handle->{"mcp_closed"} 1 47 48
Condition66%2/3
$handle->{"mcp_active"} or $handle->{"mcp_closed"}
l!l&&r!l&&!r
1047
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 47 my $output = $handle->{mcp_out};
244 47 ▶ if (length $output->{wbuf}) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $output->{'wbuf'}) { } 1 46 47
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 46 $self->_close ($handle);
249 }
250 }
251  
252 54 ▶sub _close {
Subroutine _close: called CC=5 SCAR=16.1
253 54 my ($self, $handle) = @_;
254  
255 54 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 0 54 54
256 54 $handle->{mcp_closed} = 1;
257  
258 54 ▶ my $requests = delete $handle->{mcp_peer}{requests} || {};
Condition100%2/2
delete $handle->{'mcp_peer'}{'requests'} || {}
l!l
531
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 54 $_->cancel ("Connection closed") for grep defined, values %$requests;
260  
261 54 delete $self->{connections}{$handle};
262 54 ▶ $handle->{mcp_out}->destroy if $handle->{mcp_out};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_out"} 49 5 54
263 54 $handle->destroy;
264 54 $self->event (connection_close => $handle);
265 }
266  
267 105 ▶sub close {
Subroutine close: called CC=4 SCAR=13.9
Pod documented
268 105 my ($self) = @_;
269  
270 105 ▶ return if $self->{_closed}++;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_closed"}++ 51 54 105
271 54 delete $self->{listener};
272 54 ▶ $self->_close ($_) for values %{$self->{connections} || {}};
Condition50%1/2
$self->{'connections'} || {}
l!l
540
MC/DC0%0/1
$self->{'connections'} || {}
$self->{'connections'}
Truth table50%1/2
A
A= $self->{'connections'}
Aresult
11
00
273 54 $self->event (close =>);
274 }
275  
276 52 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
277 52 $_[0]->close
278 }
279  
280 56 1
« blib/lib/AnyEvent/MCP.pm ↑ Summary bin/mcp-ask-user »