RPC::Switch::Client - Connect to the RPC-Switch using Mojo.
use RPC::Switch::Client; my $client = RPC::Switch::Client->new( address => ... port => ... who => ... token => ... ); my ($status, $outargs) = $client->call( method => 'test', inargs => { test => 'test' }, );
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.
$client = RPC::Switch::Client->new(%arguments);
Class method that returns a new RPC::Switch::Client object.
Valid arguments are:
(default: 127.0.0.1)
(default 6551)
(default false)
(default undef)
(required)
(default: password)
(default: false)
when true expects the inargs to be valid json, when false a perl hashref is expected and json encoded. (default true)
(per default the Mojo::IOLoop->singleton object is used)
(per default a new Mojo::Log object is created)
(per default a new JSON::MaybeXS object is created)
(default 60 seconds)
(default: 5 minutes)
(default: true)
$connected = $client->connect();
Connect (or reconnect) to the RPC-Switch. Returns a true value if the connection succeeded.
$connected = $client->is_connected();
Returns a true value if the $client is connected.
($status, $outargs) = $client->call(%args);
Calls the RPC-Switch and waits for the results.
$client->call_nb(%args);
Calls a method on the RPC-Switch and calls the provided callbacks on completion of the method call.
( waitcb => sub { ($status, $wait_id) = @_; ... } )
( resultcb => sub { ($status, $outargs) = @_; ... } )
($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.
$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.
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.
(optional, defaults to client->who, processname and processid)
Default arguments are the request_id and the contents of the JSON-RPC 2.0 params field.
(optional, default 'sync')
Possible values:
(optional, default false)
The RPC-Switch meta information is passed to the callback as an extra argument after the JSON-RPC 2.0 params field.
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')
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.
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' }
$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).
The RPC::Switch:Client library currently defines the following exit codes:
WORK_OK WORK_PING_TIMEOUT WORK_CONNECTION_CLOSED
$client->stop($exit);
Makes the work() function exit with the provided exit code.
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.
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' }, ... ];
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' }
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
This software has been developed with support from STRATO. In German: Diese Software wurde mit Unterstützung von STRATO entwickelt.
'greencoloured' for multiple PRs
Wieger Opmeer <wiegerop@cpan.org>
This software is copyright (c) 2018-2022 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.
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.