view release on metacpan or  search on metacpan

lib/Beekeeper/Client.pm  view on Meta::CPAN

All methods in this module are exported by default to L<Beekeeper::Worker>.

=head1 CONSTRUCTOR

=head3 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 C<bus.config.json>.

=head1 METHODS

=head3 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.

=over

=item method

A string with the name of the notification being sent with format C<{service_class}.{method}>.

=item 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.

=item 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.

=back

=head3 accept_notifications ( $method => $callback, ... )

Makes a client start accepting the specified notifications from the message bus.

C<$method> is a string with the format C<{service_class}.{method}>. A default
or fallback handler can be specified using a wildcard like C<{service_class}.*>.

C<$callback> is a coderef that will be called when a notification is received.
When executed, the callback will receive a parameter C<$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.

=head3 stop_accepting_notifications ( $method, ... )

Makes a client stop accepting the specified notifications from the message bus.

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

=head3 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 L<Beekeeper::JSONRPC::Response> object or a L<Beekeeper::JSONRPC::Error>.

On error it will die unless C<raise_error> option is set to false.

This method accepts the following parameters:

=over

=item method

A string with the name of the method to be invoked with format C<{service_class}.{method}>.

=item 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.

=item 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.

=item 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.

=item 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 L<Beekeeper::JSONRPC::Error> instead.

=back

=head3 call_remote_async ( %args )

Makes an asynchronous RPC call to a service worker through the message bus.

It returns immediately a L<Beekeeper::JSONRPC::Request> object which, once completed,
will have a defined C<response>.

This method  accepts parameters C<method>, C<params>, C<address> and C<timeout> 
the same as C<call_remote>. Additionally two callbacks can be specified:

=over

=item on_success

Callback which will be executed after receiving a successful response with a
L<Beekeeper::JSONRPC::Response> object as parameter. Must be a coderef.

=item on_error

Callback which will be executed after receiving an error response with a
L<Beekeeper::JSONRPC::Error> object as parameter. Must be a coderef.

=back

=head3 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 C<method>, C<params> and C<address> the same as C<call_remote>.

=head3 wait_async_calls

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

=head3 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.

=head3 get_authentication_data

Returns the current authentication data blob.

=head1 SEE ALSO
 
L<Beekeeper::Worker>, L<Beekeeper::Config>, L<Beekeeper::MQTT>.

=head1 AUTHOR

José Micó, C<jose.mico@gmail.com>

=head1 COPYRIGHT AND LICENSE

Copyright 2015-2023 José Micó.