canteen

This is a single-executable service intended to sit between nomad API and UI services. It exposes executable batch jobs with arguments via http push, while the statuses of the running jobs are reported via SSE.

Execution

canteen --acl <acl token> --nomad <http://nomad.api>

API Specification

Base URL

All endpoints are relative to the service base URL.

Authentication

Requests must include the ACL token configured at startup via the --acl parameter in an Authorization: Bearer <token> header.

Endpoints

1. List Available Jobs

GET /jobs

Returns a list of available executable jobs that can be submitted.

Response (200 OK):

{
  "jobs": [
    {
      "id": "job_id",
      "name": "job_name",
      "description": "Job description",
      "arguments": [
        {
          "name": "arg_name",
          "type": "string",
          "required": true,
          "description": "Argument description"
        }
      ]
    }
  ]
}

2. Submit a Batch Job

POST /jobs/{job_id}/run

Submits a new batch job for execution with the specified arguments.

Request Body:

{
  "arguments": {
    "arg_name": "arg_value"
  }
}

Response (202 Accepted):

{
  "run_id": "run_uuid",
  "job_id": "job_id",
  "status": "pending",
  "created_at": "2026-05-18T10:30:00Z",
  "nomad_allocation_id": "allocation_uuid"
}

Response (400 Bad Request):

{
  "error": "Invalid arguments for job"
}

3. Get Job Run Status

GET /runs/{run_id}

Returns the current status of a submitted job run.

Response (200 OK):

{
  "run_id": "run_uuid",
  "job_id": "job_id",
  "status": "running",
  "created_at": "2026-05-18T10:30:00Z",
  "started_at": "2026-05-18T10:30:05Z",
  "completed_at": null,
  "exit_code": null,
  "nomad_allocation_id": "allocation_uuid"
}

4. List Job Runs

GET /runs

Returns a list of submitted job runs, optionally filtered by job_id or status.

Query Parameters:

• job_id (optional): Filter by job ID
• status (optional): Filter by status (pending, running, completed, failed)
• limit (optional): Maximum number of results (default: 50)

Response (200 OK):

{
  "runs": [
    {
      "run_id": "run_uuid",
      "job_id": "job_id",
      "status": "completed",
      "created_at": "2026-05-18T10:30:00Z",
      "started_at": "2026-05-18T10:30:05Z",
      "completed_at": "2026-05-18T10:35:00Z",
      "exit_code": 0,
      "nomad_allocation_id": "allocation_uuid"
    }
  ]
}

5. Cancel Job Run

POST /runs/{run_id}/cancel

Cancels a running job.

Response (200 OK):

{
  "run_id": "run_uuid",
  "status": "cancelled"
}

Response (409 Conflict):

{
  "error": "Cannot cancel completed job"
}

6. Get Job Output (Server-Sent Events)

GET /runs/{run_id}/output

Establishes an SSE connection to stream job output and status updates in real-time.

Response (200 OK - text/event-stream):

event: status
data: {"status": "running", "timestamp": "2026-05-18T10:30:05Z"}

event: output
data: {"type": "stdout", "line": "Processing started..."}

event: output
data: {"type": "stderr", "line": "Warning: resource limit approaching"}

event: status
data: {"status": "completed", "exit_code": 0, "timestamp": "2026-05-18T10:35:00Z"}

Event Types:

• status: Job status change with exit code on completion
• output: Stdout or stderr output line
• error: Stream error or connection closing

Status Values

• pending: Job queued but not yet started
• running: Job is currently executing
• completed: Job finished successfully
• failed: Job failed with non-zero exit code
• cancelled: Job was cancelled by user

Error Responses

All error responses follow this format:

{
  "error": "Error message",
  "status": "error_code"
}

Common HTTP status codes:

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Missing or invalid authentication token
• 404 Not Found: Job or run not found
• 409 Conflict: Invalid state transition
• 500 Internal Server Error: Server error