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

filter: Statementstmt 70.0% 75 / 107 Branchbran 41.0% 23 / 56 Conditioncond 20.8% 10 / 48 MC/DCmcdc 15.3% 4 / 26 Subroutinesub 75.0% 18 / 24 Podpod 100% 4 / 4 totaltotal 50.5% 134 / 265 CC 49 SCAR 35.9
CC
49
Cov
51%
dispatch
146.6
request_idle_exit
56.0
__ANON__
20.0
CRAP 36.1
« 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.
94  
95 =back
96  
97 =cut
98  
99 package AnyEvent::MCP::Server::JSONL;
100  
101 217 ▶use common::sense;
Subroutine BEGIN: called CC=1 SCAR=0.0
102 217 ▶use parent "AnyEvent::MCP::Server";
Subroutine BEGIN: called CC=1 SCAR=0.0
103 217 ▶use AnyEvent::Handle ();
Subroutine BEGIN: called CC=1 SCAR=0.0
104 217 ▶use AnyEvent ();
Subroutine BEGIN: called CC=1 SCAR=0.0
105 217 ▶use JSON::XS ();
Subroutine BEGIN: called CC=1 SCAR=0.0
106 217 ▶use Scalar::Util qw(weaken);
Subroutine BEGIN: called CC=1 SCAR=0.0
107  
108 217 ▶sub accept {
Subroutine accept: called CC=3 SCAR=13.3
Pod documented
109 217 my ($self, $fh, $fh_out) = @_;
110  
111 217 delete $self->{_closed};
112 217 weaken $self;
113  
114 my $handle = AnyEvent::Handle->new (
115 fh => $fh,
116 rbuf_max => $self->{max_size} || 8 * 1024 * 1024,
117 4228 ▶ on_read => sub { $self->_read ($_[0]) if $self },
Subroutine __ANON__: called CC=2 SCAR=7.6
Branch: 1 branch
BranchTrueFalseTotal
if $self 4228 0 4228
118 0 ▶ on_error => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
119 0 my ($handle, $fatal, $message) = @_;
120  
121 0 ▶ $self->event (connection_error => $handle, $message) if $self;
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
122 0 ▶ $self->_close ($handle) if $self;
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
123 },
124 106 ▶ on_eof => sub {
Subroutine __ANON__: called CC=3 SCAR=11.8
125 106 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 0 106 106
126 106 my ($handle) = @_;
127  
128 106 ▶ if ($handle->{mcp_out}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($handle->{'mcp_out'}) { } 106 0 106
129 106 $handle->{mcp_eof} = 1;
130 106 $self->_drain ($handle);
131 } else {
132 0 $self->_close ($handle);
133 }
134 },
135 217 ▶ );
Condition100%2/2
$self->{'max_size'} || 8388608
l!l
3214
MC/DC100%1/1
$self->{'max_size'} || 8388608
$self->{'max_size'}
Truth table100%2/2
A
A= $self->{'max_size'}
Aresult
11
00
136  
137 217 ▶ if ($fh_out) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fh_out) 208 9 217
138 208 weaken (my $input = $handle);
139 $handle->{mcp_out} = AnyEvent::Handle->new (
140 fh => $fh_out,
141 0 ▶ on_error => sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
142 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
143 0 ▶ $self->close if $self;
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
144 },
145 208 );
146 }
147  
148 217 $handle->{mcp_peer} = {};
149 217 $handle->{mcp_peer}{mcp_handle} = $handle;
150 217 weaken $handle->{mcp_peer}{mcp_handle};
151 217 $self->{connections}{$handle} = $handle;
152  
153 217 $handle
154 }
155  
156 4228 ▶sub _read {
Subroutine _read: called CC=1 SCAR=0.3
157 4228 my ($self, $handle) = @_;
158  
159 4228 weaken $self;
160  
161 4228 ▶ $handle->push_read (line => sub {
Subroutine __ANON__: called CC=2 SCAR=7.7
162 4228 my ($handle, $line) = @_;
163  
164 4228 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 0 4228 4228
165  
166 4228 ++$handle->{mcp_active};
167 $self->json_rpc (
168 $line,
169 4130 ▶ sub {
Subroutine __ANON__: called CC=5 SCAR=16.1
170 4130 --$handle->{mcp_active};
171 4130 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 4 4126 4130
172  
173 4126 ▶ ($handle->{mcp_out} || $handle)->push_write ($_[0] . "\n")
Branch: 1 branch
BranchTrueFalseTotal
if defined $_[0] 4104 22 4126
Condition66%2/3
$handle->{'mcp_out'} || $handle
l!l&&r!l&&!r
4076280
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
174 if defined $_[0];
175 4126 ▶ $self->_drain ($handle) if $handle->{mcp_eof};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_eof"} 1 4125 4126
176 },
177 peer => $handle->{mcp_peer},
178 0 ▶ on_notify => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
179 0 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 0 0 0
180  
181 0 ▶ ($handle->{mcp_out} || $handle)->push_write (JSON::XS::encode_json ($_[1]) . "\n");
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
182 },
183 4228 );
184 4228 });
185 }
186  
187 0 ▶sub request_idle_exit {
Subroutine request_idle_exit: not called CC=7 SCAR=40.3
Pod documented
188 0 my ($self) = @_;
189  
190 return unless $ENV{PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL} eq "stdio"
191 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
192  
193 0 for my $handle (values %{$self->{connections}}) {
194 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
195  
196 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
197 jsonrpc => "2.0", method => "anyevent-mcp/idle-exit", params => {},
198 }) . "\n");
199 0 $self->{idle_exit_requested} = 1;
200 0 return 1
201 }
202  
203 undef
204 0 }
205  
206 4159 ▶sub dispatch {
Subroutine dispatch: called CC=13 SCAR=49.9
Pod documented
207 4159 my ($self, $req) = @_;
208  
209 4159 ▶ if ($req->{method} eq "anyevent-mcp/shutdown") {
Branch: 1 branch
BranchTrueFalseTotal
if ($req->{"method"} eq "anyevent-mcp/shutdown") 0 4159 4159
210 0 my $handle = $req->{peer}{mcp_handle};
211 my $busy = grep $_->{mcp_active} > ($_ == $handle ? 1 : 0),
212 0 ▶ values %{$self->{connections}};
Branch: 1 branch
BranchTrueFalseTotal
$_ == $handle ? : 0 0 0
213 my $accepted = $ENV{PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL} eq "stdio"
214 && $req->{peer}{aemcp_multibroker} && $self->{idle_exit_requested}
215 && !$self->{_idle_shutting_down} && !$busy
216 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
217  
218 0 ▶ $req->reply ({ accepted => $accepted ? JSON::XS::true : JSON::XS::false });
Branch: 1 branch
BranchTrueFalseTotal
$accepted ? : 0 0 0
219 0 ▶ if ($accepted) {
Branch: 1 branch
BranchTrueFalseTotal
if ($accepted) 0 0 0
220 0 $self->{_idle_shutting_down} = 1;
221 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
222 0 weaken $self;
223 0 ▶ if (length $out->{wbuf}) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $out->{'wbuf'}) { } 0 0 0
224 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
225 } else {
226 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
227 }
228 }
229  
230 0 return;
231 }
232  
233 4159 $self->SUPER::dispatch ($req)
234 }
235  
236 107 ▶sub _drain {
Subroutine _drain: called CC=4 SCAR=13.9
237 107 my ($self, $handle) = @_;
238  
239 107 ▶ return if $handle->{mcp_active} || $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_active"} or $handle->{"mcp_closed"} 1 106 107
Condition66%2/3
$handle->{"mcp_active"} or $handle->{"mcp_closed"}
l!l&&r!l&&!r
10106
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
240  
241 106 my $output = $handle->{mcp_out};
242 106 ▶ if (length $output->{wbuf}) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $output->{'wbuf'}) { } 1 105 106
243 1 weaken $self;
244 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
245 } else {
246 105 $self->_close ($handle);
247 }
248 }
249  
250 120 ▶sub _close {
Subroutine _close: called CC=5 SCAR=16.1
251 120 my ($self, $handle) = @_;
252  
253 120 ▶ return if $handle->{mcp_closed};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_closed"} 0 120 120
254 120 $handle->{mcp_closed} = 1;
255  
256 120 ▶ my $requests = delete $handle->{mcp_peer}{requests} || {};
Condition100%2/2
delete $handle->{'mcp_peer'}{'requests'} || {}
l!l
1173
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
257 120 $_->cancel ("Connection closed") for grep defined, values %$requests;
258  
259 120 delete $self->{connections}{$handle};
260 120 ▶ $handle->{mcp_out}->destroy if $handle->{mcp_out};
Branch: 1 branch
BranchTrueFalseTotal
if $handle->{"mcp_out"} 111 9 120
261 120 $handle->destroy;
262 120 $self->event (connection_close => $handle);
263 }
264  
265 237 ▶sub close {
Subroutine close: called CC=4 SCAR=13.9
Pod documented
266 237 my ($self) = @_;
267  
268 237 ▶ return if $self->{_closed}++;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_closed"}++ 116 121 237
269 121 delete $self->{listener};
270 121 ▶ $self->_close ($_) for values %{$self->{connections} || {}};
Condition100%2/2
$self->{'connections'} || {}
l!l
1192
MC/DC100%1/1
$self->{'connections'} || {}
$self->{'connections'}
Truth table100%2/2
A
A= $self->{'connections'}
Aresult
11
00
271 121 $self->event (close =>);
272 }
273  
274 118 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
275 118 $_[0]->close
276 }
277  
278 217 1
« blib/lib/AnyEvent/MCP.pm ↑ Summary bin/mcp-ask-user »