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

NAME

6       Event::RPC::Server - Simple API for event driven RPC servers
7

SYNOPSIS

9         use Event::RPC::Server;
10         use My::TestModule;
11
12         my $server = Event::RPC::Server->new (
13             #-- Required arguments
14             port               => 8888,
15             classes            => {
16               "My::TestModule" => {
17                 new      => "_constructor",
18                 get_data => 1,
19                 set_data => 1,
20                 clone    => "_object",
21               },
22             },
23
24             #-- Optional arguments
25             name                => "Test server",
26             logger              => Event::RPC::Logger->new(),
27             start_log_listener  => 1,
28
29             ssl                 => 1
30             ssl_key_file        => "server.key",
31             ssl_cert_file       => "server.crt",
32             ssl_passwd_cb       => sub { "topsecret" },
33             ssl_opts            => { ... },
34
35             auth_required       => 1,
36             auth_passwd_href    => { $user => Event::RPC->crypt($user,$pass) },
37             auth_module         => Your::Own::Auth::Module->new(...),
38
39             loop                => Event::RPC::Loop::Event->new(),
40
41             host                => "localhost",
42             load_modules        => 1,
43             auto_reload_modules => 1,
44             connection_hook     => sub { ... },
45
46             message_formats     => [qw/ SERL CBOR JSON STOR /],
47             insecure_msg_fmt_ok => 1,
48         );
49
50         $server->set_max_packet_size(2*1024*1024*1024);
51
52         # start server and event loop
53         $server->start;
54
55         # or prepare server start if you like to control event loop by yourself
56         $server->prepare;
57
58         # and later from inside your server implementation
59         Event::RPC::Server->instance->stop;
60

DESCRIPTION

62       Use this module to add a simple to use RPC mechanism to your event
63       driven server application.
64
65       Just create an instance of the Event::RPC::Server class with a bunch of
66       required settings. Then enter the main event loop through it, or take
67       control over the main loop on your own if you like (refer to the
68       MAINLOOP chapter for details).
69
70       General information about the architecture of Event::RPC driven
71       applications is collected in the Event::RPC manpage.
72

CONFIGURATION OPTIONS

