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 iniate 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)

- log: Mojo::Log object to use

(per default a new Mojo::Log 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)

call

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

Calls the RPC-Switch and waits for the results.

Valid arguments are:

- method: name of the methodw 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

(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)

- undocb: 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

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

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'
        }

SEE ALSO

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

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

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

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) 2018 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