1Event::RPC::Client(3) User Contributed Perl DocumentationEvent::RPC::Client(3)
2
3
4

NAME

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

SYNOPSIS

9         use Event::RPC::Client;
10
11         my $rpc_client = Event::RPC::Client->new (
12           #-- Required arguments
13           host => "localhost",
14           port => 5555,
15
16           #-- Optional arguments
17           classes   => [ "Event::RPC::Test" ],
18           class_map => { "Event::RPC::Test" => "My::Event::RPC::Test" },
19
20           ssl         => 1,
21           ssl_ca_file => "some/ca.crt",
22           ssl_ca_path => "some/ca/dir",
23           ssl_opts    => { SSL_verifycn_name => 'server-hostname' },
24
25           timeout     => 10,
26
27           auth_user => "fred",
28           auth_pass => Event::RPC->crypt("fred",$password),
29
30           insecure_msg_fmt_ok => 1,
31
32           error_cb => sub {
33             my ($client, $error) = @_;
34             print "An RPC error occured: $error\n";
35             $client->disconnect;
36             exit;
37           },
38         );
39
40         $rpc_client->set_max_packet_size(2*1024*1024*1024);
41         $rpc_client->connect;
42
43         #-- And now use classes and methods to which the
44         #-- server allows access via RPC, here My::TestModule
45         #-- from the Event::RPC::Server manpage SYNPOSIS.
46         my $obj = My::TestModule->new( data => "foobar" );
47         print "obj says hello: ".$obj->hello."\n";
48         $obj->set_data("new foobar");
49         print "updated data: ".$obj->get_data."\n";
50
51         $rpc_client->disconnect;
52

DESCRIPTION

54       Use this module to write clients accessing objects and methods exported
55       by a Event::RPC driven server.
56
57       Just connect to the server over the network, optionally with SSL and
58       user authentication, and then simply use the exported classes and
59       methods like having them locally in the client.
60
61       General information about the architecture of Event::RPC driven
62       applications is collected in the Event::RPC manpage.
63
64       The following documentation describes the client connection options in
65       detail.
66

CONFIGURATION OPTIONS

