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)
- ioloop: Mojo::IOLoop object to use: (per default the Mojo::IOLoop->singleton object is used)
- 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)
- jsonobject: json encoder/decoder object to use: (per default a new JSON::MaybeXS object is created)
- 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)
- reqauth: authentication token to be passed on to the authentication module of the API for per job/request authentication.
- clenv: client environment, made available as part of the job environment and inherited to child jobs.

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)

get_job_status_nb

$client->get_job_status_nb(%args);

Retrieves the status for the given $job_id.

Valid arguments are:

- job_id

- statuscb: coderef to the callback for the current status

( statuscb => sub { ($job_id, $result) = @_; ... } )

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)

- notifycb: coderef to the callback for job completion

( statuscb => sub { ($job_id, $result) = @_; ... } )

If the job was still running when the get_job_status_nb call was made then this callback will be called on completion of the job.

check_if_lock_exists

$found = $client->check_if_lock_exists($locktype, $lockvalue);

Checks if a lock with the given locktype and lockvalue exists. (I.e. a job is currently running that holds that lock.

Returns true if the lock exists, null if the locktype does not exist, false otherwise.

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.

close

$client->close()

Closes the connection to the JobCenter API and tries to de-allocate everything. Trying to use the client afterwards will produce errors.

create_slotgroup

$client->create_slotgroup($name, $slots)

A 'slotgroup' is a way of telling the JobCenter API how many taskss the worker can do at once. The number of slots should be a positive integer. Slotgroups names starting with a _ (underscore) are reserved for internal use. Returns a error message when then was an error, the empty string otherwise.

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)

- slotgroup: the slotgroup to use for accounting of parrallel tasks

(optional, conflicts with 'slots')

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

(optional, default 1, conflicts with 'slotgroup')

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

ACKNOWLEDGEMENT

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

THANKS

Thanks to Eitan Schuler for reporting a bug and providing a pull request.

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 JobCenter::Client::Mojo, copy and paste the appropriate command in to your terminal.

cpanm

cpanm JobCenter::Client::Mojo

CPAN shell

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

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

call

call_nb

get_job_status

get_job_status_nb

check_if_lock_exists

find_jobs

ping

close

create_slotgroup

announce

work

Possible work() exit codes

stop

SEE ALSO

ACKNOWLEDGEMENT

THANKS

AUTHORS

COPYRIGHT AND LICENSE

Module Install Instructions