74       All options described here may be passed to the new() constructor of
75       Event::RPC::Server. As well you may set or modify them using set_OPTION
76       style mutators, but not after start() or setup_listeners() was called!
77       All options may be read using get_OPTION style accessors.
78
79   REQUIRED OPTIONS
80       If you just pass the required options listed beyond you have a RPC
81       server which listens to a network port and allows everyone connecting
82       to it to access a well defined list of classes and methods resp. using
83       the correspondent server objects.
84
85       There is no authentication or encryption active in this minimal
86       configuration, so aware that this may be a big security risk!  Adding
87       security is easy, refer to the chapters about SSL and authentication.
88
89       These are the required options:
90
91       port
92           TCP port number of the RPC listener.
93
94       classes
95           This is a hash ref with the following structure:
96
97             classes => {
98               "Class1" => {
99                 new             => "_constructor",
100                 simple_method   => 1,
101                 object_returner => "_object",
102               },
103               "Class2" => { ... },
104               ...
105             },
106
107           Each class which should be accessible for clients needs to be
108           listed here at the first level, assigned a hash of methods allowed
109           to be called. Event::RPC disuinguishes three types of methods by
110           classifying their return value:
111
112           Constructors
113               A constructor method creates a new object of the corresponding
114               class and returns it. You need to assign the string
115               "_constructor" to the method entry to mark a method as a
116               constructor.
117
118           Singleton constructors
119               For singleton classes the method which returns the singleton
120               instance should be declared with "_singleton". This way the
121               server takes care that references get never destroyed on server
122               side.
123
124           Simple methods
125               What's simple about these methods is their return value: it's a
126               scalar, array, hash or even any complex reference structure
127               (Ok, not simple anymore ;), but in particular it returns NO
128               objects, because this needs to handled specially (see below).
129
130               Declare simple methods by assigning 1 in the method
131               declaration.
132
133           Object returners
134               Methods which return objects need to be declared by assigning
135               "_object" to the method name here. They're not bound to return
136               just one scalar object reference and may return an array or
137               list reference with a bunch of objects as well.
138
139   SSL OPTIONS
140       The client/server protocol of Event::RPC is not encrypted by default,
141       so everyone listening on your network can read or even manipulate data.
142       To prevent this efficiently you can enable SSL encryption.  Event::RPC
143       uses the IO::Socket::SSL Perl module for this.
144
145       First you need to generate a server key and certificate for your server
146       using the openssl command which is part of the OpenSSL distribution,
147       e.g. by issueing these commands (please refer to the manpage of openssl
148       for details - this is a very rough example, which works in general, but
149       probably you want to tweak some parameters):
150
151         % openssl genrsa -des3 -out server.key 1024
152         % openssl req -new -key server.key -out server.csr
153         % openssl x509 -req -days 3600 -in server.csr \
154                   -signkey server.key -out server.crt
155
156       After executing these commands you have the following files
157
158         server.crt
159         server.key
160         server.csr
161
162       Event::RPC needs the first two of them to operate with SSL encryption.
163
164       To enable SSL encryption you need to pass the following options to the
165       constructor:
166
167       ssl The ssl option needs to be set to 1.
168
169       ssl_key_file
170           This is the filename of the server.key you generated with the
171           openssl command.
172
173       ssl_cert_file
174           This is the filename of the server.crt file you generated with the
175           openssl command.
176
177       ssl_passwd_cb
178           Your server key is encrypted with a password you entered during the
179           key creation process described above. This callback must return it.
180           Depending on how critical your application is you probably must
181           request the password from the user during server startup or place
182           it into a more or less secured file. For testing purposes you can
183           specify a simple anonymous sub here, which just returns the
184           password, e.g.
185
186             ssl_passwd_cb => sub { return "topsecret" }
187
188           But note: having the password in plaintext in your program code is
189           insecure!
190
191       ssl_opts
192           This optional parameter takes a hash reference of options passed to
193           IO::Socket::SSL->new(...) to have more control over the server SSL
194           listener.
195
196   AUTHENTICATION OPTIONS
197       SSL encryption is fine, now it's really hard for an attacker to listen
198       or modify your network communication. But without any further
199       configuration any user on your network is able to connect to your
200       server. To prevent this users resp. connections to your server needs to
201       be authenticated somehow.
202
203       Since version 0.87 Event::RPC has an API to delegate authentication
204       tasks to a module, which can be implemented outside Event::RPC.  To be
205       compatible with prior releases it ships the module
206       Event::RPC::AuthPasswdHash which implements the old behaviour
207       transparently.
208
209       This default implementation is a simple user/password based model. For
210       now this controls just the right to connect to your server, so knowing
211       one valid user/password pair is enough to access all exported methods
212       of your server. Probably a more differentiated model will be added
213       later which allows granting access to a subset of exported methods only
214       for each user who is allowed to connect.
215
216       The following options control the authentication:
217
218       auth_required
219           Set this to 1 to enable authentication and nobody can connect your
220           server until he passes a valid user/password pair.
221
222       auth_passwd_href
223           If you like to use the builtin Event::RPC::AuthPasswdHash module
224           simply set this attribute. If you decide to use auth_module
225           (explained beyound) it's not necessary.
226
227           auth_passwd_href is a hash of valid user/password pairs. The
228           password stored here needs to be encrypted using Perl's crypt()
229           function, using the username as the salt.
230
231           Event::RPC has a convenience function for generating such a crypted
232           password, although it's currently just a 1:1 wrapper around Perl's
233           builtin crypt() function, but probably this changes someday, so
234           better use this method:
235
236             $crypted_pass = Event::RPC->crypt($user, $pass);
237
238           This is a simple example of setting up a proper auth_passwd_href
239           with two users:
240
241             auth_passwd_href => {
242               fred => Event::RPC->crypt("fred", $freds_password),
243               nick => Event::RPC->crypt("nick", $nicks_password),
244             },
245
246       auth_module
247           If you like to implement a more complex authentication method
248           yourself you may set the auth_module attribute to an instance of
249           your class.  For now your implementation just needs to have this
250           method:
251
252             $auth_module->check_credentials($user, $pass)
253
254           Aware that $pass is encrypted as explained above, so your original
255           password needs to by crypted using Event::RPC->crypt as well, at
256           least for the comparison itself.
257
258       Note: you can use the authentication module without SSL but aware that
259       an attacker listening to the network connection will be able to grab
260       the encrypted password token and authenticate himself with it to the
261       server (replay attack). Probably a more sophisticated
262       challenge/response mechanism will be added to Event::RPC to prevent
263       this. But you definitely should use SSL encryption in a critical
264       environment anyway, which renders grabbing the password from the net
265       impossible.
266
267   LOGGING OPTIONS
268       Event::RPC has some logging abilities, primarily for debugging
269       purposes.  It uses a logger for this, which is an object implementing
270       the Event::RPC::Logger interface. The documentation of
271       Event::RPC::Logger describes this interface and Event::RPC's logging
272       facilities in general.
273
274       logger
275           To enable logging just pass such an Event::RPC::Logger object to
276           the constructor.
277
278       start_log_listener
279           Additionally Event::RPC can start a log listener on the server's
280           port number incremented by 1. All clients connected to this port
281           (e.g. by using telnet) get the server's log output.
282
283           Note: currently the logging port supports neither SSL nor
284           authentication, so be careful enabling the log listener in critical
285           environments.
286
287   MAINLOOP OPTIONS
288       Event::RPC derived it's name from the fact that it follows the event
289       driven paradigm. There are several toolkits for Perl which allow event
290       driven software development. Event::RPC has an abstraction layer for
291       this and thus should be able to work with any toolkit.
292
293       loop
294           This option takes an object of the loop abstraction layer you want
295           to use. Currently the following modules are implemented:
296
297             Event::RPC::Loop::AnyEvent  Use the AnyEvent module
298             Event::RPC::Loop::Event     Use the Event module
299             Event::RPC::Loop::Glib      Use the Glib module
300
301           If loop isn't set, Event::RPC::Server tries all supported modules
302           in a row and aborts the program, if no module was found.
303
304           More modules will be added in the future. If you want to implement
305           one just take a look at the code in the modules above: it's really
306           easy and I appreciate your patch. The interface is roughly
307           described in the documentation of Event::RPC::Loop.
308
309       If you use the Event::RPC->start() method as described in the SYNOPSIS
310       Event::RPC will enter the correspondent main loop for you. If you want
311       to have full control over the main loop, use this method to setup all
312       necessary Event::RPC listeners:
313
314         $rpc_server->setup_listeners();
315
316       and manage the main loop stuff on your own.
317
318   MESSAGE FORMAT OPTIONS
319       Event::RPC supports different CPAN modules for data serialisation,
320       named "message formats" here:
321
322         SERL -- Sereal::Encoder, Sereal::Decoder
323         CBOR -- CBOR::XS
324         JSON -- JSON::XS
325         STOR -- Storable
326
327       Server and client negotiate automatically which format is best to use
328       but you can manipulate this behaviour with the following options:
329
330       message_formats
331           This takes an array of format identifiers from the list above.
332           Event::RPC::Server will only use / accept these formats.
333
334       insecure_msg_fmt_ok
335           The Storable module is known to be insecure. But for backward
336           compatibility reasons Event::RPC::Server accepts clients which
337           can't offer anything but Storable. You can prevent that by setting
338           this option explicitely to 0. It's enabled by default.
339
340   MISCELLANEOUS OPTIONS
341       host
342           By default the network listeners are bound to all interfaces in the
343           system. Use the host option to bind to a specific interface, e.g.
344           "localhost" if you efficiently want to prevent network clients from
345           accessing your server.
346
347       load_modules
348           Control whether the class module files should be loaded
349           automatically when first accesed by a client. This options defaults
350           to true, for backward compatibility reasons.
351
352       auto_reload_modules
353           If this option is set Event::RPC::Server will check on each method
354           call if the corresponding module changed on disk and reloads it
355           automatically. Of course this has an effect on performance, but
356           it's very useful during development. You probably shouldn't enable
357           this in production environments.
358
359       connection_hook
360           This callback is called on each connection / disconnection with two
361           arguments: the Event::RPC::Connection object and a string
362           containing either "connect" or "disconnect" depending what's
363           currently happening with this connection.
364

