# NAME JSON::RPC2::AnyEvent::Client - Asynchronous nonblocking JSON RPC2 client with method mapping # SYNOPSIS use JSON::RPC2::AnyEvent::Client; # create tcp connection my $rpc = JSON::RPC2::AnyEvent::Client->new( host => "127.0.0.1", port => 5555, on_error => sub{ die $_[0] } ); # call $rpc->sum( 1, 2, sub{ my ( $failed, $result, $error ) = @_; print $result unless $failed || $error; }) # call remote function with simple configure $rpc->service('agent')->listed()->remote_function( 'param1', 'param2', sub{ my ( $failed, $result, $error ) = @_; }) # some more constructor arguments my $rpc = JSON::RPC2::AnyEvent::Client->new( url => "https://$host:$port/api", # http/https transport service => 'agent', call => 'listed' || 'named', service => '_service', # rename any this module methods ); # destroy rpc connection when done $rpc->destroy; # DESCRIPTION JSON::RPC2::AnyEvent::Client is JSON RPC2 client, with tcp/http/https transport. Remote functions is mapped to local client object methods. For example remote function fn(...) is called as $c->fn(...,cb). Params of function is params of remote functions with additional one at the end of param list. Additional last param is result handler soubroutine. Implementation is based on JSON RPC2 implementation [JSON::RPC2::Client](https://metacpan.org/pod/JSON::RPC2::Client). Transport implementation is based on [AnyEvent::Handle](https://metacpan.org/pod/AnyEvent::Handle) for tcp, and on [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent::HTTP) for http/https. The 'tcp' implementation use persistent connection, that make tcp connection at object creation and use it all object life time. The http/https persistence is AnyEvent::HTTP implementation dependent and currently it is not persistent for idempotent requsests (JSON RPC2 need POST requset). See description of 'persistent' and 'keepalive' params of [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent::HTTP). # METHODS - $rpc = **new** JSON::RPC2::AnyEvent::Client host=>'example.com', ... The constructor supports arguments as `key => value` pairs. - host => 'example.com' The hostname or ip address. This enable tcp transport. The special value "unix/" used to connect to unix domain socket. Current version support unix domain socket only for 'tcp' transport. - port => 5555 The tcp port number or unix domain socket path. Used togather with 'host' param. - on\_error = sub{ die $\_\[0\] } The transport error handler callback. Remote RPC service errors does not mapped to this handler. This error also will emit all alredy waited for result callback handlers. - url => "https://$host:$port/api/rpc" The url of requst. This enables http/https transport. - service => 'agent' Set the service name, it will be prefix before remote function name with dot as separator. So if service is 'agent' then call like $rpc->remote\_fn(), then `agent.remote_fn` will be called - call => 'listed' || 'named' Type of RPC call, default listed. - simplify\_errors => 1 This option change callback api from two error to one by unify transport error with text error message from remote server. This option allow to simplify result callback writing but make less compatible with rpc protocol. It also make result callback impossible to recognize type of error is it transport or remote. This is usable for simple applications. See result callback handler for more info. - any\_method\_name => 'remap\_method\_name' If remote server have method with same name as in this module, it is possible to rename this module `method_name` to another name `remap_method_name` - **service** ( "service\_name" ) Set remote service name, if undef - then no service name used. - **listed** RPC listed call type will be used. - **named** RPC named call type will be used. - **any other name** ( $param1, $param2, ..., $cb ) Any method name will called via RPC on remote server. Last param must be result handler callback cb(). # RESULT HANDLER CALLBACK The result callback handler is a soubroutine that called when rpc function is called and result is arrived or an error occured. There three param of callback is `( $fail, $result, $error );` The $fail is transport error. It is string that contain description of communication or data decoding error. The $result is server responce, valid only when there is no fail or error. The $error is described in rpc protocol standart remote server error responce. It is valid only when no fail. There is special case for simple applications enabled by `simplify_errors` constructor argument. The result callback at this case have only two params. First param is transport error if any or text error message arrived from remote service. Simplified callback prototype is: `( $error, $result );` # DEPENDENCIES - [AnyEvent::Handle](https://metacpan.org/pod/AnyEvent::Handle); - [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent::HTTP); - [JSON::RPC2::Client](https://metacpan.org/pod/JSON::RPC2::Client); - [JSON::XS](https://metacpan.org/pod/JSON::XS) # LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. # AUTHOR Serguei Okladnikov <oklaspec@gmail.com>