GET /nodes

Parameters: none.

Returns an Array of node Objects defined (with id the stringified _id) on success, { "error": "Could not get current nodes: $_" } on error.

Sets HTTP status to 400 on error.

Note: new in Disbatch 4

GET /nodes/:node

URL: :node is the _id if it matches /\A[0-9a-f]{24}\z/, or node name if it does not.

Parameters: none.

Returns node Object (with id the stringified _id) on success, { "error": "Could not get node $node: $_" } on error.

Sets HTTP status to 400 on error.

Note: new in Disbatch 4

POST /nodes/:node

URL: :node is the _id if it matches /\A[0-9a-f]{24}\z/, or node name if it does not.

Parameters: { "maxthreads": maxthreads }

"maxthreads" is a non-negative integer or null

Returns { ref $res: Object } or { ref $res: Object, "error": error_string_or_reponse_object }

Sets HTTP status to 400 on error.

Note: new in Disbatch 4

GET /plugins

Parameters: none.

Returns an Array of allowed plugin names.

Should never fail.

Note: replaces /queue-prototypes-json

GET /queues

Parameters: none.

Returns an Array of queue Objects on success, { "error": "Could not get current queues: $_" } on error.

Each item has the following keys: id, plugin, name, threads, queued, running, completed

Sets HTTP status to 400 on error.

Note: replaces /scheduler-json

POST /queues

Create a new queue.

Parameters: { "name": name, "plugin": plugin }

name is the desired name for the queue (must be unique), plugin is the plugin name for the queue.

Returns: { ref $res: Object, "id": $inserted_id } on success; { "error": "name and plugin required" }, { "error": "Invalid param", "param": $param }, or { "error": "Unknown plugin", "plugin": $plugin } on input error; or { ref $res: Object, "id": null, "error": "$res" } on MongoDB error.

Sets HTTP status to 400 on error.

Note: replaces /start-queue-json

POST /queues/:queue

URL: :queue is the _id if it matches /\A[0-9a-f]{24}\z/, or name if it does not.

Parameters: { "name": name, "plugin": plugin, "threads": threads }

name is the new name for the queue (must be unique), plugin is the new plugin name for the queue (must be defined in the config file), threads must be a non-negative integer. Only one of name, plugin, and threads is required, but any combination is allowed.

Returns { ref $res: Object } or { "error": error }

Sets HTTP status to 400 on error.

Note: replaces /set-queue-attr-json

DELETE /queues/:queue

Deletes the specified queue.

URL: :queue is the _id if it matches /\A[0-9a-f]{24}\z/, or name if it does not.

Parameters: none

Returns: { ref $res: Object } on success, or { ref $res: Object, "error": "$res" } on error.

Sets HTTP status to 400 on error.

Note: replaces /delete-queue-json

POST /tasks/search

Parameters: { "filter": filter, "options": options, "count": count, "terse": terse }

All parameters are optional.

filter is a filter expression (query) object.

options is an object of desired options to MongoDB::Collection#find.

If not set, options.limit will be 100. This will fail if you try to set it above 100.

count is a boolean. Instead of an array of task documents, the count of task documents matching the query will be returned.

terse is a boolean. If true, the the GridFS id or "[terse mode]" will be returned for stdout and stderr of each document. If false, the full content of stdout and stderr will be returned. Default is true.

Returns: Array of task Objects or { "count": $count } on success; { "error": "filter and options must be name/value objects" }, { "error": "limit cannot exceed 100" }, or { "error": "Bad OID passed: $error" } on input error; or { "error": "$error" } on count or search error.

Sets HTTP status to 400 on error.

Note: replaces /search-tasks-json

POST /tasks/:queue

URL: :queue is the _id if it matches /\A[0-9a-f]{24}\z/, or name if it does not.

Parameters: an array of task params objects

Returns: { ref $res: Object } on success; { "error": "params must be a JSON array of task params" } or { "error": "queue not found" } on input error; or { ref $res: Object, "error": "Unknown error" } on MongoDB error.

Sets HTTP status to 400 on error.

Note: replaces /queue-create-tasks-json

POST /tasks/:queue/:collection

URL: :queue is the _id if it matches /\A[0-9a-f]{24}\z/, or name if it does not. :collection is a MongoDB collection name.

Parameters: { "filter": filter, "params": params }

filter is a filter expression (query) object for the :collection collection.

params is an object of task params. To insert a document value from a query into the params, prefix the desired key name with document. as a value.

Returns: { ref $res: Object } on success; { "error": "filter and params required and must be name/value objects" } or { "error": "queue not found" } on input error; { "error": "Could not iterate on collection $collection: $error" } on query error, or { ref $res: Object, "error": "Unknown error" } on MongoDB error.

Sets HTTP status to 400 on error.

Note: replaces /queue-create-tasks-from-query-json

NAME

Disbatch::Web - Disbatch Command Interface (JSON REST API and web browser interface to Disbatch).

VERSION

version 3.990

SUBROUTINES

init(config_file => $config_file)

Parameters: path to the Disbatch config file. Default is /etc/disbatch/config.json.

Initializes the settings for the web server.

Returns nothing.

parse_params

Parameters: none

Parses request parameters in the following order:

* from the request body if the Content-Type is application/x-www-form-urlencoded

* from the request body if the Content-Type is application/json

* from the request query otherwise

Returns a HASH of the parsed request parameters.

get_nodes

Parameters: none

Returns an array of node objects defined, with timestamp stringified and id the stringified _id.

get_plugins

Parameters: none

Returns a HASH of defined queues plugins and any defined config.plugins, where values match the keys.

get_queue_oid($queue)

Parameters: Queue ID as a string, or queue name.

Returns a MongoDB::OID object representing this queue's _id.

create_tasks($queue_id, $tasks)

Parameters: MongoDB::OID object of the queue _id, ARRAY of task params.

Creates one queued task document for the given queue _id per $tasks entry. Each $task entry becomes the value of the params field of the document.

Returns: the repsonse object from a MongoDB::Collection#insert_many request.

JSON ROUTES

BROWSER ROUTES

GET /

Returns the contents of "/index.html" – the queue browser page.

GET qr{^/}

Returns the contents of the request path.

SEE ALSO

Disbatch

Disbatch::Roles

Disbatch::Plugin::Demo

disbatchd

disbatch.pl

task_runner

disbatch-create-users

AUTHORS

Ashley Willis <awillis@synacor.com>

Matt Busigin

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Ashley Willis.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004