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 auth_required => 1,
35 auth_passwd_href => { $user => Event::RPC->crypt($user,$pass) },
36 auth_module => Your::Own::Auth::Module->new(...),
37 loop => Event::RPC::Loop::Event->new(),
39 host => "localhost",
41 load_modules => 1,
42 auto_reload_modules => 1,
43 connection_hook => sub { ... },
44 );
45 $server->start;
47 # and later from inside your server implementation
49 Event::RPC::Server->instance->stop;
50
52 Use this module to add a simple to use RPC mechanism to your event
53 driven server application.
54 Just create an instance of the Event::RPC::Server class with a bunch of
56 required settings. Then enter the main event loop through it, or take
57 control over the main loop on your own if you like (refer to the
58 MAINLOOP chapter for details).
59 General information about the architecture of Event::RPC driven
61 applications is collected in the Event::RPC manpage.
62
64 All options described here may be passed to the new() constructor of
65 Event::RPC::Server. As well you may set or modify them using set_OPTION
66 style mutators, but not after start() or setup_listeners() was called!
67 All options may be read using get_OPTION style accessors.
68 REQUIRED OPTIONS
70 If you just pass the required options listed beyond you have a RPC
71 server which listens to a network port and allows everyone connecting
72 to it to access a well defined list of classes and methods resp. using
73 the correspondent server objects.
74 There is no authentication or encryption active in this minimal
76 configuration, so aware that this may be a big security risk! Adding
77 security is easy, refer to the chapters about SSL and authentication.
78 These are the required options:
80 port
82 TCP port number of the RPC listener.
83 classes
85 This is a hash ref with the following structure:
86 classes => {
88 "Class1" => {
89 new => "_constructor",
90 simple_method => 1,
91 object_returner => "_object",
92 },
93 "Class2" => { ... },
94 ...
95 },
96 Each class which should be accessable for clients needs to be
98 listed here at the first level, assigned a hash of methods allowed
99 to be called. Event::RPC disuinguishes three types of methods by
100 classifying their return value:
101 Constructors
103 A constructor method creates a new object of the corresponding
104 class and returns it. You need to assign the string
105 "_constructor" to the method entry to mark a method as a
106 constructor.
107 Simple methods
109 What's simple about these methods is their return value: it's a
110 scalar, array, hash or even any complex reference structure
111 (Ok, not simple anymore ;), but in particular it returns NO
112 objects, because this needs to handled specially (see below).
113 Declare simple methods by assigning 1 in the method
115 declaration.
116 Object returners
118 Methods which return objects need to be declared by assigning
119 "_object" to the method name here. They're not bound to return
120 just one scalar object reference and may return an array or
121 list reference with a bunch of objects as well.
122 SSL OPTIONS
124 The client/server protocol of Event::RPC is not encrypted by default,
125 so everyone listening on your network can read or even manipulate data.
126 To prevent this efficiently you can enable SSL encryption. Event::RPC
127 uses the IO::Socket::SSL Perl module for this.
128 First you need to generate a server key and certificate for your server
130 using the openssl command which is part of the OpenSSL distribution,
131 e.g. by issueing these commands (please refer to the manpage of openssl
132 for details - this is a very rough example, which works in general, but
133 probably you want to tweak some parameters):
134 % openssl genrsa -des3 -out server.key 1024
136 % openssl req -new -key server.key -out server.csr
137 % openssl x509 -req -days 3600 -in server.csr \
138 -signkey server.key -out server.crt
139 After executing these commands you have the following files
141 server.crt
143 server.key
144 server.csr
145 Event::RPC needs the first two of them to operate with SSL encryption.
147 To enable SSL encryption you need to pass the following options to the
149 constructor:
150 ssl The ssl option needs to be set to 1.
152 ssl_key_file
154 This is the filename of the server.key you generated with the
155 openssl command.
156 ssl_cert_file
158 This is the filename of the server.crt file you generated with the
159 openssl command.
160 ssl_passwd_cb
162 Your server key is encrypted with a password you entered during the
163 key creation process described above. This callback must return it.
164 Depending on how critical your application is you probably must
165 request the password from the user during server startup or place
166 it into a more or less secured file. For testing purposes you can
167 specify a simple anonymous sub here, which just returns the
168 password, e.g.
169 ssl_passwd_cb => sub { return "topsecret" }
171 But note: having the password in plaintext in your program code is
173 insecure!
174 AUTHENTICATION OPTIONS
176 SSL encryption is fine, now it's really hard for an attacker to listen
177 or modify your network communication. But without any further
178 configuration any user on your network is able to connect to your
179 server. To prevent this users resp. connections to your server needs to
180 be authenticated somehow.
181 Since version 0.87 Event::RPC has an API to delegate authentication
183 tasks to a module, which can be implemented outside Event::RPC. To be
184 compatible with prior releases it ships the module
185 Event::RPC::AuthPasswdHash which implements the old behaviour
186 transparently.
187 This default implementation is a simple user/password based model. For
189 now this controls just the right to connect to your server, so knowing
190 one valid user/password pair is enough to access all exported methods
191 of your server. Probably a more differentiated model will be added
192 later which allows granting access to a subset of exported methods only
193 for each user who is allowed to connect.
194 The following options control the authentication:
196 auth_required
198 Set this to 1 to enable authentication and nobody can connect your
199 server until he passes a valid user/password pair.
200 auth_passwd_href
202 If you like to use the builtin Event::RPC::AuthPasswdHash module
203 simply set this attribute. If you decide to use auth_module
204 (explained beyound) it's not necessary.
205 auth_passwd_href is a hash of valid user/password pairs. The
207 password stored here needs to be encrypted using Perl's crypt()
208 function, using the username as the salt.
209 Event::RPC has a convenience function for generating such a crypted
211 password, although it's currently just a 1:1 wrapper around Perl's
212 builtin crypt() function, but probably this changes someday, so
213 better use this method:
214 $crypted_pass = Event::RPC->crypt($user, $pass);
216 This is a simple example of setting up a proper auth_passwd_href
218 with two users:
219 auth_passwd_href => {
221 fred => Event::RPC->crypt("fred", $freds_password),
222 nick => Event::RPC->crypt("nick", $nicks_password),
223 },
224 auth_module
226 If you like to implement a more complex authentication method
227 yourself you may set the auth_module attribute to an instance of
228 your class. For now your implementation just needs to have this
229 method:
230 $auth_module->check_credentials($user, $pass)
232 Aware that $pass is encrypted as explained above, so your original
234 password needs to by crypted using Event::RPC->crypt as well, at
235 least for the comparison itself.
236 Note: you can use the authentication module without SSL but aware that
238 an attacker listening to the network connection will be able to grab
239 the encrypted password token and authenticate himself with it to the
240 server (replay attack). Probably a more sophisticated
241 challenge/response mechanism will be added to Event::RPC to prevent
242 this. But you definitely should use SSL encryption in a critical
243 environment anyway, which renders grabbing the password from the net
244 impossible.
245 LOGGING OPTIONS
247 Event::RPC has some logging abilities, primarily for debugging
248 purposes. It uses a logger for this, which is an object implementing
249 the Event::RPC::Logger interface. The documentation of
250 Event::RPC::Logger describes this interface and Event::RPC's logging
251 facilities in general.
252 logger
254 To enable logging just pass such an Event::RPC::Logger object to
255 the constructor.
256 start_log_listener
258 Additionally Event::RPC can start a log listener on the server's
259 port number incremented by 1. All clients connected to this port
260 (e.g. by using telnet) get the server's log output.
261 Note: currently the logging port supports neither SSL nor
263 authentication, so be careful enabling the log listener in critical
264 environments.
265 MAINLOOP OPTIONS
267 Event::RPC derived it's name from the fact that it follows the event
268 driven paradigm. There are several toolkits for Perl which allow event
269 driven software development. Event::RPC has an abstraction layer for
270 this and thus should be able to work with any toolkit.
271 loop
273 This option takes an object of the loop abstraction layer you want
274 to use. Currently the following modules are implemented:
275 Event::RPC::Loop::Event Use the Event module
277 Event::RPC::Loop::Glib Use the Glib module
278 If loop isn't set, Event::RPC::Server tries all supported modules
280 in a row and aborts the program, if no module was found.
281 More modules will be added in the future. If you want to implement
283 one just take a look at the code in the modules above: it's really
284 easy and I appreciate your patch. The interface is roughly
285 described in the documentation of Event::RPC::Loop.
286 If you use the Event::RPC->start() method as described in the SYNOPSIS
288 Event::RPC will enter the correspondent main loop for you. If you want
289 to have full control over the main loop, use this method to setup all
290 necessary Event::RPC listeners:
291 $rpc_server->setup_listeners();
293 and manage the main loop stuff on your own.
295 MISCELLANEOUS OPTIONS
297 host
298 By default the network listeners are bound to all interfaces in the
299 system. Use the host option to bind to a specific interface, e.g.
300 "localhost" if you efficently want to prevent network clients from
301 accessing your server.
302 load_modules
304 Control whether the class module files should be loaded
305 automatically when first accesed by a client. This options defaults
306 to true, for backward compatibility reasons.
307 auto_reload_modules
309 If this option is set Event::RPC::Server will check on each method
310 call if the corresponding module changed on disk and reloads it
311 automatically. Of course this has an effect on performance, but
312 it's very useful during development. You probably shouldn't enable
313 this in production environments.
314 connection_hook
316 This callback is called on each connection / disconnection with two
317 arguments: the Event::RPC::Connection object and a string
318 containing either "connect" or "disconnect" depending what's
319 currently happening with this connection.
320
322 The following methods are publically available:
323 Event::RPC::Server->instance
325 This returns the latest created Event::RPC::Server instance
326 (usually you have only one instance in one program).
327 $rpc_server->start
329 Start the mainloop of your Event::RPC::Server.
330 $rpc_server->stop
332 Stops the mainloop which usually means, that the server exits, as
333 long you don't do more sophisticated mainloop stuff by your own.
334 $rpc_server->setup_listeners
336 This method initializes all networking listeners needed for
337 Event::RPC::Server to work, using the configured loop module. Use
338 this method if you don't use the start() method but manage the
339 mainloop on your own.
340 $rpc_server->log ( [$level,] $msg )
342 Convenience method for logging. It simply passes the arguments to
343 the configured logger's log() method.
344 $rpc_server->get_clients_connected
346 Returns the number of currently connected Event::RPC clients.
347 $rpc_server->get_log_clients_connected
349 Returns the number of currently connected logging clients.
350 $rpc_server->get_active_connection
352 This returns the currently active Event::RPC::Connection object
353 representing the connection resp. the client which currently
354 requests method invocation. This is undef if no client call is
355 active.
356
358 JA~Xrn Reder <joern at zyn dot de>
359
361 Copyright (C) 2002-2006 by Joern Reder, All Rights Reserved.
362 This library is free software; you can redistribute it and/or modify it
364 under the same terms as Perl itself.
365
367 Hey! The above document had some coding errors, which are explained
368 below:
369 Around line 781:
371 You forgot a '=back' before '=head1'
372perl v5.12.0 2008-10-25 Event::RPC::Server(3)