NAME

RPC::Switch::Client - RPC-Switch client using Mojo(licious).

SYNOPSIS

use RPC::Switch::Client;

 my $client = RPC::Switch::Client->new(
   address => ...
   port => ...
   who => ...
   token => ...
 );

 my ($job_id, $outargs) = $client->call(
   method => 'test',
   inargs => { test => 'test' },
 );

DESCRIPTION

RPC::Switch::Client is a class to build a client to connect to the RPC-Switch. The client can be used to call methods on the RPC-Switch as well as to announce and handle methods as a worker.

METHODS

new

$client = RPC::Switch::Client->new(%arguments);

Class method that returns a new RPC::Switch::Client object.

Valid arguments are:

- address: address of the RPC-Switch.

(default: 127.0.0.1)

- port: port of the RPC-Switch

(default 6551)

- tls: connect using tls

(default false)

- tls_ca: verify server using ca

(default undef)

- tls_key: private client key

(default undef)

- tls_ca: public client certificate

(default undef)

- who: who to authenticate as.

(required)

- method: how to authenticate.

(default: password)

- token: token to authenticate with.

(required)

- debug: when true prints debugging using Mojo::Log

(default: false)

- json: flag wether input is json or perl.

when true expects the inargs to be valid json, when false a perl hashref is expected and json encoded. (default true)

- log: Mojo::Log object to use

(per default a new Mojo::Log object is created)

- ping_timeout: after this long without a ping from the RPC-Switch the connection will be closed and the work() method will return

(default 5 minutes)

call

($status, $outargs) = $client->call(%args);

Calls a method on the RPC-Switch and waits for the results.

Valid arguments are:

- method: name of the method to call (required)

- inargs: input arguments for the workflow (if any)

The returned status can be on of:

- RES_OK

- RES_ERROR

call_nb

$job_id = $client->call_nb(%args);

Calls a method on the RPC-Switch and calls the provided result callback on completion.

- resultcb: coderef to the callback to call on method completion (required)

( resultcb => sub { ($status, $outargs) = @_; ... } )

- waitcb: coderef to the callback to call on method delay (optional)

( waitcb => sub { ($status, $wait_id) = @_; ... } )

The status will be RES_WAIT, the $wait_id could be used with get_status to poll for method completion.

The intended use case is for methods that start some kind of extended processing to return a "cloakroom number". If the connection to the RPC-Switch gets lost or if it infeasable to keep a connection open for a long time this number can then be used to retrieve the method call results.

get_status

($status, $outargs) = $client->get_status($wait_id, $wait);

Retrieves the status for the given $wait_id. If $wait is true then get_status will block untill either a RES_OK of RES_ERROR is returned.

The returned status can be on of:

- RES_OK

- RES_ERROR

- RES_WAIT : still working, only if $wait is false.

ping

$status = $client->ping($timeout);

Tries to ping the JobCenter API. On success return true. On failure returns the undefined value, after that the client object should be undefined.

announce

Announces the capability to perform a method to the RPC-Switch. The provided callback will be called when there is a task to be performed. Returns an error when there was a problem announcing the action.

my $err = $client->announce(
  method => 'do_something',
  cb => sub { ... },
);
die "could not announce $method: $err" if $err;

See rpc-switch-worker for an example.

Valid arguments are:

- method: the method name

(required)

- cb: callback to be called for the action

(required)

- mode: callback mode

(optional, default 'sync')

Possible values:

- 'sync': simple blocking mode, just return the results from the callback.

- 'subproc': the simple blocking callback is started in a seperate process. Useful for callbacks that take a long time.

- 'async': the callback gets passed another callback as the last argument that is to be called on completion of the task. For advanced use cases where the worker is actually more like a proxy. The (initial) callback is expected to return soonish to the event loop.

- filter: only process a subset of the action

The filter expression allows a worker to specify that it can only do the method for a certain subset of arguments. For example, for a "mkdir" method the filter expression {'host' => 'example.com'} would mean that this worker can only do mkdir on host example.com. The filter expression is limited to a simple equality tests on one key only, and only for the key configured at the RPC-Switch. If a key is configured at the RPC-Switch filtering is mandatory.

work

Starts the Mojo::IOLoop.

SEE ALSO

• Mojo::IOLoop, Mojo::IOLoop::Stream, http://mojolicious.org: the Mojolicious Web framework

• "rpc-switch-client" in examples, "rpc-switch-worker" in examples

"/github.com/a6502/rpc-switch: RPC-Switch" in https:

ACKNOWLEDGEMENT

This software has been developed with support from STRATO. In German: Diese Software wurde mit Unterstützung von STRATO entwickelt.

AUTHORS

• Wieger Opmeer <wiegerop@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Wieger Opmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm RPC::Switch::Client

perl -MCPAN -e shell
install RPC::Switch::Client