NAME

Beekeeper::Client - Make RPC calls through message bus

VERSION

Version 0.01

SYNOPSIS

  my $client = Beekeeper::Client->instance;
  
  $client->send_notification(
      method => "my.service.foo",
      params => { foo => $foo },
  );
  
  my $resp = $client->do_job(
      method => "my.service.bar",
      params => { %args },
  );
  
  die uneless $resp->success;
  
  print $resp->result;
  
  my $req = $client->do_async_job(
      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_all_jobs;

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 │
  ├───────────────────┼──────────────┼────────┼────────┼────────┤
  │ do_job            │ 1 worker     │ yes    │ yes    │ yes    │
  │ do_async_job      │ 1 worker     │ yes    │ yes    │ no     │
  │ do_background_job │ 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.

do_job ( %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.

do_async_job ( %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 do_job. 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.

do_background_job ( %args )

Makes an asynchronous RPC call to a service worker through the message bus but does not expect to receive any response, it is a fire and forget call.

It returns undef immediately.

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

wait_all_jobs

Wait (in the event loop) until all calls made by do_async_job are completed.

set_auth_tokens ( @tokens )

Add arbitrary auth tokens to subsequent jobs requests or notifications sent.

Workers get the caller tokens already set when executing jobs or notifications callbacks, and then these are piggybacked automatically.

This framework doesn't give any special meaning to these tokens.

get_auth_tokens

Get the list of current auth tokens in use.

SEE ALSO

Beekeeper::Bus::STOMP, Beekeeper::Worker.

AUTHOR

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

COPYRIGHT AND LICENSE

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