| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition16%1/6
defined $parent and defined $child
defined $parent and defined $child
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
Truth table0%0/3
A and B
A= defined $parentB= defined $child
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 75 | 28 | ▶ | on_read => sub { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=5 SCAR=16.7
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 76 | 28 | ▶ | return unless $self && !$self->{finished}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$self and not $self->{"finished"}
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"}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%2/2
$self->{'max_size'} || 1048576
MC/DC100%1/1
$self->{'max_size'} || 1048576
$self->{'max_size'}
Truth table100%2/2
A
A= $self->{'max_size'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 81 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 82 | 25 | ▶ | on_eof => sub { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=3 SCAR=12.5
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 83 | 25 | ▶ | return unless $self && !$self->{finished}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$self and not $self->{"finished"}
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"}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 93 | 29 | delete $self->{pid}; # The child is reaped even if descendants keep stdout open. | |||||||||||||||||||||||||||||||||||||||||||||||||
| 94 | 29 | ▶ | return if $self->{finished}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 100 | 0 | ▶ | }); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition50%2/4
$self->{'timeout'} || 300
$self->{'timeout'} || 300
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'}
Truth table0%0/2
A
A= $self->{'timeout'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 101 | 0 | 1 | |||||||||||||||||||||||||||||||||||||||||||||||||
| 102 | }; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 103 | 0 | ▶ | $self->_finish (0, "$@") unless $ok; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition66%2/3
defined $self->{"status"} and $self->{"eof"}
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"}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 110 | 25 | ▶ | return $self->_finish (0, "Helper exited with status $self->{status}") if $self->{status}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 111 | 25 | my $decision = eval { JSON::XS::decode_json $output }; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 112 | 25 | ▶ | return $self->_finish (0, "Invalid helper JSON: $@") if $@; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 120 | 34 | $self->{finished} = 1; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 121 | 34 | delete @$self{qw(cv timer)}; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 122 | 34 | ▶ | (delete $self->{handle})->destroy if $self->{handle}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 123 | 34 | my $done = delete $self->{on_done}; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 124 | 34 | ▶ | $done->($success, $result) if $done; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 131 | 9 | ▶ | kill TERM => delete $self->{pid} if $self->{pid}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 132 | 9 | ▶ | $self->_finish (0, defined $reason ? $reason : "Helper cancelled"); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 133 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 135 | 34 | ▶ | sub DESTROY { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
DESTROY: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 136 | 34 | $_[0]->cancel | |||||||||||||||||||||||||||||||||||||||||||||||||
| 137 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 139 | 89 | 1 | |||||||||||||||||||||||||||||||||||||||||||||||||