1500 lines
48 KiB
YAML
1500 lines
48 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
version: 1.0.0
|
|
title: Flamenco manager
|
|
description: Render Farm manager API
|
|
contact:
|
|
name: Flamenco Team
|
|
url: https://flamenco.io/
|
|
license:
|
|
name: GPLv3
|
|
url: https://www.gnu.org/licenses/gpl-3.0.en.html
|
|
servers:
|
|
- url: /
|
|
paths:
|
|
## Meta
|
|
|
|
/api/version:
|
|
summary: Clients can use this to check this is actually a Flamenco server.
|
|
get:
|
|
summary: Get the Flamenco version of this Manager
|
|
operationId: getVersion
|
|
tags: [meta]
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FlamencoVersion"
|
|
|
|
/api/configuration:
|
|
summary: Endpoint for getting configuration of Flamenco Manager.
|
|
get:
|
|
summary: Get the configuration of this Manager.
|
|
operationId: getConfiguration
|
|
tags: [meta]
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/ManagerConfiguration" }
|
|
|
|
## Worker
|
|
|
|
/api/worker/register-worker:
|
|
summary: Registration of new workers
|
|
post:
|
|
summary: Register a new worker
|
|
operationId: registerWorker
|
|
tags: [worker]
|
|
requestBody:
|
|
description: Worker to register
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerRegistration"
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RegisteredWorker"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/sign-on:
|
|
summary: Called by Workers to let the Manager know they're ready to work, and to update their metadata.
|
|
post:
|
|
summary: Authenticate & sign in the worker.
|
|
operationId: signOn
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
requestBody:
|
|
description: Worker metadata
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerSignOn"
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/sign-off:
|
|
summary: Called by Workers to let the Manager know they're going offline.
|
|
post:
|
|
summary: Mark the worker as offline
|
|
operationId: signOff
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: normal response
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/state:
|
|
summary: Called by Workers to check whether there is any state change requested.
|
|
get:
|
|
operationId: workerState
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: no state change requested
|
|
"200":
|
|
description: state change requested
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/state-changed:
|
|
summary: Called by Workers to let the Manager know they've changed status.
|
|
post:
|
|
summary: Worker changed state. This could be as acknowledgement of a Manager-requested state change, or in response to worker-local signals.
|
|
operationId: workerStateChanged
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
requestBody:
|
|
description: New worker state
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChanged"
|
|
responses:
|
|
"204":
|
|
description: normal response
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/task:
|
|
summary: Task scheduler endpoint.
|
|
post:
|
|
operationId: scheduleTask
|
|
summary: Obtain a new task to execute
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: No tasks available for this Worker.
|
|
"200":
|
|
description: Task to execute.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/AssignedTask" }
|
|
"403":
|
|
description: Permission Denied
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/SecurityError" }
|
|
"409":
|
|
description: Worker is not in the active state, so is not allowed to execute tasks right now.
|
|
"423":
|
|
description: Worker cannot obtain new tasks, but must go to another state.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
|
|
/api/worker/task/{task_id}:
|
|
summary: Workers send info about task progression here.
|
|
post:
|
|
operationId: taskUpdate
|
|
summary: Update the task, typically to indicate progress, completion, or failure.
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: Task update information
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskUpdate"
|
|
responses:
|
|
"204":
|
|
description: The update was accepted.
|
|
"409":
|
|
description: The task is assigned to another worker, so the update was not accepted.
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/task/{task_id}/may-i-run:
|
|
summary: Workers check whether they're allowed to keep running this task.
|
|
get:
|
|
operationId: mayWorkerRun
|
|
summary: >
|
|
The response indicates whether the worker is allowed to run / keep
|
|
running the task. Optionally contains a queued worker status change.
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MayKeepRunning"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
# Worker Management
|
|
/api/worker-mgt/workers:
|
|
summary: Obtain list of Workers known to the Manager.
|
|
get:
|
|
operationId: fetchWorkers
|
|
summary: Get list of workers.
|
|
tags: [worker-mgt]
|
|
responses:
|
|
"200":
|
|
description: Known workers
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/WorkerList" }
|
|
|
|
/api/worker-mgt/workers/{worker_id}:
|
|
summary: Get detailed worker info.
|
|
get:
|
|
operationId: fetchWorker
|
|
summary: Fetch info about the worker.
|
|
tags: [worker-mgt]
|
|
parameters:
|
|
- name: worker_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Worker info
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Worker" }
|
|
|
|
/api/worker-mgt/workers/{worker_id}/setstatus:
|
|
summary: Request a status change for the given worker.
|
|
post:
|
|
operationId: requestWorkerStatusChange
|
|
tags: [worker-mgt]
|
|
parameters:
|
|
- name: worker_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: The status change to request.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStatusChangeRequest"
|
|
responses:
|
|
"204":
|
|
description: Status change was accepted.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
## Jobs
|
|
|
|
/api/jobs/types:
|
|
summary: Available Flamenco job types.
|
|
get:
|
|
operationId: getJobTypes
|
|
summary: Get list of job types and their parameters.
|
|
tags: [jobs]
|
|
responses:
|
|
"200":
|
|
description: Available job types
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/AvailableJobTypes" }
|
|
|
|
/api/jobs/type/{typeName}:
|
|
summary: Info about a specific job type.
|
|
get:
|
|
operationId: getJobType
|
|
summary: Get single job type and its parameters.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: typeName
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Job type
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/AvailableJobType" }
|
|
|
|
/api/jobs:
|
|
summary: Job submission endpoint.
|
|
post:
|
|
operationId: submitJob
|
|
summary: Submit a new job for Flamenco Manager to execute.
|
|
tags: [jobs]
|
|
requestBody:
|
|
description: Job to submit
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SubmittedJob"
|
|
responses:
|
|
"200":
|
|
description: Job was succesfully compiled into individual tasks.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Job" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/jobs/query:
|
|
summary: Obtain jobs with filtering and sorting.
|
|
post:
|
|
operationId: queryJobs
|
|
summary: Fetch list of jobs.
|
|
tags: [jobs]
|
|
requestBody:
|
|
description: Specification of which jobs to get.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JobsQuery"
|
|
responses:
|
|
"200":
|
|
description: Normal query response, can be empty list if nothing matched the query.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobsQueryResult" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/jobs/{job_id}:
|
|
summary: Job info and management
|
|
get:
|
|
operationId: fetchJob
|
|
summary: Fetch info about the job.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Job info
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Job" }
|
|
|
|
/api/jobs/{job_id}/setstatus:
|
|
summary: Request a status change for the given job.
|
|
post:
|
|
operationId: setJobStatus
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: The status change to request.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JobStatusChange"
|
|
responses:
|
|
"204":
|
|
description: Status change was accepted.
|
|
"422":
|
|
description: The requested status change is not valid for the current status of the job.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/jobs/{job_id}/tasks:
|
|
summary: Access tasks of this job.
|
|
get:
|
|
operationId: fetchJobTasks
|
|
summary: Fetch a summary of all tasks of the given job.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Get summaries of the tasks of this job.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobTasksSummary" }
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/tasks/{task_id}:
|
|
summary: Fetch a single task
|
|
get:
|
|
operationId: fetchTask
|
|
summary: Fetch a single task.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: The task info.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Task" }
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/tasks/{task_id}/logtail:
|
|
summary: Fetch the task's last few log lines.
|
|
get:
|
|
operationId: fetchTaskLogTail
|
|
summary: Fetch the last few lines of the task's log.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: The task log.
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
"204":
|
|
description: Returned when the task has no log yet.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/tasks/{task_id}/setstatus:
|
|
summary: >
|
|
Request a status change for the given task. This may have effect on the
|
|
job status as well. This endpoint is meant for humans managing tasks via
|
|
the web interface. Workers post to `/api/worker/task/{task_id}` instead.
|
|
post:
|
|
operationId: setTaskStatus
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: The status change to request.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskStatusChange"
|
|
responses:
|
|
"204":
|
|
description: Status change was accepted.
|
|
"422":
|
|
description: The requested status change is not valid for the current status of the task.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
## Shaman
|
|
|
|
/shaman/checkout/requirements:
|
|
summary: Allows a client to check which files are available on the server, and which ones are still unknown.
|
|
post:
|
|
operationId: shamanCheckoutRequirements
|
|
summary: Checks a Shaman Requirements file, and reports which files are unknown.
|
|
tags: [shaman]
|
|
requestBody:
|
|
description: Set of files to check
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ShamanRequirementsRequest"
|
|
responses:
|
|
"200":
|
|
description: Subset of the posted requirements, indicating the unknown files.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ShamanRequirementsResponse"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/shaman/checkout/create:
|
|
summary: Symlink a set of files into the checkout area.
|
|
post:
|
|
operationId: shamanCheckout
|
|
summary: Create a directory, and symlink the required files into it. The files must all have been uploaded to Shaman before calling this endpoint.
|
|
tags: [shaman]
|
|
requestBody:
|
|
description: Set of files to check out.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ShamanCheckout"
|
|
responses:
|
|
"200":
|
|
description: Checkout was created succesfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ShamanCheckoutResult"
|
|
"424":
|
|
description: There were files missing. Use `shamanCheckoutRequirements` to figure out which ones.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"409":
|
|
description: Checkout already exists.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/shaman/files/{checksum}/{filesize}:
|
|
summary: Upload files to the Shaman server.
|
|
get:
|
|
operationId: shamanFileStoreCheck
|
|
summary: >
|
|
Check the status of a file on the Shaman server.
|
|
tags: [shaman]
|
|
parameters:
|
|
- name: checksum
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
description: SHA256 checksum of the file.
|
|
- name: filesize
|
|
in: path
|
|
required: true
|
|
schema: { type: integer }
|
|
description: Size of the file in bytes.
|
|
responses:
|
|
"200":
|
|
description: Normal response.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/ShamanSingleFileStatus" }
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
post:
|
|
operationId: shamanFileStore
|
|
summary: >
|
|
Store a new file on the Shaman server. Note that the Shaman server can
|
|
forcibly close the HTTP connection when another client finishes uploading
|
|
the exact same file, to prevent double uploads.
|
|
|
|
The file's contents should be sent in the request body.
|
|
tags: [shaman]
|
|
parameters:
|
|
- name: checksum
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
description: SHA256 checksum of the file.
|
|
- name: filesize
|
|
in: path
|
|
required: true
|
|
schema: { type: integer }
|
|
description: Size of the file in bytes.
|
|
- name: X-Shaman-Can-Defer-Upload
|
|
in: header
|
|
required: false
|
|
schema: { type: boolean }
|
|
description: >
|
|
The client indicates that it can defer uploading this file. The
|
|
"208" response will not only be returned when the file is already
|
|
fully known to the Shaman server, but also when someone else is
|
|
currently uploading this file.
|
|
- name: X-Shaman-Original-Filename
|
|
in: header
|
|
required: false
|
|
schema: { type: string }
|
|
description: >
|
|
The original filename. If sent along with the request, it will be
|
|
included in the server logs, which can aid in debugging.
|
|
requestBody:
|
|
description: Contents of the file
|
|
required: true
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
|
|
responses:
|
|
"204":
|
|
description: The file was accepted.
|
|
"208":
|
|
description: The file was already known to the server.
|
|
"417":
|
|
description: >
|
|
There was a mismatch between the request parameters and the actual
|
|
file size or checksum of the uploaded file.
|
|
"425":
|
|
description: >
|
|
Client should defer uploading this file. The file is currently in
|
|
the process of being uploaded by someone else, and
|
|
`X-Shaman-Can-Defer-Upload: true` was sent in the request.
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
tags:
|
|
- name: meta
|
|
description: Info about the Flamenco Manager itself.
|
|
- name: jobs
|
|
description: Job & task queries, submission, and management.
|
|
- name: worker
|
|
description: API for Flamenco Workers to communicate with Flamenco Manager.
|
|
- name: worker-mgt
|
|
description: Worker Management API, for the web interface to query and control Workers.
|
|
- name: shaman
|
|
description: Shaman API, for file uploading & creating job checkouts.
|
|
|
|
components:
|
|
schemas:
|
|
FlamencoVersion:
|
|
type: object
|
|
required: [version, name]
|
|
properties:
|
|
version: { type: string }
|
|
name: { type: string }
|
|
|
|
ManagerConfiguration:
|
|
type: object
|
|
properties:
|
|
"storageLocation":
|
|
description: Directory used for job file storage.
|
|
type: string
|
|
"shamanEnabled":
|
|
description: Whether the Shaman file transfer API is available.
|
|
type: boolean
|
|
required: [storageLocation, shamanEnabled]
|
|
|
|
WorkerRegistration:
|
|
type: object
|
|
required: [secret, platform, supported_task_types, nickname]
|
|
properties:
|
|
secret: { type: string }
|
|
platform: { type: string }
|
|
supported_task_types:
|
|
type: array
|
|
items: { type: string }
|
|
nickname: { type: string }
|
|
|
|
RegisteredWorker:
|
|
type: object
|
|
properties:
|
|
uuid: { type: string, format: uuid }
|
|
nickname: { type: string }
|
|
address: { type: string }
|
|
status: { $ref: "#/components/schemas/WorkerStatus" }
|
|
platform: { type: string }
|
|
software: { type: string }
|
|
supported_task_types:
|
|
type: array
|
|
items: { type: string }
|
|
required:
|
|
- uuid
|
|
- nickname
|
|
- address
|
|
- status
|
|
- platform
|
|
- current_task
|
|
- software
|
|
- supported_task_types
|
|
|
|
WorkerStatus:
|
|
type: string
|
|
enum: [starting, awake, asleep, error, shutdown, testing, offline]
|
|
|
|
WorkerSignOn:
|
|
type: object
|
|
properties:
|
|
nickname: { type: string }
|
|
supported_task_types:
|
|
type: array
|
|
items: { type: string }
|
|
software_version: { type: string }
|
|
required: [nickname, supported_task_types, software_version]
|
|
|
|
WorkerStateChange:
|
|
type: object
|
|
properties:
|
|
status_requested: { $ref: "#/components/schemas/WorkerStatus" }
|
|
required: [status_requested]
|
|
|
|
WorkerStateChanged:
|
|
type: object
|
|
properties:
|
|
status: { $ref: "#/components/schemas/WorkerStatus" }
|
|
required: [status]
|
|
|
|
AssignedTask:
|
|
type: object
|
|
description: AssignedTask is a task as it is received by the Worker.
|
|
properties:
|
|
uuid: { type: string, format: uuid }
|
|
job: { type: string }
|
|
name: { type: string }
|
|
status: { $ref: "#/components/schemas/TaskStatus" }
|
|
priority: { type: integer }
|
|
job_priority: { type: integer }
|
|
job_type: { type: string }
|
|
task_type: { type: string }
|
|
commands:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/Command" }
|
|
required:
|
|
- uuid
|
|
- job
|
|
- name
|
|
- status
|
|
- priority
|
|
- job_priority
|
|
- job_type
|
|
- task_type
|
|
- commands
|
|
|
|
TaskUpdate:
|
|
type: object
|
|
description: >
|
|
TaskUpdate is sent by a Worker to update the status & logs of a task
|
|
it's executing. All properties are optional; omitted properties are
|
|
ignored (i.e. omitting `activity` will not erase the activity property
|
|
of the task).
|
|
properties:
|
|
"taskStatus":
|
|
$ref: "#/components/schemas/TaskStatus"
|
|
description: The new task status.
|
|
"activity":
|
|
type: string
|
|
description: One-liner to indicate what's currently happening with the task. Overwrites previously sent activity strings.
|
|
"log":
|
|
type: string
|
|
description: Log lines for this task, will be appended to logs sent earlier.
|
|
|
|
MayKeepRunning:
|
|
type: object
|
|
description: Indicates whether the worker may keep running the task.
|
|
properties:
|
|
"mayKeepRunning": { type: boolean }
|
|
"reason": { type: string }
|
|
"statusChangeRequested":
|
|
type: boolean
|
|
description: >
|
|
Indicates that a status change requested for the worker. It should
|
|
use the `workerState` operation to determine which state to go to
|
|
next. If this is `true`, `mayKeepRunning` MUST be `false`.
|
|
required: ["mayKeepRunning", "reason", "statusChangeRequested"]
|
|
|
|
JobStatus:
|
|
type: string
|
|
enum:
|
|
- active
|
|
- canceled
|
|
- completed
|
|
- construction-failed
|
|
- failed
|
|
- paused
|
|
- queued
|
|
- archived
|
|
- archiving
|
|
- cancel-requested
|
|
- requeueing
|
|
- under-construction
|
|
|
|
TaskStatus:
|
|
type: string
|
|
enum:
|
|
- active
|
|
- canceled
|
|
- completed
|
|
- failed
|
|
- queued
|
|
- soft-failed
|
|
- paused
|
|
|
|
Command:
|
|
type: object
|
|
description: Command represents a single command to execute by the Worker.
|
|
properties:
|
|
name: { type: string }
|
|
parameters: { type: object }
|
|
required: [name, parameters]
|
|
|
|
AvailableJobTypes:
|
|
type: object
|
|
description: List of job types supported by this Manager.
|
|
properties:
|
|
"job_types":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/AvailableJobType" }
|
|
required: [job_types]
|
|
|
|
AvailableJobType:
|
|
type: object
|
|
description: Job type supported by this Manager, and its parameters.
|
|
properties:
|
|
"name": { type: string }
|
|
"label": { type: string }
|
|
"settings":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/AvailableJobSetting" }
|
|
required: [name, label, settings]
|
|
|
|
AvailableJobSetting:
|
|
type: object
|
|
description: Single setting of a Job types.
|
|
properties:
|
|
"key":
|
|
type: string
|
|
description: Identifier for the setting, must be unique within the job type.
|
|
"type": { $ref: "#/components/schemas/AvailableJobSettingType" }
|
|
"subtype": { $ref: "#/components/schemas/AvailableJobSettingSubtype" }
|
|
"choices":
|
|
description: When given, limit the valid values to these choices. Only usable with string type.
|
|
type: array
|
|
items: { type: string }
|
|
"propargs":
|
|
description: Any extra arguments to the bpy.props.SomeProperty() call used to create this property.
|
|
type: object
|
|
"description":
|
|
description: The description/tooltip shown in the user interface.
|
|
"default":
|
|
description: The default value shown to the user when determining this setting.
|
|
"eval":
|
|
type: string
|
|
description: Python expression to be evaluated in order to determine the default value for this setting.
|
|
"visible":
|
|
$ref: "#/components/schemas/AvailableJobSettingVisibility"
|
|
"required":
|
|
type: boolean
|
|
description: >
|
|
Whether to immediately reject a job definition, of this type,
|
|
without this particular setting.
|
|
default: false
|
|
"editable":
|
|
type: boolean
|
|
description: >
|
|
Whether to allow editing this setting after the job has been
|
|
submitted. Would imply deleting all existing tasks for this job, and
|
|
recompiling it.
|
|
default: false
|
|
required: [key, type]
|
|
|
|
AvailableJobSettingType:
|
|
type: string
|
|
description: >
|
|
Type of job setting, must be usable as IDProperty type in Blender. No
|
|
nested structures (arrays, dictionaries) are supported.
|
|
enum: [string, int32, float, bool]
|
|
|
|
AvailableJobSettingSubtype:
|
|
type: string
|
|
description: >
|
|
Sub-type of the job setting. Currently only available for string types.
|
|
`HASHED_FILE_PATH` is a directory path + `"/######"` appended.
|
|
enum: ["file_path", "dir_path", "file_name", "hashed_file_path"]
|
|
|
|
AvailableJobSettingVisibility:
|
|
type: string
|
|
description: >
|
|
When to show this setting.
|
|
`visible`: always show.
|
|
`submission`: only show in the UI of a job submitter (like a Blender add-on).
|
|
`web`: only show in the web interface for management, but not when submitting the job.
|
|
`hidden`: never show; only available to the job compiler script as internal setting.
|
|
enum: [visible, hidden, submission, web]
|
|
default: visible
|
|
|
|
SubmittedJob:
|
|
type: object
|
|
description: Job definition submitted to Flamenco.
|
|
properties:
|
|
"name": { type: string }
|
|
"type": { type: string }
|
|
"priority": { type: integer, default: 50 }
|
|
"settings": { $ref: "#/components/schemas/JobSettings" }
|
|
"metadata": { $ref: "#/components/schemas/JobMetadata" }
|
|
required: [name, type, priority]
|
|
example:
|
|
type: "simple-blender-render"
|
|
name: 3Д рендеринг
|
|
priority: 50
|
|
settings:
|
|
blender_cmd: "{blender}"
|
|
filepath: "/render/sf/jobs/scene123.blend"
|
|
render_output_root: "/render/sf/frames/scene123"
|
|
render_output_path: "/render/sf/frames/scene123/3Д рендеринг/######"
|
|
frames: "1-10"
|
|
chunk_size: 3
|
|
fps: 24
|
|
extract_audio: true
|
|
images_or_video: "images"
|
|
format: "PNG"
|
|
output_file_extension: ".png"
|
|
metadata:
|
|
"user.name": "Sybren Stüvel"
|
|
"user.email": "sybren@blender.org"
|
|
"project": "Sprite Fright"
|
|
Job:
|
|
allOf:
|
|
- $ref: "#/components/schemas/SubmittedJob"
|
|
- properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Job
|
|
created:
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp
|
|
updated:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last update.
|
|
status: { $ref: "#/components/schemas/JobStatus" }
|
|
activity:
|
|
type: string
|
|
description: Description of the last activity on this job.
|
|
required: [id, created, updated, status, activity]
|
|
|
|
JobSettings:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
JobMetadata:
|
|
type: object
|
|
description: Arbitrary metadata strings. More complex structures can be modeled by using `a.b.c` notation for the key.
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
"user.name": Sybren Stüvel
|
|
"user.email": sybren@blender.org
|
|
"project": "Sprite Fright"
|
|
|
|
JobsQuery:
|
|
type: object
|
|
properties:
|
|
"offset":
|
|
type: integer
|
|
minimum: 0
|
|
"limit":
|
|
type: integer
|
|
minimum: 1
|
|
"order_by":
|
|
type: array
|
|
items: { type: string }
|
|
"status_in":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/JobStatus" }
|
|
description: Return only jobs with a status in this array.
|
|
"metadata":
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Filter by metadata, using `LIKE` notation.
|
|
"settings":
|
|
type: object
|
|
additionalProperties: true
|
|
description: Filter by job settings, using `LIKE` notation.
|
|
example:
|
|
"limit": 5
|
|
"order_by": ["updated", "status"]
|
|
"status_in": ["active", "queued", "failed"]
|
|
"metadata": { project: "Sprite Fright" }
|
|
|
|
JobsQueryResult:
|
|
type: object
|
|
properties:
|
|
jobs:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/Job" }
|
|
required: [jobs]
|
|
|
|
Task:
|
|
type: object
|
|
description: The task as it exists in the Manager database, i.e. before variable replacement.
|
|
properties:
|
|
"id": { type: string, format: uuid }
|
|
"created":
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp
|
|
"updated":
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last update.
|
|
"job_id": { type: string, format: uuid }
|
|
"name": { type: string }
|
|
"status": { $ref: "#/components/schemas/TaskStatus" }
|
|
"priority": { type: integer }
|
|
"task_type": { type: string }
|
|
"activity": { type: string }
|
|
"commands":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/Command" }
|
|
"worker": { $ref: "#/components/schemas/TaskWorker" }
|
|
required:
|
|
- id
|
|
- created
|
|
- updated
|
|
- job_id
|
|
- name
|
|
- status
|
|
- priority
|
|
- task_type
|
|
- activity
|
|
- commands
|
|
|
|
TaskWorker:
|
|
type: object
|
|
properties:
|
|
"id": { type: string, format: uuid }
|
|
"name": { type: string }
|
|
"address": { type: string }
|
|
required: [id, name, address]
|
|
|
|
JobTasksSummary:
|
|
description: "Simplified list of tasks of a job. Contains all tasks, but not all info of each task."
|
|
type: object
|
|
properties:
|
|
tasks:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/TaskSummary" }
|
|
required: [jobs]
|
|
|
|
TaskSummary:
|
|
type: object
|
|
description: Just enough information about the task to show in the job's task list.
|
|
properties:
|
|
id: { type: string, format: uuid }
|
|
name: { type: string }
|
|
status: { $ref: "#/components/schemas/TaskStatus" }
|
|
priority: { type: integer }
|
|
task_type: { type: string }
|
|
updated: { type: string, format: date-time }
|
|
required: [id, name, status, priority, task_type, updated]
|
|
|
|
JobStatusChange:
|
|
type: object
|
|
properties:
|
|
status: { $ref: "#/components/schemas/JobStatus" }
|
|
reason:
|
|
type: string
|
|
description: The reason for this status change.
|
|
required: [status, reason]
|
|
|
|
TaskStatusChange:
|
|
type: object
|
|
properties:
|
|
status: { $ref: "#/components/schemas/TaskStatus" }
|
|
reason:
|
|
type: string
|
|
description: The reason for this status change.
|
|
required: [status, reason]
|
|
|
|
Error:
|
|
description: Generic error response.
|
|
type: object
|
|
required: [code, message]
|
|
properties:
|
|
code:
|
|
type: integer
|
|
format: int32
|
|
description: >
|
|
HTTP status code of this response. Is included in the payload so
|
|
that a single object represents all error information.
|
|
|
|
Code 503 is used when the database is busy. The HTTP response will
|
|
contain a 'Retry-After' HTTP header that indicates after which time
|
|
the request can be retried. Following the header is not mandatory,
|
|
and it's up to the client to do something reasonable like
|
|
exponential backoff.
|
|
message: { type: string }
|
|
|
|
SecurityError:
|
|
type: object
|
|
required: [message]
|
|
properties:
|
|
message: { type: string }
|
|
|
|
ShamanRequirementsRequest:
|
|
type: object
|
|
description: Set of files with their SHA256 checksum and size in bytes.
|
|
properties:
|
|
"files":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/ShamanFileSpec" }
|
|
required: [files]
|
|
example:
|
|
files:
|
|
- sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0
|
|
size: 1424
|
|
- sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079
|
|
size: 127
|
|
|
|
ShamanRequirementsResponse:
|
|
type: object
|
|
description: The files from a requirements request, with their status on the Shaman server. Files that are known to Shaman are excluded from the response.
|
|
properties:
|
|
"files":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/ShamanFileSpecWithStatus" }
|
|
required: [files]
|
|
example:
|
|
files:
|
|
- sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0
|
|
size: 1424
|
|
status: unknown
|
|
- sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079
|
|
size: 127
|
|
status: uploading
|
|
|
|
ShamanFileSpec:
|
|
type: object
|
|
description: Specification of a file in the Shaman storage.
|
|
properties:
|
|
"sha": { type: string, description: "SHA256 checksum of the file" }
|
|
"size": { type: integer, description: "File size in bytes" }
|
|
"path":
|
|
type: string
|
|
description: "Location of the file in the checkout"
|
|
required: [sha, size, path]
|
|
|
|
ShamanFileSpecWithStatus:
|
|
# Using allOf here would trigger a bug in the Python code generator,
|
|
# resulting in this error:
|
|
#
|
|
# Values stored for property status in ShamanFileSpecWithStatus differ
|
|
# when looking at self and self's composed instances. All values must be
|
|
# the same at ['['received_data', 'files', 0]']['status']
|
|
#
|
|
# The underlying cause is that composited types can apparently store
|
|
# property values multiple times, and these have to be equal. However, one
|
|
# is using the `ShamanFileStatus` type, and the other is using the `str`
|
|
# type to store the same status value.
|
|
#
|
|
# To work around this, even though this should be a composition of
|
|
# `ShamanFileSpec` with some extra properties, we just repeat those same
|
|
# properties here.
|
|
type: object
|
|
description: Specification of a file, which could be in the Shaman storage, or not, depending on its status.
|
|
properties:
|
|
"sha": { type: string, description: "SHA256 checksum of the file" }
|
|
"size": { type: integer, description: "File size in bytes" }
|
|
"path":
|
|
type: string
|
|
description: "Location of the file in the checkout"
|
|
"status": { $ref: "#/components/schemas/ShamanFileStatus" }
|
|
required: [sha, size, path, status]
|
|
|
|
ShamanCheckout:
|
|
type: object
|
|
description: Set of files with their SHA256 checksum, size in bytes, and desired location in the checkout directory.
|
|
properties:
|
|
"files":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/ShamanFileSpec" }
|
|
"checkoutPath":
|
|
type: string
|
|
description: >
|
|
Path where the Manager should create this checkout. It is relative
|
|
to the Shaman checkout path as configured on the Manager. In older
|
|
versions of the Shaman this was just the "checkout ID", but in this
|
|
version it can be a path like `project-slug/scene-name/unique-ID`.
|
|
required: [files, checkoutPath]
|
|
example:
|
|
files:
|
|
- sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0
|
|
size: 1424
|
|
path: definition.go
|
|
- sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079
|
|
size: 127
|
|
path: logging.go
|
|
|
|
ShamanCheckoutResult:
|
|
type: object
|
|
description: The result of a Shaman checkout.
|
|
properties:
|
|
"checkoutPath":
|
|
type: string
|
|
description: >
|
|
Path where the Manager created this checkout. This can be different
|
|
than what was requested, as the Manager will ensure a unique
|
|
directory. The path is relative to the Shaman checkout path as
|
|
configured on the Manager.
|
|
required: [checkoutPath]
|
|
|
|
ShamanFileStatus:
|
|
type: string
|
|
enum: [unknown, uploading, stored]
|
|
|
|
ShamanSingleFileStatus:
|
|
type: object
|
|
description: Status of a file in the Shaman storage.
|
|
properties:
|
|
"status": { $ref: "#/components/schemas/ShamanFileStatus" }
|
|
required: [status]
|
|
|
|
# SocketIO API. These types are not used in any HTTP operation defined in
|
|
# the 'paths' section of this document, so some code generators may choose
|
|
# to skip these.
|
|
|
|
SocketIOJobUpdate:
|
|
type: object
|
|
description: >
|
|
Subset of a Job, sent over SocketIO when a job changes.
|
|
For new jobs, `previous_status` will be excluded.
|
|
properties:
|
|
"id":
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Job
|
|
"name": { type: string, description: "Name of the job" }
|
|
"updated":
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last update
|
|
"status": { $ref: "#/components/schemas/JobStatus" }
|
|
"previous_status": { $ref: "#/components/schemas/JobStatus" }
|
|
"type": { type: string }
|
|
"priority": { type: integer, default: 50 }
|
|
"refresh_tasks":
|
|
type: boolean
|
|
description: >
|
|
Indicates that the client should refresh all the job's tasks. This
|
|
is sent for mass updates, where updating each individual task would
|
|
generate too many updates to be practical.
|
|
required: [id, updated, status, type, priority, refresh_tasks]
|
|
|
|
SocketIOTaskUpdate:
|
|
type: object
|
|
description: >
|
|
Subset of a Task, sent over SocketIO when a task changes.
|
|
For new tasks, `previous_status` will be excluded.
|
|
properties:
|
|
"id":
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Task
|
|
"job_id": { type: string, format: uuid }
|
|
"name": { type: string, description: "Name of the task" }
|
|
"updated":
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last update
|
|
"status": { $ref: "#/components/schemas/TaskStatus" }
|
|
"previous_status": { $ref: "#/components/schemas/TaskStatus" }
|
|
"activity": { type: string }
|
|
required: [id, job_id, name, updated, status, activity]
|
|
|
|
SocketIOTaskLogUpdate:
|
|
type: object
|
|
description: >
|
|
Task log chunk, sent to a SocketIO room dedicated to a single task, to
|
|
avoid sending too many updates.
|
|
properties:
|
|
"task_id":
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Task
|
|
"log":
|
|
type: string
|
|
description: Chunk of the task log. May contain multiple lines of text.
|
|
required: [task_id, log]
|
|
|
|
SocketIOWorkerUpdate:
|
|
type: object
|
|
description: >
|
|
Subset of a Worker, sent over SocketIO when a worker changes.
|
|
properties:
|
|
"id":
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Worker
|
|
"nickname": { type: string, description: "Name of the worker" }
|
|
"updated":
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last update
|
|
"status": { $ref: "#/components/schemas/WorkerStatus" }
|
|
"previous_status": { $ref: "#/components/schemas/WorkerStatus" }
|
|
"status_change":
|
|
$ref: "#/components/schemas/WorkerStatusChangeRequest"
|
|
"version": { type: string }
|
|
required: [id, nickname, updated, status, version]
|
|
|
|
SocketIOSubscription:
|
|
type: object
|
|
description: >
|
|
Send by SocketIO clients as `/subscription` event type, to manage their
|
|
subscription to job updates. Clients always get job updates, but for
|
|
task updates or task logs they need to explicitly subscribe. For
|
|
simplicity, clients can only subscribe to one job (to get task updates
|
|
for that job) and one task's log at a time.
|
|
properties:
|
|
"op": { $ref: "#/components/schemas/SocketIOSubscriptionOperation" }
|
|
"type": { $ref: "#/components/schemas/SocketIOSubscriptionType" }
|
|
"uuid":
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the thing to subscribe to / unsubscribe from.
|
|
required: [op, type]
|
|
|
|
SocketIOSubscriptionOperation:
|
|
type: string
|
|
enum: [subscribe, unsubscribe]
|
|
|
|
SocketIOSubscriptionType:
|
|
type: string
|
|
enum: [allJobs, allWorkers, job, tasklog]
|
|
description: What kind of thing to subscribe to / unsubscribe from.
|
|
|
|
# Worker Management
|
|
|
|
WorkerList:
|
|
type: object
|
|
description: List of workers.
|
|
properties:
|
|
"workers":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/WorkerSummary" }
|
|
required: [workers]
|
|
|
|
WorkerSummary:
|
|
type: object
|
|
description: Basic information about a Worker.
|
|
properties:
|
|
"id": { type: string, format: uuid }
|
|
"nickname": { type: string }
|
|
"status": { $ref: "#/components/schemas/WorkerStatus" }
|
|
"status_change":
|
|
$ref: "#/components/schemas/WorkerStatusChangeRequest"
|
|
# These will be implemented soon:
|
|
# "task_id":
|
|
# type: string
|
|
# format: uuid
|
|
# description: The worker's current/last-worked-on task.
|
|
# "last_seen":
|
|
# type: string
|
|
# format: date-time
|
|
# description: Last time this worker was seen by the Manager.
|
|
"version":
|
|
type: string
|
|
description: Version of Flamenco this Worker is running
|
|
required: [id, nickname, status, version]
|
|
|
|
Worker:
|
|
description: All information about a Worker
|
|
allOf:
|
|
- $ref: "#/components/schemas/WorkerSummary"
|
|
- properties:
|
|
"ip_address":
|
|
type: string
|
|
description: IP address of the Worker
|
|
"platform":
|
|
type: string
|
|
description: Operating system of the Worker
|
|
"supported_task_types":
|
|
type: array
|
|
items: { type: string }
|
|
required:
|
|
- id
|
|
- nickname
|
|
- status
|
|
- ip_address
|
|
- platform
|
|
- version
|
|
- supported_task_types
|
|
|
|
WorkerStatusChangeRequest:
|
|
type: object
|
|
description: Request for a Worker to change its status to `status`.
|
|
properties:
|
|
"status": { $ref: "#/components/schemas/WorkerStatus" }
|
|
"is_lazy":
|
|
type: boolean
|
|
description: >
|
|
Whether the status change should happen immediately, or after the
|
|
worker's current task is finished.
|
|
required: [status, is_lazy]
|
|
|
|
securitySchemes:
|
|
worker_auth:
|
|
description: Username is the worker ID, password is the secret given at worker registration.
|
|
type: http
|
|
scheme: basic
|