1Event::RPC::Client(3) User Contributed Perl DocumentationEvent::RPC::Client(3)
2
6 Event::RPC::Client - Client API to connect to Event::RPC Servers
7
9 use Event::RPC::Client;
10 my $rpc_client = Event::RPC::Client->new (
12 #-- Required arguments
13 host => "localhost",
14 port => 5555,
15 #-- Optional arguments
17 classes => [ "Event::RPC::Test" ],
18 class_map => { "Event::RPC::Test" => "My::Event::RPC::Test" },
19 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 timeout => 10,
26 auth_user => "fred",
28 auth_pass => Event::RPC->crypt("fred",$password),
29 insecure_msg_fmt_ok => 1,
31 error_cb => sub {
33 my ($client, $error) = @_;
34 print "An RPC error occured: $error\n";
35 $client->disconnect;
36 exit;
37 },
38 );
39 $rpc_client->set_max_packet_size(2*1024*1024*1024);
41 $rpc_client->connect;
42 #-- 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 $rpc_client->disconnect;
52
54 Use this module to write clients accessing objects and methods exported
55 by a Event::RPC driven server.
56 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 General information about the architecture of Event::RPC driven
62 applications is collected in the Event::RPC manpage.
63 The following documentation describes the client connection options in
65 detail.
66
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 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 REQUIRED OPTIONS
79 These are necessary to connect the server:
80 server
82 This is the hostname of the server running Event::RPC::Server. Use
83 a IP address or DNS name here.
84 port
86 This is the TCP port the server is listening to.
87 NETWORK OPTIONS
89 timeout
90 Specify a timeout (in seconds), which is applied when connecting
91 the server.
92 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 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 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 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 On the client you access the remote classes under the name assigned
114 in the class map. For example with this map
115 class_map => { "Event::ExecFlow::Job" => "_srv::Event::ExecFlow::Job" }
117 you need to write this on the client, if you like to create an
119 object remotely on the server:
120 my $server_job = _srv::Event::ExecFlow::Job->new ( ... );
122 and this to create an object on the client:
124 my $client_job = Event::ExecFlow::Job->new ( ... );
126 The server knows nothing of the renaming on client side, so you
128 still write this on the server to create objects there:
129 my $job = Event::ExecFlow::Job->new ( ... );
131 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 ssl Set this option to 1 to encrypt the network connection using SSL.
140 ssl_ca_file
142 Path to the the Certificate Authority's certificate file (ca.crt),
143 your server key was signed with.
144 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 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 AUTHENTICATION OPTIONS
159 If the server requires user authentication you need to set the
160 following options:
161 auth_user
163 A valid username.
164 auth_pass
166 The corresponding password, encrypted using Perl's crypt()
167 function, using the username as the salt.
168 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 $crypted_pass = Event::RPC->crypt($user, $pass);
175 If the passed credentials are invalid the Event::RPC::Client->connect()
177 method throws a correspondent exception.
178 MESSAGE FORMAT OPTIONS
180 Event::RPC supports different CPAN modules for data serialisation,
181 named "message formats" here:
182 SERL -- Sereal::Encoder, Sereal::Decoder
184 CBOR -- CBOR::XS
185 JSON -- JSON::XS
186 STOR -- Storable
187 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 For the client there is one option to influence this format negotiation
193 mechanism:
194 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 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 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 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 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 If you don't specify an error_cb an exception is thrown instead.
224
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 $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 $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 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 Note: you have to set the same value on client and server side!
246 $rpc_client->get_max_packet_size
248 Returns the currently active max packet size.
249
251 $rpc_client->get_server_version
252 Returns the Event::RPC version number of the server after
253 connecting.
254 $rpc_client->get_server_protocol
256 Returns the Event::RPC protocol number of the server after
257 connecting.
258 $rpc_client->get_client_version
260 Returns the Event::RPC version number of the client.
261 $rpc_client->get_client_protocol
263 Returns the Event::RPC protocol number of the client.
264
266 Jörn Reder <joern AT zyn.de>
267
269 Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.
270 This library is free software; you can redistribute it and/or modify it
272 under the same terms as Perl itself.
273perl v5.36.0 2023-01-20 Event::RPC::Client(3)