NAME
Beekeeper::Client - Make RPC calls through message bus
VERSION
Version 0.09
SYNOPSIS
my $client = Beekeeper::Client->instance;
$client->send_notification(
method => "my.service.foo",
params => { foo => $foo },
);
my $resp = $client->call_remote(
method => "my.service.bar",
params => { %args },
);
die uneless $resp->success;
print $resp->result;
my $req = $client->call_remote_async(
method => "my.service.baz",
params => { %args },
on_success => sub {
my $resp = shift;
print resp->result;
},
on_error => sub {
my $error = shift;
die error->message;
},
);
$client->wait_async_calls;DESCRIPTION
This module connects to the message broker and makes RPC calls through it.
There are four different methods to do so:
┌───────────────────┬──────────────┬────────┬────────┬────────┐
│ method │ sent to │ queued │ result │ blocks │
├───────────────────┼──────────────┼────────┼────────┼────────┤
│ call_remote │ 1 worker │ yes │ yes │ yes │
│ call_remote_async │ 1 worker │ yes │ yes │ no │
│ fire_remote │ 1 worker │ yes │ no │ no │
│ send_notification │ many workers │ no │ no │ no │
└───────────────────┴──────────────┴────────┴────────┴────────┘All methods in this module are exported by default to Beekeeper::Worker.
CONSTRUCTOR
instance( %args )
Connects to the message broker and returns a singleton instance.
Unless explicit connection parameters to the broker are provided it tries to connect using the parameters defined in config file bus.config.json.
METHODS
send_notification ( %args )
Broadcasts a notification to the message bus.
All clients and workers listening for given method will receive it.
If no one is listening for it the notification will be discarded.
- method
-
A string with the name of the notification being sent with format
{service_class}.{method}. - params
-
An arbitrary value or data structure sent with the notification. It could be undefined, but it should not contain blessed references that cannot be serialized as JSON.
- address
-
A string with the name of the remote bus when sending notifications to another logical bus. Notifications to another bus need a router shoveling them.
accept_notifications ( $method => $callback, ... )
Makes a client start accepting the specified notifications from the message bus.
$method is a string with the format {service_class}.{method}. A default or fallback handler can be specified using a wildcard like {service_class}.*.
$callback is a coderef that will be called when a notification is received. When executed, the callback will receive a parameter $params which contains the notification value or data structure sent.
Please note that callbacks will not be executed timely if AnyEvent loop is not running.
stop_accepting_notifications ( $method, ... )
Makes a client stop accepting the specified notifications from the message bus.
$method must be one of the strings used previously in accept_notifications.
call_remote ( %args )
Makes a synchronous RPC call to a service worker through the message bus.
It will wait (in the event loop) until a response is received, wich will be either a Beekeeper::JSONRPC::Response object or a Beekeeper::JSONRPC::Error.
On error it will die unless raise_error option is set to false.
This method accepts the following parameters:
- method
-
A string with the name of the method to be invoked with format
{service_class}.{method}. - params
-
An arbitrary value or data structure to be passed as parameters to the defined method. It could be undefined, but it should not contain blessed references that cannot be serialized as JSON.
- address
-
A string with the name of the remote bus when calling methods of workers connected to another logical bus. Requests to another bus need a router shoveling them.
- timeout
-
Time in seconds before cancelling the request and returning an error response. If the request takes too long but otherwise was executed successfully the response will eventually arrive but it will be ignored.
- raise_error
-
If set to true (the default) dies with the received error message when a call returns an error response. If set to false returns a Beekeeper::JSONRPC::Error instead.
call_remote_async ( %args )
Makes an asynchronous RPC call to a service worker through the message bus.
It returns immediately a Beekeeper::JSONRPC::Request object which, once completed, will have a defined response.
This method accepts parameters method, params, address and timeout the same as call_remote. Additionally two callbacks can be specified:
- on_success
-
Callback which will be executed after receiving a successful response with a Beekeeper::JSONRPC::Response object as parameter. Must be a coderef.
- on_error
-
Callback which will be executed after receiving an error response with a Beekeeper::JSONRPC::Error object as parameter. Must be a coderef.
fire_remote ( %args )
Makes a fire and forget RPC call to a service worker through the message bus.
It returns undef immediately. The worker receiving the call will not send back a response.
This method accepts parameters method, params and address the same as call_remote.
wait_async_calls
Waits (running the event loop) until all calls made by call_remote_async are completed either by success, error or timeout.
set_authentication_data ( $data )
Adds an arbitrary authentication data blob to subsequent calls or notifications sent.
This data persists for client lifetime in standalone clients. Within worker context it persists until the end of current request only, and will be piggybacked on calls made to another workers within the scope of current request.
The meaning of this data is application specific, this framework doesn't give any special one to it.
get_authentication_data
Returns the current authentication data blob.
SEE ALSO
Beekeeper::Worker, Beekeeper::Config, Beekeeper::MQTT.
AUTHOR
José Micó, jose.mico@gmail.com
COPYRIGHT AND LICENSE
Copyright 2015-2023 José Micó.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language itself.
This software is distributed in the hope that it will be useful, but it is provided “as is” and without any express or implied warranties. For details, see the full text of the license in the file LICENSE.