NAME

RPC::Switch::Client - Connect to the RPC-Switch using Mojo.

SYNOPSIS

use RPC::Switch::Client;

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

 my ($status, $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 initiate and inspect rpcs as well as for providing 'worker' services to the RPC-Switch.

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)
- ioloop: Mojo::IOLoop object to use: (per default the Mojo::IOLoop->singleton object is used)
- log: Mojo::Log object to use: (per default a new Mojo::Log object is created)
- jsonobject: json encoder/decoder object to use: (per default a new JSON::MaybeXS object is created)
- timeout: how long to wait for Api calls to complete: (default 60 seconds)
- ping_timeout: after this long without a ping from the Api the connection will be closed and the work() method will return: (default: 5 minutes)
- autoconnect: automatically connect to the RPC-Switch.: (default: true)

connect

$connected = $client->connect();

Connect (or reconnect) to the RPC-Switch. Returns a true value if the connection succeeded.

is_connected

$connected = $client->is_connected();

Returns a true value if the $client is connected.

call

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

Calls 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)
- timeout: wait this many seconds for the method to finish (optional, defaults to 5 times the Api-call timeout, so default 5 minutes)

call_nb

$client->call_nb(%args);

Calls a method on the RPC-Switch and calls the provided callbacks on completion of the method call.

- waitcb: (optional) coderef that will be called when the worker signals that processing may take a while. The $wait_id can be used with the get_status call, $status wil be the string 'RES_WAIT'.: ( waitcb => sub { ($status, $wait_id) = @_; ... } )
- resultcb: coderef that will be called on method completion. $status will be a string value, one of 'RES_OK' or 'RES_ERROR'. $outargs will be the method return values or a error message, respectively.: ( resultcb => sub { ($status, $outargs) = @_; ... } )

get_status

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

Retrieves the status for the given $wait_id. See call_nb for a description of the return values.

ping

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

Tries to ping the RPC-Switch. 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 method to be performed. Returns an error when there was a problem announcing the action.

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

See rpc-switch-worker for an example.

Valid arguments are:

- workername: name of the worker

(optional, defaults to client->who, processname and processid)

- method: name of the method

(required)

- cb: callback to be called for the method

Default arguments are the request_id and the contents of the JSON-RPC 2.0 params field.

(required)

- mode: callback mode

(optional, default 'sync')

Possible values:

- 'sync': simple blocking mode, just return the results from the callback. Use only for callbacks taking less than (about) a second.
- '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, after setting up some Mojo-callbacks.

- async: backwards compatible way for specifying mode 'async'

(optional, default false)

- meta: pass RPC-Switch meta information

The RPC-Switch meta information is passed to the callback as an extra argument after the JSON-RPC 2.0 params field.

- undocb: undo on error

A callback that gets called when the original callback returns an error object or throws an error.

Called with the same arguments as the original callback.

(optional, only valid for mode 'subproc')

- filter: only process a subset of the method

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" action the filter expression {'host' => 'example.com'} would mean that this worker can only do mkdir on host example.com. Filter expressions are limited to simple equality tests on one or more keys, and only those keys that are allowed in the action definition. Filtering can be allowed, be mandatory or be forbidden per action.

- doc: documentation for the method

The documentation provided to the RPC-Switch can be retrieved by calling the rpcswitch.get_method_details method. Documentation is 'free-form' but the suggested format is something like:

'doc' => {
  'description' => 'adds step to counter and returns counter; step defaults to 1',
  'outputs' => 'counter',
  'inputs' => 'counter, step'
}

work

$client->work();

Starts the Mojo::IOLoop. Returns a non-zero value when the IOLoop was stopped due to some error condition (like a lost connection or a ping timeout).

Possible work() exit codes

The RPC::Switch:Client library currently defines the following exit codes:

WORK_OK
WORK_PING_TIMEOUT
WORK_CONNECTION_CLOSED

stop

$client->stop($exit);

Makes the work() function exit with the provided exit code.

REMOTE METHOD INFORMATION

Once a connection has been established to the RPC-Switch there are two methods that can provide information about the remote methods that are callable via the RPC-Switch.

- rpcswitch.get_methods

Produces a list of all methods that are callable by the current role with a short description text if available

Example: ./rpc-switch-client rpcswitch.get_methods '{}'

  ...
	[
	  {
	    'foo.add' => 'adds 2 numbers'
	  },
	  {
	    'foo.div' => 'undocumented method'
	  },
	  ...
	];

- rpcswitch.get_method_details

Gives detailed information about a specific method. Details can include the 'backend' (b) method that a worker needs to provide, a short descrption (d) and contact information (c). If a worker is available then the documentation for that method from that worker is shown.

Example: ./rpc-switch-client rpcswitch.get_method_details '{"method":"foo.add"}'

  ...
	{
	  'doc' => {
		     'description' => 'adds step to counter and returns counter; step defaults to 1',
		     'outputs' => 'counter',
		     'inputs' => 'counter, step'
		   },
	  'b' => 'bar.add',
	  'd' => 'adds 2 numbers',
	  'c' => 'wieger'
	}

ACKNOWLEDGEMENT

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

THANKS

'greencoloured' for multiple PRs

AUTHORS

Wieger Opmeer <wiegerop@cpan.org>

COPYRIGHT AND LICENSE

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

To install RPC::Switch::Client, copy and paste the appropriate command in to your terminal.

cpanm

cpanm RPC::Switch::Client

CPAN shell

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

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

new

connect

is_connected

call

call_nb

get_status

ping

announce

work

Possible work() exit codes

stop

REMOTE METHOD INFORMATION

SEE ALSO

ACKNOWLEDGEMENT

THANKS

AUTHORS

COPYRIGHT AND LICENSE

Module Install Instructions