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 89 ▶use common::sense;
Subroutine BEGIN: called CC=1 SCAR=0.0
42  
43 89 ▶use JSON::XS ();
Subroutine BEGIN: called CC=1 SCAR=0.0
44 89 ▶use Scalar::Util qw(weaken);
Subroutine BEGIN: called CC=1 SCAR=0.0
45  
46 89 ▶use AnyEvent ();
Subroutine BEGIN: called CC=1 SCAR=0.0
47 89 ▶use AnyEvent::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
48 89 ▶use AnyEvent::Handle ();
Subroutine BEGIN: called CC=1 SCAR=0.0
49 89 ▶use AnyEvent::MCP ();
Subroutine BEGIN: called CC=1 SCAR=0.0
50  
51 89 our @ISA = qw(AnyEvent::MCP::Base);
52  
53 34 ▶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 34 34
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" 34 0 34
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 34 34
unless defined $parent and defined $child 0 0 0
Condition16%1/6
defined $parent and defined $child
!ll&&!rl&&r
0034
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' ? : 31 3 34
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 28 ▶ on_read => sub {
Subroutine __ANON__: called CC=5 SCAR=16.7
76 28 ▶ return unless $self && !$self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
unless $self and not $self->{"finished"} 0 28 28
Condition33%1/3
$self and not $self->{"finished"}
!ll&&!rl&&r
0028
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 28 $output .= $_[0]{rbuf};
78 28 $_[0]{rbuf} = "";
79 $self->cancel ("Helper output exceeds size limit")
80 28 ▶ if length $output > ($self->{max_size} || 1024 * 1024);
Branch: 1 branch
BranchTrueFalseTotal
if length $output > ($self->{"max_size"} || 1048576) 3 25 28
Condition100%2/2
$self->{'max_size'} || 1048576
l!l
325
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 25 ▶ on_eof => sub {
Subroutine __ANON__: called CC=3 SCAR=12.5
83 25 ▶ return unless $self && !$self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
unless $self and not $self->{"finished"} 0 25 25
Condition33%1/3
$self and not $self->{"finished"}
!ll&&!rl&&r
0025
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 25 $self->{eof} = 1;
85 25 $self->_complete ($output);
86 },
87 0 );
88 0 $self->{handle}->push_write ($input);
89 0 $self->{handle}->push_shutdown;
90 32 ▶ $self->{cv}->cb (sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
91 32 my $status = $_[0]->recv;
92 32 ▶ return unless $self;
Branch: 1 branch
BranchTrueFalseTotal
unless $self 3 29 32
93 29 delete $self->{pid}; # The child is reaped even if descendants keep stdout open.
94 29 ▶ return if $self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"finished"} 4 25 29
95 25 $self->{status} = $status;
96 25 $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
1024
$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 34 34
unless $ok 0 0 0
104 }
105  
106 50 ▶sub _complete {
Subroutine _complete: called CC=5 SCAR=16.2
107 50 my ($self, $output) = @_;
108  
109 50 ▶ return unless defined $self->{status} && $self->{eof};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"status"} and $self->{"eof"} 25 25 50
Condition66%2/3
defined $self->{"status"} and $self->{"eof"}
!ll&&!rl&&r
25025
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 25 ▶ return $self->_finish (0, "Helper exited with status $self->{status}") if $self->{status};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"status"} 0 25 25
111 25 my $decision = eval { JSON::XS::decode_json $output };
112 25 ▶ return $self->_finish (0, "Invalid helper JSON: $@") if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 3 22 25
113 22 $self->_finish (1, $decision);
114 }
115  
116 34 ▶sub _finish {
Subroutine _finish: called CC=4 SCAR=14.3
117 34 my ($self, $success, $result) = @_;
118  
119 34 ▶ return if $self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"finished"} 0 34 34
120 34 $self->{finished} = 1;
121 34 delete @$self{qw(cv timer)};
122 34 ▶ (delete $self->{handle})->destroy if $self->{handle};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"handle"} 34 0 34
123 34 my $done = delete $self->{on_done};
124 34 ▶ $done->($success, $result) if $done;
Branch: 1 branch
BranchTrueFalseTotal
if $done 34 0 34
125 }
126  
127 46 ▶sub cancel {
Subroutine cancel: called CC=4 SCAR=13.9
Pod undocumented
128 46 my ($self, $reason) = @_;
129  
130 46 ▶ return if $self->{finished};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"finished"} 37 9 46
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 34 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
136 34 $_[0]->cancel
137 }
138  
139 89 1
« blib/lib/AnyEvent/MCP/Client/JSONL.pm ↑ Summary blib/lib/AnyEvent/MCP/Server/Request.pm »