NAME

Beekeeper::Client - Make RPC calls through message bus

VERSION

Version 0.05

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 message bus.

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 tries to connect using the configuration from config file bus.config.json.

METHODS

send_notification ( %args )

Broadcast a notification to the message bus.

All clients and workers listening for method will receive it. If no one is listening the notification is lost.

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, ... )

Make this client start accepting specified notifications from message bus.

$method is a string with the format "{service_class}.{method}". A default or fallback handler can be specified using a wildcard as "{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.

Note that callbacks will not be executed timely if AnyEvent loop is not running.

stop_accepting_notifications ( $method, ... )

Make this client stop accepting specified notifications from message bus.

$method must be one of the strings used previously in accept_notifications.

stop_accepting_notifications ( $method, ... )

Make this client stop accepting specified notifications from 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 an 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 )

Fire and forget an asynchronous RPC call to a service worker through the message bus.

It returns undef immediately, there is no way to know if the call was executed successfully or not.

This method accepts parameters method, params and address the same as call_remote.

wait_async_calls

Wait (running the event loop) until all calls made by call_remote_async are completed either by success, error or timeout.

set_authentication_data ( $data )

Add 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

Gets the current authentication data blob.

SEE ALSO

Beekeeper::MQTT, Beekeeper::Worker.

AUTHOR

José Micó, jose.mico@gmail.com

COPYRIGHT AND LICENSE

Copyright 2015-2021 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.

cpanm Beekeeper

perl -MCPAN -e shell
install Beekeeper