NAME

JobCenter::Client::Mojo - JobCenter JSON-RPC 2.0 Api client using Mojo.

SYNOPSIS

  use JobCenter::Client::Mojo;

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

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

DESCRIPTION

JobCenter::Client::Mojo is a class to build a client to connect to the JSON-RPC 2.0 Api of the JobCenter workflow engine. The client can be used to create and inspect jobs as well as for providing 'worker' services to the JobCenter.

METHODS

new

$client = JobCenter::Client::Mojo->new(%arguments);

Class method that returns a new JobCenter::Client::Mojo object.

Valid arguments are:

- address: address of the Api.

(default: 127.0.0.1)

- port: port of the Api

(default 6522)

- 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

($job_id, $result) = $client->call(%args);

Creates a new JobCenter job and waits for the results. Throws an error if somethings goes wrong immediately. Errors encountered during later processing are returned as a JobCenter error object.

Valid arguments are:

- wfname: name of the workflow to call (required)

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

- vtag: version tag of the workflow to use (optional)

- timeout: wait this many seconds for the job to finish (optional, defaults to 5 times the Api-call timeout, so default 5 minutes)

call_nb

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

Creates a new JobCenter job and call the provided callback on completion of the job. Throws an error if somethings goes wrong immediately. Errors encountered during later processing are returned as a JobCenter error object to the callback.

Valid arguments are those for call and:

- cb1: coderef to the callback to call on job creation (requird)

( cb1 => sub { ($job_id, $err) = @_; ... } )

If job_id is undefined the job was not created, the error is then returned as the second return value.

- cb2: coderef to the callback to call on job completion (requird)

( cb2 => sub { ($job_id, $outargs) = @_; ... } )

get_job_status

($job_id, $result) = $client->get_job_status($job_id);

Retrieves the status for the given $job_id. If the job_id does not exist then the returned $job_id will be undefined and $result will be an error message. If the job has not finished executing then both $job_id and $result will be undefined. Otherwise the $result will contain the result of the job. (Which may be a JobCenter error object)

find_jobs

($err, @jobs) = $client->find_jobs({'foo'=>'bar'});

Finds all currently running jobs with arguments matching the filter expression. The expression is evaluated in PostgreSQL using the @> for jsonb objects, basically this means that you can only do equality tests for one or more top-level keys. If @jobs is empty $err might contain an error message.

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 do an action to the Api. 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(
    workername => 'me',
    actionname => 'do',
    slots => 1
    cb => sub { ... },
  );
  die "could not announce $actionname?: $err" if $err;

See jcworker for an example.

Valid arguments are:

- workername: name of the worker

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

- actionname: name of the action

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

- slots: the amount of tasks the worker is able to process in parallel for this action.

(optional, default 1)

- 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 action

The filter expression allows a worker to specify that it can only do the actionname 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.

- addenv: pass on action enviroment to the callback

If the addenv flag is true the action callback will be given one extra argument containing the action environment as a hashref. In the async callback mode the environment will be inserted before the result callback.

work

Starts the Mojo::IOLoop.

SEE ALSO

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

• "jcclient" in examples, "jcworker" in examples

https://github.com/a6502/JobCenter: JobCenter Orchestration Engine

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 JobCenter::Client::Mojo

perl -MCPAN -e shell
install JobCenter::Client::Mojo