Event:...Client(3pm)

💖 Event::RPC::Client — the client-side API for talking to Event::RPC servers 💖

okay bestie, this is a page from the User Contributed Perl Documentation set, and it's literally the client half of Event::RPC. Sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

Event::RPC::Client — the Client API you use to connect to Event::RPC Servers 🫶

---

✨ SYNOPSIS ✨

use Event::RPC::Client;

my $rpc_client = Event::RPC::Client->new (
  #-- Required arguments
  host => "localhost",    # or "unix/" for Unix Domain socket
  port => 5555,           # or path to Unix Domain socket

  #-- Optional arguments
  classes   => [ "Event::RPC::Test" ],
  class_map => { "Event::RPC::Test" => "My::Event::RPC::Test" },

  ssl         => 1,
  ssl_ca_file => "some/ca.crt",
  ssl_ca_path => "some/ca/dir",
  ssl_opts    => { SSL_verifycn_name => 'server-hostname' },

  timeout     => 10,

  auth_user => "fred",
  auth_pass => Event::RPC->crypt("fred",$password),

  insecure_msg_fmt_ok => 1,

  error_cb => sub {
    my ($client, $error) = @_;
    print "An RPC error occurred: $error\n";
    $client->disconnect;
    exit;
  },
);

$rpc_client->set_max_packet_size(2*1024*1024*1024);
$rpc_client->connect;

#-- And now use classes and methods to which the
#-- server allows access via RPC, here My::TestModule
#-- from the Event::RPC::Server manpage SYNPOSIS.
my $obj = My::TestModule->new( data => "foobar" );
print "obj says hello: ".$obj->hello."\n";
$obj->set_data("new foobar");
print "updated data: ".$obj->get_data."\n";

$rpc_client->disconnect;

---

✨ DESCRIPTION ✨

bestie this is THE module you use to write clients that access objects and methods exported by a server that's driven by Event::RPC. that's the whole vibe 💅

so how it goes: you just connect to the server over the network — optionally with SSL and user authentication — and then you straight-up use the exported classes and methods like they were sitting locally in your client the whole time. no cap, that's the point. ✨

if you want the big-picture tea about how Event::RPC driven applications are architected, that's all collected in the Event::RPC manpage. go read it, iykyk.

and everything below this? it's the client connection options, in detail. obsessed. 🎀

---

✨ CONFIGURATION OPTIONS ✨

at minimum you have to tell it the server hostname and TCP port so it can connect to an Event::RPC server instance. if the server needs an SSL connection or user authentication, you gotta supply those corresponding options too — otherwise the connection is just gonna fail, periodt. 💀

every option described down here can be passed to the new() constructor of Event::RPC::Client. you can also set or modify them with set_OPTION style mutators — but not after connect() was called! 🚨 and they can all be read back using get_OPTION style accessors.

REQUIRED OPTIONS 🌸

these ones are non-negotiable if you actually want to connect:

• host — the hostname of the server running Event::RPC::Server. put an IP address or a DNS name here. Set "unix/" for a Unix Domain socket. 🦋
• port — the TCP port, or the Unix Domain socket path, that the server is listening on.

NETWORK OPTIONS 🌈

• timeout — a timeout in seconds, applied when connecting to the server. ⏰

CLASS IMPORT OPTION 🧚

• classes — a reference to a list of classes that should be imported into the client. if you request a class the server doesn't export, you get a warning. ⚠️ by default all server classes are imported. use this feature when your server exports a huge list of classes but your client doesn't need all of them. it saves memory in the client and connect performance increases. slay.
• class_map — optionally you can map the class names coming from the server to a different name on the local client, using the class_map hash. this is necessary if you want to use the same classes locally and remotely. imported classes from the server are by default registered under the same name on the client, so that conflicts with local classes named identically. on the client you access the remote classes under the name assigned in the class map. for example, with this map:

class_map => { "Event::ExecFlow::Job" => "_srv::Event::ExecFlow::Job" }

you need to write this on the client if you want to create an object remotely on the server:

