Event::RPC::Server(3) User Contributed Perl DocumentationEvent::RPC::Server(3)NAMEEvent::RPC::Server - Simple API for event driven RPC servers
SYNOPSIS
use Event::RPC::Server;
use My::TestModule;
my $server = Event::RPC::Server->new (
#-- Required arguments
port => 8888,
classes => {
"My::TestModule" => {
new => "_constructor",
get_data => 1,
set_data => 1,
clone => "_object",
},
},
#-- Optional arguments
name => "Test server",
logger => Event::RPC::Logger->new(),
start_log_listener => 1,
ssl => 1
ssl_key_file => "server.key",
ssl_cert_file => "server.crt",
ssl_passwd_cb => sub { "topsecret" },
auth_required => 1,
auth_passwd_href => { $user => Event::RPC->crypt($user,$pass) },
auth_module => Your::Own::Auth::Module->new(...),
loop => Event::RPC::Loop::Event->new(),
host => "localhost",
load_modules => 1,
auto_reload_modules => 1,
connection_hook => sub { ... },
);
$server->start;
# and later from inside your server implementation
Event::RPC::Server->instance->stop;
DESCRIPTION
Use this module to add a simple to use RPC mechanism to your event
driven server application.
Just create an instance of the Event::RPC::Server class with a bunch of
required settings. Then enter the main event loop through it, or take
control over the main loop on your own if you like (refer to the
MAINLOOP chapter for details).
General information about the architecture of Event::RPC driven
applications is collected in the Event::RPC manpage.
CONFIGURATION OPTIONS
All options described here may be passed to the new() constructor of
Event::RPC::Server. As well you may set or modify them using set_OPTION
style mutators, but not after start() or setup_listeners() was called!
All options may be read using get_OPTION style accessors.
REQUIRED OPTIONS
If you just pass the required options listed beyond you have a RPC
server which listens to a network port and allows everyone connecting
to it to access a well defined list of classes and methods resp. using
the correspondent server objects.
There is no authentication or encryption active in this minimal
configuration, so aware that this may be a big security risk! Adding
security is easy, refer to the chapters about SSL and authentication.
These are the required options:
port
TCP port number of the RPC listener.
classes
This is a hash ref with the following structure:
classes => {
"Class1" => {
new => "_constructor",
simple_method => 1,
object_returner => "_object",
},
"Class2" => { ... },
...
},
Each class which should be accessable for clients needs to be
listed here at the first level, assigned a hash of methods allowed
to be called. Event::RPC disuinguishes three types of methods by
classifying their return value:
Constructors
A constructor method creates a new object of the corresponding
class and returns it. You need to assign the string
"_constructor" to the method entry to mark a method as a
constructor.
Simple methods
What's simple about these methods is their return value: it's a
scalar, array, hash or even any complex reference structure
(Ok, not simple anymore ;), but in particular it returns NO
objects, because this needs to handled specially (see below).
Declare simple methods by assigning 1 in the method
declaration.
Object returners
Methods which return objects need to be declared by assigning
"_object" to the method name here. They're not bound to return
just one scalar object reference and may return an array or
list reference with a bunch of objects as well.
SSL OPTIONS
The client/server protocol of Event::RPC is not encrypted by default,
so everyone listening on your network can read or even manipulate data.
To prevent this efficiently you can enable SSL encryption. Event::RPC
uses the IO::Socket::SSL Perl module for this.
First you need to generate a server key and certificate for your server
using the openssl command which is part of the OpenSSL distribution,
e.g. by issueing these commands (please refer to the manpage of openssl
for details - this is a very rough example, which works in general, but
probably you want to tweak some parameters):
% openssl genrsa -des3 -out server.key 1024
% openssl req -new -key server.key -out server.csr
% openssl x509 -req -days 3600 -in server.csr \
-signkey server.key -out server.crt
After executing these commands you have the following files
server.crt
server.key
server.csr
Event::RPC needs the first two of them to operate with SSL encryption.
To enable SSL encryption you need to pass the following options to the
constructor:
ssl The ssl option needs to be set to 1.
ssl_key_file
This is the filename of the server.key you generated with the
openssl command.
ssl_cert_file
This is the filename of the server.crt file you generated with the
openssl command.
ssl_passwd_cb
Your server key is encrypted with a password you entered during the
key creation process described above. This callback must return it.
Depending on how critical your application is you probably must
request the password from the user during server startup or place
it into a more or less secured file. For testing purposes you can
specify a simple anonymous sub here, which just returns the
password, e.g.
ssl_passwd_cb => sub { return "topsecret" }
But note: having the password in plaintext in your program code is
insecure!
AUTHENTICATION OPTIONS
SSL encryption is fine, now it's really hard for an attacker to listen
or modify your network communication. But without any further
configuration any user on your network is able to connect to your
server. To prevent this users resp. connections to your server needs to
be authenticated somehow.
Since version 0.87 Event::RPC has an API to delegate authentication
tasks to a module, which can be implemented outside Event::RPC. To be
compatible with prior releases it ships the module
Event::RPC::AuthPasswdHash which implements the old behaviour
transparently.
This default implementation is a simple user/password based model. For
now this controls just the right to connect to your server, so knowing
one valid user/password pair is enough to access all exported methods
of your server. Probably a more differentiated model will be added
later which allows granting access to a subset of exported methods only
for each user who is allowed to connect.
The following options control the authentication:
auth_required
Set this to 1 to enable authentication and nobody can connect your
server until he passes a valid user/password pair.
auth_passwd_href
If you like to use the builtin Event::RPC::AuthPasswdHash module
simply set this attribute. If you decide to use auth_module
(explained beyound) it's not necessary.
auth_passwd_href is a hash of valid user/password pairs. The
password stored here needs to be encrypted using Perl's crypt()
function, using the username as the salt.
Event::RPC has a convenience function for generating such a crypted
password, although it's currently just a 1:1 wrapper around Perl's
builtin crypt() function, but probably this changes someday, so
better use this method:
$crypted_pass = Event::RPC->crypt($user, $pass);
This is a simple example of setting up a proper auth_passwd_href
with two users:
auth_passwd_href => {
fred => Event::RPC->crypt("fred", $freds_password),
nick => Event::RPC->crypt("nick", $nicks_password),
},
auth_module
If you like to implement a more complex authentication method
yourself you may set the auth_module attribute to an instance of
your class. For now your implementation just needs to have this
method:
$auth_module->check_credentials($user, $pass)
Aware that $pass is encrypted as explained above, so your original
password needs to by crypted using Event::RPC->crypt as well, at
least for the comparison itself.
Note: you can use the authentication module without SSL but aware that
an attacker listening to the network connection will be able to grab
the encrypted password token and authenticate himself with it to the
server (replay attack). Probably a more sophisticated
challenge/response mechanism will be added to Event::RPC to prevent
this. But you definitely should use SSL encryption in a critical
environment anyway, which renders grabbing the password from the net
impossible.
LOGGING OPTIONS
Event::RPC has some logging abilities, primarily for debugging
purposes. It uses a logger for this, which is an object implementing
the Event::RPC::Logger interface. The documentation of
Event::RPC::Logger describes this interface and Event::RPC's logging
facilities in general.
logger
To enable logging just pass such an Event::RPC::Logger object to
the constructor.
start_log_listener
Additionally Event::RPC can start a log listener on the server's
port number incremented by 1. All clients connected to this port
(e.g. by using telnet) get the server's log output.
Note: currently the logging port supports neither SSL nor
authentication, so be careful enabling the log listener in critical
environments.
MAINLOOP OPTIONS
Event::RPC derived it's name from the fact that it follows the event
driven paradigm. There are several toolkits for Perl which allow event
driven software development. Event::RPC has an abstraction layer for
this and thus should be able to work with any toolkit.
loop
This option takes an object of the loop abstraction layer you want
to use. Currently the following modules are implemented:
Event::RPC::Loop::Event Use the Event module
Event::RPC::Loop::Glib Use the Glib module
If loop isn't set, Event::RPC::Server tries all supported modules
in a row and aborts the program, if no module was found.
More modules will be added in the future. If you want to implement
one just take a look at the code in the modules above: it's really
easy and I appreciate your patch. The interface is roughly
described in the documentation of Event::RPC::Loop.
If you use the Event::RPC->start() method as described in the SYNOPSIS
Event::RPC will enter the correspondent main loop for you. If you want
to have full control over the main loop, use this method to setup all
necessary Event::RPC listeners:
$rpc_server->setup_listeners();
and manage the main loop stuff on your own.
MISCELLANEOUS OPTIONS
host
By default the network listeners are bound to all interfaces in the
system. Use the host option to bind to a specific interface, e.g.
"localhost" if you efficently want to prevent network clients from
accessing your server.
load_modules
Control whether the class module files should be loaded
automatically when first accesed by a client. This options defaults
to true, for backward compatibility reasons.
auto_reload_modules
If this option is set Event::RPC::Server will check on each method
call if the corresponding module changed on disk and reloads it
automatically. Of course this has an effect on performance, but
it's very useful during development. You probably shouldn't enable
this in production environments.
connection_hook
This callback is called on each connection / disconnection with two
arguments: the Event::RPC::Connection object and a string
containing either "connect" or "disconnect" depending what's
currently happening with this connection.
METHODS
The following methods are publically available:
Event::RPC::Server->instance
This returns the latest created Event::RPC::Server instance
(usually you have only one instance in one program).
$rpc_server->start
Start the mainloop of your Event::RPC::Server.
$rpc_server->stop
Stops the mainloop which usually means, that the server exits, as
long you don't do more sophisticated mainloop stuff by your own.
$rpc_server->setup_listeners
This method initializes all networking listeners needed for
Event::RPC::Server to work, using the configured loop module. Use
this method if you don't use the start() method but manage the
mainloop on your own.
$rpc_server->log ( [$level,] $msg )
Convenience method for logging. It simply passes the arguments to
the configured logger's log() method.
$rpc_server->get_clients_connected
Returns the number of currently connected Event::RPC clients.
$rpc_server->get_log_clients_connected
Returns the number of currently connected logging clients.
$rpc_server->get_active_connection
This returns the currently active Event::RPC::Connection object
representing the connection resp. the client which currently
requests method invocation. This is undef if no client call is
active.
AUTHORS
JA~Xrn Reder <joern at zyn dot de>
COPYRIGHT AND LICENSE
Copyright (C) 2002-2006 by Joern Reder, All Rights Reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 781:
You forgot a '=back' before '=head1'
perl v5.14.1 2008-10-25 Event::RPC::Server(3)