METHODS

366       The following methods are publically available:
367
368       Event::RPC::Server->instance
369           This returns the latest created Event::RPC::Server instance
370           (usually you have only one instance in one program).
371
372       $rpc_server->start
373           Start the mainloop of your Event::RPC::Server.
374
375       $rpc_server->stop
376           Stops the mainloop which usually means, that the server exits, as
377           long you don't do more sophisticated mainloop stuff by your own.
378
379       $rpc_server->setup_listeners
380           This method initializes all networking listeners needed for
381           Event::RPC::Server to work, using the configured loop module.  Use
382           this method if you don't use the start() method but manage the
383           mainloop on your own.
384
385       $rpc_server->log ( [$level,] $msg )
386           Convenience method for logging. It simply passes the arguments to
387           the configured logger's log() method.
388
389       $rpc_server->get_clients_connected
390           Returns the number of currently connected Event::RPC clients.
391
392       $rpc_server->get_log_clients_connected
393           Returns the number of currently connected logging clients.
394
395       $rpc_server->get_active_connection
396           This returns the currently active Event::RPC::Connection object
397           representing the connection resp. the client which currently
398           requests method invocation. This is undef if no client call is
399           active.
400
401       $rpc_client->set_max_packet_size ( $bytes )
402           By default Event::RPC does not handle network packages which exceed
403           2 GB in size (was 4 MB with version 1.04 and earlier).
404
405           You can change this value using this method at any time, but 4 GB
406           is the maximum. An attempt of the server to send a bigger packet
407           will be aborted and reported as an exception on the client and
408           logged as an error message on the server.
409
410           Note: you have to set the same value on client and server side!
411
412       $rpc_client->get_max_packet_size
413           Returns the currently active max packet size.
414

AUTHORS

416         Jörn Reder <joern AT zyn.de>
417
419       Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.
420
421       This library is free software; you can redistribute it and/or modify it
422       under the same terms as Perl itself.
423
424
425
426perl v5.36.0                      2023-01-20             Event::RPC::Server(3)
Impressum