blib/lib/AnyEvent/MCP/Helper.pm

filter: Statementstmt 77.7% 77 / 99 Branchbran 53.8% 28 / 52 Conditioncond 42.8% 9 / 21 MC/DCmcdc 23.0% 3 / 13 Subroutinesub 88.8% 16 / 18 Podpod 0.0% 0 / 3 totaltotal 64.5% 133 / 206 CC 54 SCAR 18.0
CC
54
Cov
66%
ask
14.9
ask
14.9
__ANON__
6.0
CRAP 6.0
« blib/lib/AnyEvent/MCP/Client/JSONL.pm ↑ Summary blib/lib/AnyEvent/MCP/Server/Request.pm »
1 =head1 NAME
2  
3 AnyEvent::MCP::Helper - asynchronous JSON exchange with an external helper
4  
5 =head1 SYNOPSIS
6  
7 use AnyEvent::MCP::Helper;
8 my $job = AnyEvent::MCP::Helper->new (
9 helper => ["my-helper", "--option"], timeout => 300,
10 );
11 $job->ask ($input, sub {
12 my ($success, $result) = @_;
13 ...
14 });
15  
16 =head1 DESCRIPTION
17  
18 Runs an executable (or an argument array, never a shell command), writes one
19 UTF-8 JSON value to its stdin and closes that input. A successful helper
20 writes one JSON value to stdout and exits zero. Diagnostics use stderr.
21  
22 C<ask ($input, $done)> calls C<$done-E<gt>($success, $result)> once. On failure,
23 C<$result> is an error string. One exchange may be active per object.
24 C<timeout> defaults to 300 seconds and C<max_size> to 1 MiB of output.
25 C<cancel ($reason)> terminates the helper and completes with failure.
26 The independent child watcher reaps the helper after cancellation too.
27  
28 This module handles processes and bytes, not the meaning of the JSON.
29 It is the transport for local form and permission helpers: an MCP server
30 or multibroker can ask a human without blocking its AnyEvent loop.
31 Ordinary server authors should normally use
32 L<AnyEvent::MCP::Server::Permissions> or the form facilities in
33 L<AnyEvent::MCP::Permissions::Ask>, not launch helpers directly.
34 L<AnyEvent::MCP::Permissions::Ask> provides the permission interface;
35 C<anyevent-mcp-form-elicitation> implements the standard form request/response contract.
36  
37 =cut
38  
39 package AnyEvent::MCP::Helper;
40  
41 390 ▶use common::sense;
Subroutine BEGIN: called CC=1 SCAR=0.0
42  
43 390 ▶use JSON::XS ();
Subroutine BEGIN: called CC=1 SCAR=0.0
44 390 ▶use Scalar::Util qw(weaken);
Subroutine BEGIN: called CC=1 SCAR=0.0
45  
46 390 ▶use AnyEvent ();
Subroutine BEGIN: called CC=1 SCAR=0.0
47 390 ▶use AnyEvent::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
48 390 ▶use AnyEvent::Handle ();
Subroutine BEGIN: called CC=1 SCAR=0.0
49 390 ▶use AnyEvent::MCP ();
Subroutine BEGIN: called CC=1 SCAR=0.0
50  
51 390 our @ISA = qw(AnyEvent::MCP::Base);
52  
53 57 ▶sub ask {
Subroutine ask: called CC=8 SCAR=27.0
Pod undocumented
54 0 ▶ my ($self, $prepared, $done) = @_;
Subroutine ask: not called CC=8 SCAR=27.0
Pod undocumented
55  
56 0 ▶ die "Helper is already active\n" if $self->{on_done};
Branch: 2 branches
BranchTrueFalseTotal
if $self->{"on_done"} 0 57 57
if $self->{"on_done"} 0 0 0
57 0 $self->{finished} = 0;
58 0 $self->{on_done} = $done;
59 0 delete @$self{qw(status eof)};
60 0 ▶ my $helper = $self->{helper} or die "No helper configured\n";
Branch: 2 branches
BranchTrueFalseTotal
my $helper = $self->{"helper"} or die "No helper configured\n" 57 0 57
my $helper = $self->{"helper"} or die "No helper configured\n" 0 0 0
61 0 my $input = JSON::XS::encode_json $prepared;
62 0 my $output = "";
63 0 my $ok = eval {
64 0 my ($parent, $child) = AnyEvent::Util::portable_socketpair;
65 0 ▶ die "Cannot create helper socket: $!\n" unless defined $parent && defined $child;
Branch: 2 branches
BranchTrueFalseTotal
unless defined $parent and defined $child 0 57 57
unless defined $parent and defined $child 0 0 0
Condition16%1/6
defined $parent and defined $child
!ll&&!rl&&r
0057
defined $parent and defined $child
!ll&&!rl&&r
000
MC/DC0%0/2
defined $parent and defined $child
defined $parent defined $child
MC/DC0%0/2
defined $parent and defined $child
defined $parent defined $child
Truth table33%1/3
A and B
A= defined $parentB= defined $child
ABresult
0X0
100
111
Truth table0%0/3
A and B
A= defined $parentB= defined $child
ABresult
0X0
100
111
66 $self->{cv} = AnyEvent::Util::run_cmd (
67 ref $helper eq "ARRAY" ? $helper : [$helper],
68 0 ▶ "<" => $child, ">" => $child, '$$' => \$self->{pid}, close_all => 1,
Branch: 2 branches
BranchTrueFalseTotal
ref $helper eq 'ARRAY' ? : 37 20 57
ref $helper eq 'ARRAY' ? : 0 0 0
69 );
70 0 close $child;
71 0 weaken $self;
72 $self->{handle} = AnyEvent::Handle->new (
73 fh => $parent,
74 0 ▶ on_error => sub { $self->cancel ("Helper socket: $_[2]") if $self },
Subroutine __ANON__: not called CC=2 SCAR=17.9
Branch: 1 branch
BranchTrueFalseTotal
if $self 0 0 0
75 51 ▶ on_read => sub {
Subroutine __ANON__: called CC=5 SCAR=16.7
76 51 ▶ return unless $self && !$self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
unless $self and not $self->{"finished"} 0 51 51
Condition33%1/3
$self and not $self->{"finished"}
!ll&&!rl&&r
0051
MC/DC0%0/2
$self and not $self->{"finished"}
$self not $self->{"finished"}
Truth table33%1/3
A and not(B)
A= $selfB= not $self->{"finished"}
ABresult
0X0
100
111
77 51 $output .= $_[0]{rbuf};
78 51 $_[0]{rbuf} = "";
79 $self->cancel ("Helper output exceeds size limit")
80 51 ▶ if length $output > ($self->{max_size} || 1024 * 1024);
Branch: 1 branch
BranchTrueFalseTotal
if length $output > ($self->{"max_size"} || 1048576) 3 48 51
Condition100%2/2
$self->{'max_size'} || 1048576
l!l
348
MC/DC100%1/1
$self->{'max_size'} || 1048576
$self->{'max_size'}
Truth table100%2/2
A
A= $self->{'max_size'}
Aresult
11
00
81 },
82 48 ▶ on_eof => sub {
Subroutine __ANON__: called CC=3 SCAR=12.5
83 48 ▶ return unless $self && !$self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
unless $self and not $self->{"finished"} 0 48 48
Condition33%1/3
$self and not $self->{"finished"}
!ll&&!rl&&r
0048
MC/DC0%0/2
$self and not $self->{"finished"}
$self not $self->{"finished"}
Truth table33%1/3
A and not(B)
A= $selfB= not $self->{"finished"}
ABresult
0X0
100
111
84 48 $self->{eof} = 1;
85 48 $self->_complete ($output);
86 },
87 0 );
88 0 $self->{handle}->push_write ($input);
89 0 $self->{handle}->push_shutdown;
90 55 ▶ $self->{cv}->cb (sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
91 55 my $status = $_[0]->recv;
92 55 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 3 52 55
93 52 delete $self->{pid}; # The child is reaped even if descendants keep stdout open.
94 52 ▶ return if $self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"finished"} 4 48 52
95 48 $self->{status} = $status;
96 48 $self->_complete ($output);
97 0 });
98 3 ▶ $self->{timer} = AnyEvent->timer (after => $self->{timeout} || 300, cb => sub {
Subroutine __ANON__: called CC=2 SCAR=7.6
99 3 ▶ $self->cancel ("Helper timed out") if $self;
Branch: 1 branch
BranchTrueFalseTotal
if $self 3 0 3
100 0 ▶ });
Condition50%2/4
$self->{'timeout'} || 300
l!l
3225
$self->{'timeout'} || 300
l!l
00
MC/DC100%1/1
$self->{'timeout'} || 300
$self->{'timeout'}
MC/DC0%0/1
$self->{'timeout'} || 300
$self->{'timeout'}
Truth table100%2/2
A
A= $self->{'timeout'}
Aresult
11
00
Truth table0%0/2
A
A= $self->{'timeout'}
Aresult
11
00
101 0 1
102 };
103 0 ▶ $self->_finish (0, "$@") unless $ok;
Branch: 2 branches
BranchTrueFalseTotal
unless $ok 0 57 57
unless $ok 0 0 0
104 }
105  
106 96 ▶sub _complete {
Subroutine _complete: called CC=5 SCAR=16.2
107 96 my ($self, $output) = @_;
108  
109 96 ▶ return unless defined $self->{status} && $self->{eof};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"status"} and $self->{"eof"} 48 48 96
Condition66%2/3
defined $self->{"status"} and $self->{"eof"}
!ll&&!rl&&r
48048
MC/DC50%1/2
defined $self->{"status"} and $self->{"eof"}
defined $self->{"status"} $self->{"eof"}
Truth table66%2/3
A and B
A= defined $self->{"status"}B= $self->{"eof"}
ABresult
0X0
100
111
110 48 ▶ return $self->_finish (0, "Helper exited with status $self->{status}") if $self->{status};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"status"} 0 48 48
111 48 my $decision = eval { JSON::XS::decode_json $output };
112 48 ▶ return $self->_finish (0, "Invalid helper JSON: $@") if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 3 45 48
113 45 $self->_finish (1, $decision);
114 }
115  
116 57 ▶sub _finish {
Subroutine _finish: called CC=4 SCAR=14.3
117 57 my ($self, $success, $result) = @_;
118  
119 57 ▶ return if $self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"finished"} 0 57 57
120 57 $self->{finished} = 1;
121 57 delete @$self{qw(cv timer)};
122 57 ▶ (delete $self->{handle})->destroy if $self->{handle};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"handle"} 57 0 57
123 57 my $done = delete $self->{on_done};
124 57 ▶ $done->($success, $result) if $done;
Branch: 1 branch
BranchTrueFalseTotal
if $done 57 0 57
125 }
126  
127 68 ▶sub cancel {
Subroutine cancel: called CC=4 SCAR=13.9
Pod undocumented
128 68 my ($self, $reason) = @_;
129  
130 68 ▶ return if $self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"finished"} 59 9 68
131 9 ▶ kill TERM => delete $self->{pid} if $self->{pid};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"pid"} 9 0 9
132 9 ▶ $self->_finish (0, defined $reason ? $reason : "Helper cancelled");
Branch: 1 branch
BranchTrueFalseTotal
defined $reason ? : 6 3 9
133 }
134  
135 56 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
136 56 $_[0]->cancel
137 }
138  
139 390 1
« blib/lib/AnyEvent/MCP/Client/JSONL.pm ↑ Summary blib/lib/AnyEvent/MCP/Server/Request.pm »