http-runner
v0.0.5
Published
A simple HTTP-based remote job runner.
Downloads
8
Readme
http-runner
A simple HTTP-based remote job runner using Node.js.
Description
http-runner
allows you to remotely create shell jobs using a small HTTP JSON
API. Basically, you send an HTTP POST with a JSON object containing a command
and an arguments
string and it will spawn a process.
stdout
and stderr
output, the process exit code and any error message will be captured and returned.
This package allows you to execute long-running processes (e.g. transcoding, archival tasks, etc.) asynchronously and be notified when a job is done. Also, it allows you to trigger jobs on separate machines on your network to spread load.
API
Request: POST /
Parameters (HTTP POST data, should be valid JSON object):
{
"command": "curl",
"args":"--progress-bar https://raw.github.com/tieleman/http-runner/master/LICENSE",
"callback":"http://my.callback.io:8080/"
}
callback
is an optional argument. It is a HTTP endpoint that should be notified when the job completes. The job and any error status will be POSTed to this endpoint. This will silently fail if the callback is not available (i.e. http-runner
doesn't care whether the other end is available or not).
Responses:
202 Accepted
- Job accepted400 Bad Request
- Invalid request (format)
Request: GET /:id
Responses:
200 OK
- Returns status of job404 Not Found
- Job not found
Warning
http-runner
is of course an easy way to have anyone compromise your system. Don't run this public on the internet. It will kill your dog, eat your dinner, break your porselain collection and sell the nuclear launch codes to evil dictators.
Don't ever run this as root, run it as an unprivileged user, and even then, use extreme caution (don't say I didn't warn you).
If at all possible use a small whitelist (and don't put sudo
in your whitelist).
Running http-runner
- Clone the source from Github (or install from npm using
npm install http-runner
). - Run
npm install
from the source directory to install dependencies if cloned from Github (not necessary when installed using npm). - Run
bin/http-runner
, this will start the server on port 9000, listening on the loopback interface only (so no remote connections can be made unless you explicitly allow it).
The CLI supports the following options:
-p $PORT: run server on specified TCP port (default 9000)
-i $INTERFACE: accept connections on the specified interface (default 127.0.0.1)
-w $WHITELIST: only allow specific commands (comma-separated, default all commands)
-n $MAX_JOB_COUNT: maximum number of jobs to keep in memory (default 100)
Examples
Creating a job:
# curl -XPOST -d'{"command":"echo", "args":"foo"}' http://localhost:9000
{"stderr":"","stdout":"","id":"9c2ec44b891317c272c0e20d1e46629a83ebf905","code":null,"command":"echo","arguments":["foo"]}
Getting the status of a job:
# curl http://localhost:9000/9c2ec44b891317c272c0e20d1e46629a83ebf905
{"stderr":"","stdout":"foo\n","id":"9c2ec44b891317c272c0e20d1e46629a83ebf905","code":0,"command":"echo","arguments":["foo"],"err":null}
Note that after the job has completed the exit code has been set (in this case to 0
). Also, if any errors occurred during the spawning of the job (e.g. Node can't spawn for whatever reason) this will be visible in the err
property.
Starting http-runner
with CLI options (port 8080, whitelist of two commands: ffmpeg
and rake
):
# http-runner -p 8080 -w /usr/local/bin/ffmpeg,/usr/local/bin/rake
Note that the comma-separated list should not contain spaces (not fully tested) and jobs should match the commands listed here exactly.
The -n
option allows specifying the maximum number of jobs to keep in memory. Creating a job after the maximum has been reached will result in the purging of the oldest jobs from memory, to prevent memory overflow issues.