68       You need to specify at least the server hostname and TCP port to
69       connect a Event::RPC server instance. If the server requires a SSL
70       connection or user authentication you need to supply the corresponding
71       options as well, otherwise connecting will fail.
72
73       All options described here may be passed to the new() constructor of
74       Event::RPC::Client. As well you may set or modify them using set_OPTION
75       style mutators, but not after connect() was called!  All options may be
76       read using get_OPTION style accessors.
77
78   REQUIRED OPTIONS
79       These are necessary to connect the server:
80
81       server
82           This is the hostname of the server running Event::RPC::Server.  Use
83           a IP address or DNS name here.
84
85       port
86           This is the TCP port the server is listening to.
87
88   NETWORK OPTIONS
89       timeout
90           Specify a timeout (in seconds), which is applied when connecting
91           the server.
92
93   CLASS IMPORT OPTION
94       classes
95           This is reference to a list of classes which should be imported
96           into the client. You get a warning if you request a class which is
97           not exported by the server.
98
99           By default all server classes are imported. Use this feature if
100           your server exports a huge list of classes, but your client doesn't
101           need all of them. This saves memory in the client and connect
102           performance increases.
103
104       class_map
105           Optionally you can map the class names from the server to a
106           different name on the local client using the class_map hash.
107
108           This is necessary if you like to use the same classes locally and
109           remotely. Imported classes from the server are by default
110           registered under the same name on the client, so this conflicts
111           with local classes named identically.
112
113           On the client you access the remote classes under the name assigned
114           in the class map. For example with this map
115
116             class_map => { "Event::ExecFlow::Job" => "_srv::Event::ExecFlow::Job" }
117
118           you need to write this on the client, if you like to create an
119           object remotely on the server:
120
121             my $server_job = _srv::Event::ExecFlow::Job->new ( ... );
122
123           and this to create an object on the client:
124
125             my $client_job = Event::ExecFlow::Job->new ( ... );
126
127           The server knows nothing of the renaming on client side, so you
128           still write this on the server to create objects there:
129
130             my $job = Event::ExecFlow::Job->new ( ... );
131
132   SSL OPTIONS
133       If the server accepts only SSL connections you need to enable ssl here
134       in the client as well. By default the SSL connection will be
135       established without any peer verification, which makes Man-in-the-
136       Middle attacks possible. If you want to prevent that, you need to set
137       either ssl_ca_file or ssl_ca_path option.
138
139       ssl Set this option to 1 to encrypt the network connection using SSL.
140
141       ssl_ca_file
142           Path to the the Certificate Authority's certificate file (ca.crt),
143           your server key was signed with.
144
145       ssl_ca_path
146           Path of a directory containing several trusted certificates with a
147           proper index. Please refer to the OpenSSL documentation for details
148           about setting up such a directory.
149
150       ssl_opts
151           This optional parameter takes a hash reference of options passed to
152           IO::Socket::SSL->new(...) to have more control over the SSL
153           connection. For example you can set the 'SSL_verifycn_name' here if
154           the server certificate common name doesn't match to the hostname
155           you use to resolve the server IP or use you have to use a static
156           server IP address or something like that.
157
158   AUTHENTICATION OPTIONS
159       If the server requires user authentication you need to set the
160       following options:
161
162       auth_user
163           A valid username.
164
165       auth_pass
166           The corresponding password, encrypted using Perl's crypt()
167           function, using the username as the salt.
168
169           Event::RPC has a convenience function for generating such a crypted
170           password, although it's currently just a wrapper around Perl's
171           builtin crypt() function, but probably this changes someday, so
172           better use this method:
173
174             $crypted_pass = Event::RPC->crypt($user, $pass);
175
176       If the passed credentials are invalid the Event::RPC::Client->connect()
177       method throws a correspondent exception.
178
179   MESSAGE FORMAT OPTIONS
180       Event::RPC supports different CPAN modules for data serialisation,
181       named "message formats" here:
182
183         SERL -- Sereal::Encoder, Sereal::Decoder
184         CBOR -- CBOR::XS
185         JSON -- JSON::XS
186         STOR -- Storable
187
188       Server and client negotiate automatically which format is best to use.
189       The server sends a list of supported formats to the client which takes
190       the first one which is available.
191
192       For the client there is one option to influence this format negotiation
193       mechanism:
194
195       insecure_msg_fmt_ok
196           The Storable module is known to be insecure, so it should be taken
197           as the last option only. By default the Client would do so. You can
198           prevent that by setting this option explicitely to 0. It's enabled
199           by default. Most likely the connection will fail in that case,
200           because the server only will offer Storable if no other serialiser
201           is available.
202
203   ERROR HANDLING
204       Any exceptions thrown on the server during execution of a remote method
205       will result in a corresponding exception on the client. So you can use
206       normal exception handling with eval {} when executing remote methods.
207
208       But besides this the network connection between your client and the
209       server may break at any time. This raises an exception as well, but you
210       can override this behaviour with the following attribute:
211
212       error_cb
213           This subroutine is called if any error occurs in the network
214           communication between the client and the server. The actual
215           Event::RPC::Client object and an error string are passed as
216           arguments.
217
218           This is no generic exception handler for exceptions thrown from the
219           executed methods on the server! If you like to catch such
220           exceptions you need to put an eval {} around your method calls, as
221           you would do for local method calls.
222
223           If you don't specify an error_cb an exception is thrown instead.
224

METHODS

226       $rpc_client->connect
227           This establishes the configured connection to the server. An
228           exception is thrown if something goes wrong, e.g. server not
229           available, credentials are invalid or something like this.
230
231       $rpc_client->disconnect
232           Closes the connection to the server. You may omit explicit
233           disconnecting since it's done automatically once the
234           Event::RPC::Client object gets destroyed.
235
236       $rpc_client->set_max_packet_size ( $bytes )
237           By default Event::RPC does not handle network packages which exceed
238           2 GB in size (was 4 MB with version 1.04 and earlier).
239
240           You can change this value using this method at any time, but 4 GB
241           is the maximum. An attempt of the server to send a bigger packet
242           will be aborted and reported as an exception on the client and
243           logged as an error message on the server.
244
245           Note: you have to set the same value on client and server side!
246
247       $rpc_client->get_max_packet_size
248           Returns the currently active max packet size.
249

READY ONLY ATTRIBUTES

251       $rpc_client->get_server_version
252           Returns the Event::RPC version number of the server after
253           connecting.
254
255       $rpc_client->get_server_protocol
256           Returns the Event::RPC protocol number of the server after
257           connecting.
258
259       $rpc_client->get_client_version
260           Returns the Event::RPC version number of the client.
261
262       $rpc_client->get_client_protocol
263           Returns the Event::RPC protocol number of the client.
264

AUTHORS

266         Jörn Reder <joern AT zyn.de>
267
269       Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.
270
271       This library is free software; you can redistribute it and/or modify it
272       under the same terms as Perl itself.
273
274
275
276perl v5.34.0                      2022-01-21             Event::RPC::Client(3)
Impressum