NAME¶
Event::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->set_max_packet_size(2*1024*1024*1024);
$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 accessible 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::AnyEvent Use the AnyEvent module
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 efficiently 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.
- $rpc_client->set_max_packet_size ( $bytes )
- By default Event::RPC does not handle network packages which exceed 2 GB
in size (was 4 MB with version 1.04 and earlier).
You can change this value using this method at any time, but 4 GB is the
maximum. An attempt of the server to send a bigger packet will be aborted
and reported as an exception on the client and logged as an error message
on the server.
Note: you have to set the same value on client and server side!
- $rpc_client->get_max_packet_size
- Returns the currently active max packet size.
AUTHORS¶
Joern 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.