view release on metacpan or  search on metacpan

lib/Event/RPC/Client.pm  view on Meta::CPAN

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 B<ssl_ca_file> or B<ssl_ca_path> option.

=over 4

=item B<ssl>

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

=item B<ssl_ca_file>

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

=item B<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.

=item B<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. 

=back

=head2 AUTHENTICATION OPTIONS

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

=over 4

=item B<auth_user>

A valid username.

=item B<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);

=back

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

=head2 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:

=over 4

=item B<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
explicitely 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.

=back

=head2 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:

=over 4

=item B<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 B<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 B<error_cb> an exception is thrown instead.

=back

=head1 METHODS

=over 4

=item $rpc_client->B<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.

=item $rpc_client->B<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.

=item $rpc_client->B<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!

=item $rpc_client->B<get_max_packet_size>

Returns the currently active max packet size.

=back

=head1 READY ONLY ATTRIBUTES

=over 4

=item $rpc_client->B<get_server_version>

Returns the Event::RPC version number of the server after connecting.

=item $rpc_client->B<get_server_protocol>

Returns the Event::RPC protocol number of the server after connecting.

=item $rpc_client->B<get_client_version>

Returns the Event::RPC version number of the client.

=item $rpc_client->B<get_client_protocol>

Returns the Event::RPC protocol number of the client.

=back

=head1 AUTHORS

  Jörn Reder <joern AT zyn.de>

=head1 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.

=cut