1Event::RPC::Server(3) User Contributed Perl DocumentationEvent::RPC::Server(3)
2
6 Event::RPC::Server - Simple API for event driven RPC servers
7
9 use Event::RPC::Server;
10 use My::TestModule;
11 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 #-- Optional arguments
25 name => "Test server",
26 logger => Event::RPC::Logger->new(),
27 start_log_listener => 1,
28 ssl => 1
30 ssl_key_file => "server.key",
31 ssl_cert_file => "server.crt",
32 ssl_passwd_cb => sub { "topsecret" },
33 ssl_opts => { ... },
34 auth_required => 1,
36 auth_passwd_href => { $user => Event::RPC->crypt($user,$pass) },
37 auth_module => Your::Own::Auth::Module->new(...),
38 loop => Event::RPC::Loop::Event->new(),
40 host => "localhost",
42 load_modules => 1,
43 auto_reload_modules => 1,
44 connection_hook => sub { ... },
45 message_formats => [qw/ SERL CBOR JSON STOR /],
47 insecure_msg_fmt_ok => 1,
48 );
49 $server->set_max_packet_size(2*1024*1024*1024);
51 # start server and event loop
53 $server->start;
54 # or prepare server start if you like to control event loop by yourself
56 $server->prepare;
57 # and later from inside your server implementation
59 Event::RPC::Server->instance->stop;
60
62 Use this module to add a simple to use RPC mechanism to your event
63 driven server application.
64 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 General information about the architecture of Event::RPC driven
71 applications is collected in the Event::RPC manpage.
72
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 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 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 These are the required options:
90 port
92 TCP port number of the RPC listener.
93 classes
95 This is a hash ref with the following structure:
96 classes => {
98 "Class1" => {
99 new => "_constructor",
100 simple_method => 1,
101 object_returner => "_object",
102 },
103 "Class2" => { ... },
104 ...
105 },
106 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 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 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 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 Declare simple methods by assigning 1 in the method
131 declaration.
132 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 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 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 % 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 After executing these commands you have the following files
157 server.crt
159 server.key
160 server.csr
161 Event::RPC needs the first two of them to operate with SSL encryption.
163 To enable SSL encryption you need to pass the following options to the
165 constructor:
166 ssl The ssl option needs to be set to 1.
168 ssl_key_file
170 This is the filename of the server.key you generated with the
171 openssl command.
172 ssl_cert_file
174 This is the filename of the server.crt file you generated with the
175 openssl command.
176 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 ssl_passwd_cb => sub { return "topsecret" }
187 But note: having the password in plaintext in your program code is
189 insecure!
190 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 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 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 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 The following options control the authentication:
217 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 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 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 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 $crypted_pass = Event::RPC->crypt($user, $pass);
237 This is a simple example of setting up a proper auth_passwd_href
239 with two users:
240 auth_passwd_href => {
242 fred => Event::RPC->crypt("fred", $freds_password),
243 nick => Event::RPC->crypt("nick", $nicks_password),
244 },
245 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 $auth_module->check_credentials($user, $pass)
253 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 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 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 logger
275 To enable logging just pass such an Event::RPC::Logger object to
276 the constructor.
277 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 Note: currently the logging port supports neither SSL nor
284 authentication, so be careful enabling the log listener in critical
285 environments.
286 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 loop
294 This option takes an object of the loop abstraction layer you want
295 to use. Currently the following modules are implemented:
296 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 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 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 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 $rpc_server->setup_listeners();
315 and manage the main loop stuff on your own.
317 MESSAGE FORMAT OPTIONS
319 Event::RPC supports different CPAN modules for data serialisation,
320 named "message formats" here:
321 SERL -- Sereal::Encoder, Sereal::Decoder
323 CBOR -- CBOR::XS
324 JSON -- JSON::XS
325 STOR -- Storable
326 Server and client negotiate automatically which format is best to use
328 but you can manipulate this behaviour with the following options:
329 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 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 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 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 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 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
366 The following methods are publically available:
367 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 $rpc_server->start
373 Start the mainloop of your Event::RPC::Server.
374 $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 $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 $rpc_server->log ( [$level,] $msg )
386 Convenience method for logging. It simply passes the arguments to
387 the configured logger's log() method.
388 $rpc_server->get_clients_connected
390 Returns the number of currently connected Event::RPC clients.
391 $rpc_server->get_log_clients_connected
393 Returns the number of currently connected logging clients.
394 $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 $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 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 Note: you have to set the same value on client and server side!
411 $rpc_client->get_max_packet_size
413 Returns the currently active max packet size.
414
416 Jörn Reder <joern AT zyn.de>
417
419 Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.
420 This library is free software; you can redistribute it and/or modify it
422 under the same terms as Perl itself.
423perl v5.36.0 2023-01-20 Event::RPC::Server(3)