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" },
             ssl_opts            => { ... },

             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 { ... },

             message_formats     => [qw/ SERL CBOR JSON STOR /],
             insecure_msg_fmt_ok => 1,
         );

         $server->set_max_packet_size(2*1024*1024*1024);

         # start server and event loop
         $server->start;

         # or prepare server start if you like to control event loop by yourself
         $server->prepare;

         # 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.

           Singleton constructors
               For singleton classes the method which returns the singleton instance should be
               declared with "_singleton". This way the server takes care that references get
               never destroyed on server side.

           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 issuing 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!

       ssl_opts
           This optional parameter takes a hash reference of options passed to
           IO::Socket::SSL->new(...) to have more control over the server SSL listener.

   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.

   MESSAGE FORMAT OPTIONS
       Event::RPC supports different CPAN modules for data serialisation, named "message formats"
       here:

         SERL -- Sereal::Encoder, Sereal::Decoder
         CBOR -- CBOR::XS
         JSON -- JSON::XS
         STOR -- Storable

       Server and client negotiate automatically which format is best to use but you can
       manipulate this behaviour with the following options:

       message_formats
           This takes an array of format identifiers from the list above. Event::RPC::Server will
           only use / accept these formats.

       insecure_msg_fmt_ok
           The Storable module is known to be insecure. But for backward compatibility reasons
           Event::RPC::Server accepts clients which can't offer anything but Storable. You can
           prevent that by setting this option explicitly to 0. It's enabled by default.

   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

         Jörn Reder <joern AT zyn.de>

COPYRIGHT AND LICENSE

       Copyright (C) 2005-2015 by Jörn Reder <joern AT zyn.de>.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.