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. Transport implementation is based on AnyEvent::Handle for tcp, and on 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.

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;
• AnyEvent::HTTP;
• JSON::RPC2::Client;
• 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