Basic Usage

The shhttp daemon creates an HTTP service that by default listens on path /v1/ for HTTP requests with JSON content. If the daemon is run with the defaults, the service will listen on http://localhost:2112/v1.

Immediate execution (/exec)

You can submit a single command/script on the /v1/exec path by doing a POST on it with the following body:

POST http://localhost:2112/v1/exec
{
	"Command": "echo",
	"Args": ["shhttp is awesome"]
}

The command/script will be performed and the result will be returned as follows:

{
    "Executable": {
        "Command": "echo",
        "Args": [
            "shhttp is awesome"
        ],
        "ExecPath": "",
        "Stdin": "",
        "Shell": false
    },
    "Stdout": "shhttp is awesome\n",
    "Stderr": "",
    "ExitCode": 0,
    "Start": 1549611855,
    "End": 1549611855
}

The command is executed as an exec call which is why shell based expansion is not performed, for example, the following will will not perform as expected:

POST http://localhost:2112/v1/exec
{
	"Command": "echo",
	"Args": ["shhttp is awesome", "|", "grep", "awesome"]
}

will return

{
    "Executable": {
        "Command": "echo",
        "Args": [
            "shhttp is awesome",
            "|",
            "grep",
            "awesome"
        ],
        "ExecPath": "",
        "Stdin": "",
        "Shell": false
    },
    "Stdout": "shhttp is awesome | grep awesome\n",
    "Stderr": "",
    "ExitCode": 0,
    "Start": 1549612162,
    "End": 1549612162
}

To make the shell work, you need to set the Shell property in the request:

POST http://localhost:2112/v1/exec
{
	"Command": "echo",
	"Args": ["shhttp is awesome", "|", "grep", "awesome"],
	"Shell": true
}

resulting in:

{
    "Executable": {
        "Command": "echo",
        "Args": [
            "shhttp is awesome",
            "|",
            "grep",
            "awesome"
        ],
        "ExecPath": "",
        "Stdin": "",
        "Shell": true
    },
    "Stdout": "shhttp is awesome\n",
    "Stderr": "",
    "ExitCode": 0,
    "Start": 1549612268,
    "End": 1549612268
}

For this, the default shell sh is used.

Executable schema

The full body of the request is as follows:

{
	"Command": "(string) The command to execute",
	"Args": "(string []) Array of arguments to pass to the above command",
	"BaseDir": "(string) The directory from which the command should be invoked",
	"Stdin": "(string) This string will be piped into the stdin of the command",
	"Shell": "(bool) Whether to execute this command on shell",
        "Env": "(json) String key-value pairs that are injected as environment variables"
}

Job Schema

The full body of Job is as follows:

{
	Id : "(string) System generated identifier, overwritten if sent in the request",
	"Executions": [
		"Executable": {
			"Command": "(string) The command to execute",
			"Args": "(string []) Array of arguments to pass to the above command",
			"BaseDir": "(string) The directory from which the command should be invoked",
			"Stdin": "(string) This string will be piped into the stdin of the command",
			"Shell": "(bool) Whether to execute this command on shell",
	        "Env": "(json) String key-value pairs that are injected as environment variables"
		},
		"Stdout": "(string) Output of the executable, set by the system",
		"Stderr": "(string) Error output of the executable, set by the system",
		"ExitCode": "(int) Exit code returned by the executable, set by the system",
		"Start": "(int) Unix epoch when the execution started",
		"End": "(int) Unix epoch when the execution ended"
	],
	"Status": "(string) Can be any of (IN_PROGRESS, DONE, QUEUED, FAILED), set by the system",
	"Created": "(int) Unix epoch when the job was created",
	"LastModified": "(int) Unix epoch when the job was last modified",
	"IgnoreErrors": "(bool) Set to true if an error in any execution should not stop the job"
}