NAME

       Event::RPC::Client - Client API to connect to Event::RPC Servers

SYNOPSIS

         use Event::RPC::Client;

         my $rpc_client = Event::RPC::Client->new (
           #-- Required arguments
           host => "localhost",
           port => 5555,

           #-- Optional arguments
           classes   => [ "Event::RPC::Test" ],
           class_map => { "Event::RPC::Test" => "My::Event::RPC::Test" },

           ssl         => 1,
           ssl_ca_file => "some/ca.crt",
           ssl_ca_path => "some/ca/dir",
           ssl_opts    => { SSL_verifycn_name => 'server-hostname' },

           timeout     => 10,

           auth_user => "fred",
           auth_pass => Event::RPC->crypt("fred",$password),

           insecure_msg_fmt_ok => 1,

           error_cb => sub {
             my ($client, $error) = @_;
             print "An RPC error occured: $error\n";
             $client->disconnect;
             exit;
           },
         );

         $rpc_client->set_max_packet_size(2*1024*1024*1024);
         $rpc_client->connect;

         #-- And now use classes and methods to which the
         #-- server allows access via RPC, here My::TestModule
         #-- from the Event::RPC::Server manpage SYNPOSIS.
         my $obj = My::TestModule->new( data => "foobar" );
         print "obj says hello: ".$obj->hello."\n";
         $obj->set_data("new foobar");
         print "updated data: ".$obj->get_data."\n";

         $rpc_client->disconnect;

DESCRIPTION

       Use this module to write clients accessing objects and methods exported by a Event::RPC
       driven server.

       Just connect to the server over the network, optionally with SSL and user authentication,
       and then simply use the exported classes and methods like having them locally in the
       client.

       General information about the architecture of Event::RPC driven applications is collected
       in the Event::RPC manpage.

       The following documentation describes the client connection options in detail.