my $server_job = _srv::Event::ExecFlow::Job->new ( ... );

and this to create an object on the client:

my $client_job = Event::ExecFlow::Job->new ( ... );

the server knows nothing about the renaming happening on the client side, so you still write this on the server to create objects there:

my $job = Event::ExecFlow::Job->new ( ... );

SSL OPTIONS 👑

if the server only accepts SSL connections, you need to enable ssl here on the client too. by default the SSL connection gets established without any peer verification, which makes Man-in-the-Middle attacks possible 😭. if you want to prevent that, you need to set either the ssl_ca_file or the ssl_ca_path option.

• ssl — set this option to 1 to encrypt the network connection using SSL. 🔒
• ssl_ca_file — path to the the Certificate Authority's certificate file (ca.crt) that your server key was signed with.
• ssl_ca_path — path of a directory containing several trusted certificates with a proper index. please refer to the OpenSSL documentation for the details about setting up such a directory.
• ssl_opts — this optional parameter takes a hash reference of options passed to IO::Socket::SSL->new(...) so you get more control over the SSL connection. for example you can set the 'SSL_verifycn_name' here if the server certificate common name doesn't match the hostname you use to resolve the server IP, or if you have to use a static server IP address or something like that.

AUTHENTICATION OPTIONS 🫶

if the server requires user authentication, you need to set the following options:

• auth_user — a valid username.
• auth_pass — the corresponding password, 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 wrapper around Perl's builtin crypt() function, this will probably change someday, so better use this method:

$crypted_pass = Event::RPC->crypt($user, $pass);

if the passed credentials are invalid, the Event::RPC::Client->connect() method throws a correspondent exception. 💀

MESSAGE FORMAT OPTIONS 🎀

Event::RPC supports different CPAN modules for data serialisation, and here they're called "message formats":

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

server and client negotiate automatically which format is best to use. the server sends a list of supported formats to the client, and the client takes the first one which is available. cute, right? ✨

and for the client there is one option to influence this format negotiation mechanism:

• insecure_msg_fmt_ok — the Storable module is known to be insecure, so it should only ever be taken as the last option. by default the Client does exactly that. you can prevent it by explicitly setting this option to 0. it's enabled by default. most likely the connection will fail in that case, because the server will only offer Storable if no other serialiser is available. 🙈

ERROR HANDLING 😭

any exceptions thrown on the server during execution of a remote method will result in a corresponding exception on the client. so you can use normal exception handling with eval {} when executing remote methods.

but besides all that, the network connection between your client and the server may break at any time. that raises an exception too, but you can override this behaviour with the following attribute:

• error_cb — this subroutine is called if any error occurs in the network communication between the client and the server. the actual Event::RPC::Client object and an error string are passed as arguments. this is no generic exception handler for exceptions thrown from the executed methods on the server! if you want to catch such exceptions you need to put an eval {} around your method calls, exactly like you would do for local method calls. if you don't specify an error_cb, an exception is thrown instead.

---

✨ METHODS ✨

• $rpc_client->connect — establishes the configured connection to the server. an exception is thrown if something goes wrong, e.g. server not available, credentials are invalid, or something like that. 🔥
• $rpc_client->disconnect — closes the connection to the server. you may skip explicit disconnecting, since it's done automatically once the Event::RPC::Client object gets destroyed. 🦋
• $rpc_client->set_max_packet_size ( $bytes ) — by default Event::RPC does not handle network packages which exceed 2 GB in size (it 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. 📏

---

✨ READY ONLY ATTRIBUTES ✨

• $rpc_client->get_server_version — returns the Event::RPC version number of the server, after connecting.
• $rpc_client->get_server_protocol — returns the Event::RPC protocol number of the server, after connecting.
• $rpc_client->get_client_version — returns the Event::RPC version number of the client.
• $rpc_client->get_client_protocol — returns the Event::RPC protocol number of the client.

---

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

---

and that's a wrap bestie 💖 this page is from the User Contributed Perl Documentation, shipped as perl v5.40.1, dated 2025-09-29. go build something iconic with it 👑🌈⭐