CONFIGURATION OPTIONS

       You need to specify at least the server hostname and TCP port to connect a Event::RPC
       server instance. If the server requires a SSL connection or user authentication you need
       to supply the corresponding options as well, otherwise connecting will fail.

       All options described here may be passed to the new() constructor of Event::RPC::Client.
       As well you may set or modify them using set_OPTION style mutators, but not after
       connect() was called!  All options may be read using get_OPTION style accessors.

   REQUIRED OPTIONS
       These are necessary to connect the server:

       server
           This is the hostname of the server running Event::RPC::Server.  Use a IP address or
           DNS name here.

       port
           This is the TCP port the server is listening to.

   NETWORK OPTIONS
       timeout
           Specify a timeout (in seconds), which is applied when connecting the server.

   CLASS IMPORT OPTION
       classes
           This is reference to a list of classes which should be imported into the client. You
           get a warning if you request a class which is not exported by the server.

           By default all server classes are imported. Use this feature if your server exports a
           huge list of classes, but your client doesn't need all of them. This saves memory in
           the client and connect performance increases.

       class_map
           Optionally you can map the class names from the server to a different name on the
           local client using the class_map hash.

           This is necessary if you like to use the same classes locally and remotely. Imported
           classes from the server are by default registered under the same name on the client,
           so this conflicts with local classes named identically.

           On the client you access the remote classes under the name assigned in the class map.
           For example with this map

             class_map => { "Event::ExecFlow::Job" => "_srv::Event::ExecFlow::Job" }

           you need to write this on the client, if you like to create an object remotely on the
           server:

             my $server_job = _srv::Event::ExecFlow::Job->new ( ... );

           and this to create an object on the client:

             my $client_job = Event::ExecFlow::Job->new ( ... );

           The server knows nothing of the renaming on client side, so you still write this on
           the server to create objects there:

             my $job = Event::ExecFlow::Job->new ( ... );

   SSL OPTIONS
       If the server accepts only SSL connections you need to enable ssl here in the client as
       well. By default the SSL connection will be established without any peer verification,
       which makes Man-in-the-Middle attacks possible. If you want to prevent that, you need to
       set either ssl_ca_file or ssl_ca_path option.

       ssl Set this option to 1 to encrypt the network connection using SSL.

       ssl_ca_file
           Path to the the Certificate Authority's certificate file (ca.crt), your server key was
           signed with.

       ssl_ca_path
           Path of a directory containing several trusted certificates with a proper index.
           Please refer to the OpenSSL documentation for details about setting up such a
           directory.

       ssl_opts
           This optional parameter takes a hash reference of options passed to
           IO::Socket::SSL->new(...) to have more control over the SSL connection. For example
           you can set the 'SSL_verifycn_name' here if the server certificate common name doesn't
           match to the hostname you use to resolve the server IP or use you have to use a static
           server IP address or something like that.

   AUTHENTICATION OPTIONS
       If the server requires user authentication you need to set the following options:

       auth_user
           A valid username.

       auth_pass
           The corresponding password, encrypted using Perl's crypt() function, using the
           username as the salt.

           Event::RPC has a convenience function for generating such a crypted password, although
           it's currently just a wrapper around Perl's builtin crypt() function, but probably
           this changes someday, so better use this method:

             $crypted_pass = Event::RPC->crypt($user, $pass);

       If the passed credentials are invalid the Event::RPC::Client->connect() method throws a
       correspondent exception.

   MESSAGE FORMAT OPTIONS
       Event::RPC supports different CPAN modules for data serialisation, named "message formats"
       here:

         SERL -- Sereal::Encoder, Sereal::Decoder
         CBOR -- CBOR::XS
         JSON -- JSON::XS
         STOR -- Storable

       Server and client negotiate automatically which format is best to use. The server sends a
       list of supported formats to the client which takes the first one which is available.

       For the client there is one option to influence this format negotiation mechanism:

       insecure_msg_fmt_ok
           The Storable module is known to be insecure, so it should be taken as the last option
           only. By default the Client would do so. You can prevent that by setting this option
           explicitly to 0. It's enabled by default. Most likely the connection will fail in that
           case, because the server only will offer Storable if no other serialiser is available.

   ERROR HANDLING
       Any exceptions thrown on the server during execution of a remote method will result in a
       corresponding exception on the client. So you can use normal exception handling with eval
       {} when executing remote methods.

       But besides this the network connection between your client and the server may break at
       any time. This raises an exception as well, but you can override this behaviour with the
       following attribute:

       error_cb
           This subroutine is called if any error occurs in the network communication between the
           client and the server. The actual Event::RPC::Client object and an error string are
           passed as arguments.

           This is no generic exception handler for exceptions thrown from the executed methods
           on the server! If you like to catch such exceptions you need to put an eval {} around
           your method calls, as you would do for local method calls.

           If you don't specify an error_cb an exception is thrown instead.

METHODS

       $rpc_client->connect
           This establishes the configured connection to the server. An exception is thrown if
           something goes wrong, e.g. server not available, credentials are invalid or something
           like this.

       $rpc_client->disconnect
           Closes the connection to the server. You may omit explicit disconnecting since it's
           done automatically once the Event::RPC::Client object gets destroyed.

       $rpc_client->set_max_packet_size ( $bytes )
           By default Event::RPC does not handle network packages which exceed 2 GB in size (was
           4 MB with version 1.04 and earlier).

           You can change this value using this method at any time, but 4 GB is the maximum. An
           attempt of the server to send a bigger packet will be aborted and reported as an
           exception on the client and logged as an error message on the server.

           Note: you have to set the same value on client and server side!

       $rpc_client->get_max_packet_size
           Returns the currently active max packet size.

READY ONLY ATTRIBUTES

       $rpc_client->get_server_version
           Returns the Event::RPC version number of the server after connecting.

       $rpc_client->get_server_protocol
           Returns the Event::RPC protocol number of the server after connecting.

       $rpc_client->get_client_version
           Returns the Event::RPC version number of the client.

       $rpc_client->get_client_protocol
           Returns the Event::RPC protocol number of the client.

AUTHORS

         Jörn Reder <joern AT zyn.de>

COPYRIGHT AND LICENSE

       Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.