Sybren A. Stüvel
aff6d41a91
This endpoint will not actually delete the jobs, but just mark them for deletion. Flamenco Manager will process the deletions in the background.
2559 lines
83 KiB
YAML
2559 lines
83 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/v3/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/v3/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" }
|
|
|
|
/api/v3/configuration/check/shared-storage:
|
|
summary: Validate a path for use as shared storage.
|
|
post:
|
|
summary: Validate a path for use as shared storage.
|
|
operationId: checkSharedStoragePath
|
|
tags: [meta]
|
|
requestBody:
|
|
description: Path to check
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/PathCheckInput" }
|
|
responses:
|
|
"200":
|
|
description: Normal response, path check went fine.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/PathCheckResult" }
|
|
default:
|
|
description: Something went wrong.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/v3/configuration/check/blender:
|
|
summary: Find & validate a Blender executable.
|
|
get:
|
|
summary: Find one or more CLI commands for use as way to start Blender
|
|
operationId: findBlenderExePath
|
|
tags: [meta]
|
|
responses:
|
|
"200":
|
|
description: Found locations of Blender.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/BlenderPathFindResult" }
|
|
default:
|
|
description: Something went wrong.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
post:
|
|
summary: Validate a CLI command for use as way to start Blender
|
|
operationId: checkBlenderExePath
|
|
tags: [meta]
|
|
requestBody:
|
|
description: Command or executable path to check
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/PathCheckInput" }
|
|
responses:
|
|
"200":
|
|
description: Normal response, path check went fine.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/BlenderPathCheckResult" }
|
|
default:
|
|
description: Something went wrong.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/v3/configuration/setup-assistant:
|
|
summary: Save the configuration from the Setup Assistant.
|
|
post:
|
|
summary: Update the Manager's configuration, and restart it in fully functional mode.
|
|
tags: [meta]
|
|
operationId: saveSetupAssistantConfig
|
|
requestBody:
|
|
description: Configuration to save.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/SetupAssistantConfig" }
|
|
responses:
|
|
"204":
|
|
description: Normal response. The webapp should do a full refresh at this point.
|
|
default:
|
|
description: Something went wrong.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/v3/configuration/file:
|
|
summary: >
|
|
Access to the configuration file of Flamenco Manager. This is not schema'd
|
|
in OpenAPI, but follows the `internal/manager/config` package.
|
|
get:
|
|
summary: Retrieve the configuration of Flamenco Manager.
|
|
operationId: getConfigurationFile
|
|
tags: [meta]
|
|
responses:
|
|
"200":
|
|
description: Normal response.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
application/yaml:
|
|
schema:
|
|
type: string
|
|
|
|
/api/v3/configuration/variables/{audience}/{platform}:
|
|
summary: Endpoint for getting the variables from Flamenco Manager's configuration.
|
|
get:
|
|
summary: >
|
|
Get the variables of this Manager. Used by the Blender add-on to
|
|
recognise two-way variables, and for the web interface to do variable
|
|
replacement based on the browser's platform.
|
|
operationId: getVariables
|
|
tags: [meta]
|
|
parameters:
|
|
- name: audience
|
|
in: path
|
|
required: true
|
|
schema: { $ref: "#/components/schemas/ManagerVariableAudience" }
|
|
- name: platform
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Normal response.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/ManagerVariables" }
|
|
|
|
/api/v3/configuration/shared-storage/{audience}/{platform}:
|
|
summary: Endpoint for getting the shared storage location from Flamenco Manager's configuration.
|
|
get:
|
|
summary: >
|
|
Get the shared storage location of this Manager, adjusted for the given
|
|
audience and platform.
|
|
operationId: getSharedStorage
|
|
tags: [meta]
|
|
parameters:
|
|
- name: audience
|
|
in: path
|
|
required: true
|
|
schema: { $ref: "#/components/schemas/ManagerVariableAudience" }
|
|
- name: platform
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Normal response.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/SharedStorageLocation" }
|
|
|
|
## Worker
|
|
|
|
/api/v3/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/v3/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/v3/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/v3/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/v3/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/v3/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/v3/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/v3/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"
|
|
|
|
/api/v3/worker/task/{task_id}/output-produced:
|
|
summary: Workers send thumbnails/previews of their last-produced output here.
|
|
post:
|
|
operationId: taskOutputProduced
|
|
summary: >
|
|
Store the most recently rendered frame here. Note that it is up to the
|
|
Worker to ensure this is in a format that's digestable by the Manager.
|
|
Currently only PNG and JPEG support is planned.
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: Contents of the file
|
|
required: true
|
|
content:
|
|
image/jpeg: { schema: { type: string, format: binary } }
|
|
image/png: { schema: { type: string, format: binary } }
|
|
responses:
|
|
"202":
|
|
description: The file was accepted for processing.
|
|
"411":
|
|
description: Length required; the client did not send a Content-Length header.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"413":
|
|
description: Payload too large.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"415":
|
|
description: Unsupported Media Type, the image format cannot be processed by the Manager.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"429":
|
|
description: The client is sending too many frames, and should throttle itself.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
# Worker Management
|
|
/api/v3/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/v3/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" }
|
|
delete:
|
|
operationId: deleteWorker
|
|
summary: >
|
|
Remove the given worker. It is recommended to only call this function
|
|
when the worker is in `offline` state. If the worker is still running,
|
|
stop it first. Any task still assigned to the worker will be requeued.
|
|
tags: [worker-mgt]
|
|
parameters:
|
|
- name: worker_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"204":
|
|
description: Normal response, worker has been deleted
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/v3/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"
|
|
|
|
/api/v3/worker-mgt/workers/{worker_id}/settags:
|
|
summary: Update the tag membership of this Worker.
|
|
post:
|
|
operationId: setWorkerTags
|
|
tags: [worker-mgt]
|
|
parameters:
|
|
- name: worker_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: The list of worker tag IDs this worker should be a member of.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerTagChangeRequest"
|
|
responses:
|
|
"204":
|
|
description: Status change was accepted.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/v3/worker-mgt/workers/{worker_id}/sleep-schedule:
|
|
summary: Get or update the worker's sleep schedule.
|
|
get:
|
|
operationId: fetchWorkerSleepSchedule
|
|
tags: [worker-mgt]
|
|
parameters:
|
|
- name: worker_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Normal response, the sleep schedule.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerSleepSchedule"
|
|
"204":
|
|
description: The worker has no sleep schedule.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
post:
|
|
operationId: setWorkerSleepSchedule
|
|
tags: [worker-mgt]
|
|
parameters:
|
|
- name: worker_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: The new sleep schedule.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerSleepSchedule"
|
|
responses:
|
|
"204":
|
|
description: The schedule has been stored.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/v3/worker-mgt/tags:
|
|
summary: Manage worker tags.
|
|
get:
|
|
operationId: fetchWorkerTags
|
|
summary: Get list of worker tags.
|
|
tags: [worker-mgt]
|
|
responses:
|
|
"200":
|
|
description: Worker tags.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/WorkerTagList" }
|
|
post:
|
|
operationId: createWorkerTag
|
|
summary: Create a new worker tag.
|
|
tags: [worker-mgt]
|
|
requestBody:
|
|
description: The worker tag.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerTag"
|
|
responses:
|
|
"200":
|
|
description: The tag was created. The created tag is returned, so that the caller can know its UUID.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/WorkerTag" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/v3/worker-mgt/tag/{tag_id}:
|
|
summary: Get, update, or delete a worker tag.
|
|
parameters:
|
|
- name: tag_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
get:
|
|
operationId: fetchWorkerTag
|
|
summary: Get a single worker tag.
|
|
tags: [worker-mgt]
|
|
responses:
|
|
"200":
|
|
description: The worker tag.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/WorkerTag" }
|
|
put:
|
|
operationId: updateWorkerTag
|
|
summary: Update an existing worker tag.
|
|
tags: [worker-mgt]
|
|
requestBody:
|
|
description: The updated worker tag.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerTag"
|
|
responses:
|
|
"204":
|
|
description: The tag update has been stored.
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
delete:
|
|
operationId: deleteWorkerTag
|
|
summary: Remove this worker tag. This unassigns all workers from the tag and removes it.
|
|
tags: [worker-mgt]
|
|
responses:
|
|
"204":
|
|
description: The tag has been removed.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
## Jobs
|
|
|
|
/api/v3/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/v3/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/v3/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" }
|
|
"412":
|
|
description: >
|
|
The given job type etag does not match the job type etag on the
|
|
Manager. This is likely due to the client caching the job type for
|
|
too long.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/v3/jobs/mass-delete:
|
|
summary: >
|
|
Mark many jobs for deletion, based on certain criteria. This endpoint will
|
|
not actually delete the jobs, but just mark them for deletion. Flamenco
|
|
Manager will process the deletions in the background.
|
|
|
|
Note that the `last_updated_max` parameter is rounded up to entire
|
|
seconds. This may mark more jobs for deletion than you expect, if their
|
|
`updated_at` timestamps differ by less than a second.
|
|
delete:
|
|
operationId: deleteJobMass
|
|
summary: Mark jobs for deletion, based on certain criteria.
|
|
tags: [jobs]
|
|
requestBody:
|
|
description: Parameters to determine which jobs to delete.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JobMassDeletionSelection"
|
|
responses:
|
|
"204":
|
|
description: Jobs were succesfully marked for deletion.
|
|
"416":
|
|
description: There were no jobs that match the request.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/v3/jobs/check:
|
|
summary: Check the job for validity, without creating it.
|
|
post:
|
|
operationId: submitJobCheck
|
|
summary: Submit a new job for Flamenco Manager to check.
|
|
tags: [jobs]
|
|
requestBody:
|
|
description: Job to check
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SubmittedJob"
|
|
responses:
|
|
"204":
|
|
description: Job was succesfully compiled into individual tasks. The job and tasks have NOT been stored in the database, though.
|
|
"412":
|
|
description: >
|
|
The given job type etag does not match the job type etag on the
|
|
Manager. This is likely due to the client caching the job type for
|
|
too long.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/v3/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/v3/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" }
|
|
delete:
|
|
operationId: deleteJob
|
|
summary: >
|
|
Request deletion this job, including its tasks and any log files.
|
|
The actual deletion may happen in the background.
|
|
No job files will be deleted (yet).
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"204":
|
|
description: Default response, deletion has been triggered.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/v3/jobs/{job_id}/what-would-delete-do:
|
|
summary: Get info about what would be deleted when deleting this job.
|
|
get:
|
|
operationId: deleteJobWhatWouldItDo
|
|
summary: >
|
|
Get info about what would be deleted when deleting this job. The job
|
|
itself, its logs, and the last-rendered images will always be deleted.
|
|
The job files are only deleted conditionally, and this operation can be
|
|
used to figure that out.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Job deletion info
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobDeletionInfo" }
|
|
|
|
/api/v3/jobs/{job_id}/last-rendered:
|
|
summary: Obtain info about the last-rendered images for this job.
|
|
get:
|
|
operationId: fetchJobLastRenderedInfo
|
|
summary: Get the URL that serves the last-rendered images of this job.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Normal response.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobLastRenderedImageInfo" }
|
|
"204":
|
|
description: This job doesn't have any last-rendered image.
|
|
|
|
/api/v3/jobs/last-rendered:
|
|
summary: Obtain info about the global last-rendered image.
|
|
get:
|
|
operationId: fetchGlobalLastRenderedInfo
|
|
summary: Get the URL that serves the last-rendered images.
|
|
tags: [jobs]
|
|
responses:
|
|
"200":
|
|
description: Normal response.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobLastRenderedImageInfo" }
|
|
"204":
|
|
description: This job doesn't have any last-rendered image.
|
|
|
|
/api/v3/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/v3/jobs/{job_id}/setpriority:
|
|
summary: Request a priority change for the given job.
|
|
post:
|
|
operationId: setJobPriority
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: The new priority.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JobPriorityChange"
|
|
responses:
|
|
"204":
|
|
description: Priority change was accepted.
|
|
"422":
|
|
description: The requested priority is not acceptable.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/v3/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/v3/jobs/{job_id}/blocklist:
|
|
summary: Access blocklist of this job.
|
|
get:
|
|
operationId: fetchJobBlocklist
|
|
summary: Fetch the list of workers that are blocked from doing certain task types on this job.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Get tuples (worker, task type) that got blocked on this job.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobBlocklist" }
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
delete:
|
|
operationId: removeJobBlocklist
|
|
summary: Remove entries from a job blocklist.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: Tuples (worker, task type) to be removed from the blocklist.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobBlocklist" }
|
|
responses:
|
|
"204":
|
|
description: Request accepted, entries have been removed.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/v3/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/v3/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/v3/tasks/{task_id}/log:
|
|
summary: Retrieve info about the task log.
|
|
get:
|
|
operationId: fetchTaskLogInfo
|
|
summary: Get the URL of the task log, and some more info.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: The task log info.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskLogInfo"
|
|
"204":
|
|
description: Returned when the task has no log yet.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/v3/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/v3/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
|
|
|
|
/api/v3/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"
|
|
|
|
/api/v3/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"
|
|
|
|
/api/v3/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
|
|
properties:
|
|
"version":
|
|
type: string
|
|
description: >
|
|
Version of this Manager, meant for human consumption. For release
|
|
builds it is the same as `shortversion`, for other builds it also
|
|
includes the `git` version info.
|
|
"shortversion": { type: string }
|
|
"name": { type: string }
|
|
"git": { type: string }
|
|
required: [version, shortversion, name, git]
|
|
example:
|
|
version: "3.3-alpha0 (v3.2-76-gdd34d538)"
|
|
shortversion: 3.3-alpha0
|
|
name: Your Manager
|
|
git: v3.2-76-gdd34d538
|
|
|
|
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
|
|
"isFirstRun":
|
|
description: >
|
|
Whether this is considered the first time the Manager runs. This is
|
|
determined by a few factors, like a non-existent configuration file
|
|
or certain settings being empty while they shouldn't be.
|
|
type: boolean
|
|
required: [storageLocation, shamanEnabled, isFirstRun]
|
|
|
|
SetupAssistantConfig:
|
|
type: object
|
|
description: Configuration obtained from the Setup Assistant.
|
|
properties:
|
|
"storageLocation":
|
|
description: Directory used for job file storage.
|
|
type: string
|
|
"blenderExecutable":
|
|
$ref: "#/components/schemas/BlenderPathCheckResult"
|
|
required: [storageLocation, blenderExecutable]
|
|
|
|
ManagerVariables:
|
|
description: Mapping from variable name to its properties.
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/ManagerVariable"
|
|
|
|
ManagerVariable:
|
|
type: object
|
|
properties:
|
|
"value": { type: string }
|
|
"is_twoway":
|
|
type: boolean
|
|
description: >
|
|
One-way variables are the most common one, and are simple
|
|
replacement from `{name}` to their value, which happens when a Task
|
|
is given to a Worker. Two-way variables are also replaced when
|
|
submitting a job, where the platform-specific value is replaced by
|
|
`{name}`.
|
|
required: [name, is_twoway, value]
|
|
|
|
ManagerVariableAudience:
|
|
type: string
|
|
enum: [workers, users]
|
|
|
|
SharedStorageLocation:
|
|
type: object
|
|
description: >
|
|
Location of the shared storage, adjusted for a specific audience &
|
|
platform. This uses two-way variables to adjust the shared storage path
|
|
from the Manager's configuration.
|
|
properties:
|
|
"location": { type: string }
|
|
"audience": { $ref: "#/components/schemas/ManagerVariableAudience" }
|
|
"platform": { type: string }
|
|
"shamanEnabled":
|
|
description: Whether the Shaman file transfer API is available.
|
|
type: boolean
|
|
required: [location, audience, platform, shamanEnabled]
|
|
|
|
PathCheckInput:
|
|
type: object
|
|
properties:
|
|
"path": { type: string }
|
|
required: [path]
|
|
|
|
PathCheckResult:
|
|
type: object
|
|
properties:
|
|
"path":
|
|
description: The path that was checked.
|
|
type: string
|
|
"is_usable":
|
|
description: Whether the path is usable or not.
|
|
type: boolean
|
|
"cause":
|
|
description: Description of why this path is (not) usable.
|
|
type: string
|
|
required: [path, is_usable, cause]
|
|
|
|
BlenderPathFindResult:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/BlenderPathCheckResult"
|
|
|
|
BlenderPathCheckResult:
|
|
type: object
|
|
properties:
|
|
"input":
|
|
description: The input that was given to find this Blender.
|
|
type: string
|
|
"path":
|
|
description: The path that was found.
|
|
type: string
|
|
"source":
|
|
$ref: "#/components/schemas/BlenderPathSource"
|
|
"is_usable":
|
|
description: Whether the path is usable or not.
|
|
type: boolean
|
|
"cause":
|
|
description: Description of why this path is (not) usable.
|
|
type: string
|
|
required: [input, path, source, is_usable, cause]
|
|
|
|
BlenderPathSource:
|
|
type: string
|
|
enum:
|
|
# The reported path is the result of inspecting the association with .blend files.
|
|
# This is only checked when the input path is empty.
|
|
- file_association
|
|
# The input path was interpreted as simple command, and found on $PATH.
|
|
- path_envvar
|
|
# The input path was used as-is, as it points to an existing binary.
|
|
- input_path
|
|
|
|
WorkerRegistration:
|
|
type: object
|
|
required: [secret, platform, supported_task_types, name]
|
|
properties:
|
|
secret: { type: string }
|
|
platform: { type: string }
|
|
supported_task_types:
|
|
type: array
|
|
items: { type: string }
|
|
name: { type: string }
|
|
example:
|
|
"name": "example-worker"
|
|
"secret": "do-not-tell-anyone"
|
|
"platform": "linux"
|
|
"software": "3.2"
|
|
"supported_task_types": ["blender", "ffmpeg", "file-management", "misc"]
|
|
|
|
RegisteredWorker:
|
|
type: object
|
|
properties:
|
|
uuid: { type: string, format: uuid }
|
|
name: { 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
|
|
- name
|
|
- address
|
|
- status
|
|
- platform
|
|
- current_task
|
|
- software
|
|
- supported_task_types
|
|
|
|
WorkerStatus:
|
|
type: string
|
|
enum: [starting, awake, asleep, error, testing, offline, restart]
|
|
|
|
WorkerSignOn:
|
|
type: object
|
|
properties:
|
|
name: { type: string }
|
|
supported_task_types:
|
|
type: array
|
|
items: { type: string }
|
|
software_version: { type: string }
|
|
can_restart: { type: boolean }
|
|
required: [name, supported_task_types, software_version]
|
|
example:
|
|
# This example may be nice to use from the SwaggerUI interface.
|
|
name: API user
|
|
supported_task_types: [blender, ffmpeg, file-management, misc]
|
|
software_version: swagger-ui
|
|
can_restart: false
|
|
|
|
WorkerStateChange:
|
|
type: object
|
|
properties:
|
|
status_requested: { $ref: "#/components/schemas/WorkerStatus" }
|
|
required: [status_requested]
|
|
|
|
WorkerStateChanged:
|
|
type: object
|
|
properties:
|
|
status: { $ref: "#/components/schemas/WorkerStatus" }
|
|
required: [status]
|
|
example:
|
|
status: "awake"
|
|
|
|
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
|
|
- failed
|
|
- paused
|
|
- queued
|
|
- 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" }
|
|
"etag":
|
|
type: string
|
|
description: >
|
|
Hash of the job type. If the job settings or the label change, this
|
|
etag will change. This is used on job submission to ensure that the
|
|
submitted job settings are up to date.
|
|
required: [name, label, settings, etag]
|
|
|
|
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.
|
|
"evalInfo":
|
|
type: object
|
|
description: Meta-data for the 'eval' expression.
|
|
properties:
|
|
"showLinkButton":
|
|
type: boolean
|
|
default: false
|
|
description: >
|
|
Enables the 'eval on submit' toggle button behavior for this setting.
|
|
A toggle button will be shown in Blender's submission interface.
|
|
When toggled on, the `eval` expression will determine the setting's
|
|
value. Manually editing the setting is then no longer possible, and
|
|
instead of an input field, the 'description' string is shown.
|
|
|
|
An example use is the to-be-rendered frame range, which by default
|
|
automatically follows the scene range, but can be overridden
|
|
manually when desired.
|
|
"description":
|
|
type: string
|
|
default: ""
|
|
description: >
|
|
Description of what the 'eval' expression is doing.
|
|
It is also used as placeholder text to show when the manual
|
|
input field is hidden (because eval-on-submit has been toggled
|
|
on by the user).
|
|
required: [showLinkButton, description]
|
|
"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 }
|
|
"type_etag":
|
|
type: string
|
|
description: >
|
|
Hash of the job type, copied from the `AvailableJobType.etag`
|
|
property of the job type. The job will be rejected if this field
|
|
doesn't match the actual job type on the Manager. This prevents job
|
|
submission with old settings, after the job compiler script has been
|
|
updated.
|
|
|
|
If this field is ommitted, the check is bypassed.
|
|
"priority": { type: integer, default: 50 }
|
|
"settings": { $ref: "#/components/schemas/JobSettings" }
|
|
"metadata": { $ref: "#/components/schemas/JobMetadata" }
|
|
"submitter_platform":
|
|
type: string
|
|
description: >
|
|
Operating system of the submitter. This is used to recognise two-way
|
|
variables. This should be a lower-case version of the platform, like
|
|
"linux", "windows", "darwin", "openbsd", etc. Should be ompatible
|
|
with Go's `runtime.GOOS`; run `go tool dist list` to get a list of
|
|
possible platforms.
|
|
|
|
As a special case, the platform "manager" can be given, which will
|
|
be interpreted as "the Manager's platform". This is mostly to make
|
|
test/debug scripts easier, as they can use a static document on all
|
|
platforms.
|
|
"storage": { $ref: "#/components/schemas/JobStorageInfo" }
|
|
"worker_tag":
|
|
type: string
|
|
format: uuid
|
|
description: >
|
|
Worker tag that should execute this job. When a tag ID is
|
|
given, only Workers in that tag will be scheduled to work on it.
|
|
If empty or ommitted, all workers can work on this job.
|
|
required: [name, type, priority, submitter_platform]
|
|
example:
|
|
type: "simple-blender-render"
|
|
name: 3Д рендеринг
|
|
priority: 50
|
|
submitter_platform: linux
|
|
settings:
|
|
blendfile: "/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
|
|
format: "PNG"
|
|
has_previews: false
|
|
image_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.
|
|
delete_requested_at:
|
|
type: string
|
|
format: date-time
|
|
description: >
|
|
If job deletion was requested, this is the timestamp at which
|
|
that request was stored on Flamenco Manager.
|
|
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"
|
|
|
|
JobStorageInfo:
|
|
type: object
|
|
description: >
|
|
Storage info of a job, which Flamenco can use to remove job-related
|
|
files when necessary.
|
|
properties:
|
|
"shaman_checkout_id":
|
|
type: string
|
|
description: >
|
|
'Checkout ID' used when creating the Shaman checkout for this job.
|
|
Aids in removing the checkout directory when the job is removed from
|
|
Flamenco.
|
|
|
|
JobDeletionInfo:
|
|
type: object
|
|
description: Info about what will be deleted when this job is deleted.
|
|
properties:
|
|
"shaman_checkout":
|
|
type: boolean
|
|
description: Whether the Shaman checkout directory will be removed along with the job.
|
|
required: ["shaman_checkout"]
|
|
|
|
JobMassDeletionSelection:
|
|
type: object
|
|
description: Parameters to describe which jobs should be deleted.
|
|
properties:
|
|
"last_updated_max":
|
|
type: string
|
|
format: date-time
|
|
description: All jobs that were last updated before or on this timestamp will be deleted.
|
|
example:
|
|
"last_updated_max": "2023-06-01T13:14:15+02:00"
|
|
|
|
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_at", "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" }
|
|
"last_touched":
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of when any worker worked on this task.
|
|
"failed_by_workers":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/TaskWorker" }
|
|
required:
|
|
- id
|
|
- created
|
|
- updated
|
|
- job_id
|
|
- name
|
|
- status
|
|
- priority
|
|
- task_type
|
|
- activity
|
|
- commands
|
|
|
|
TaskWorker:
|
|
type: object
|
|
description: Worker reference, as used in Task objects.
|
|
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]
|
|
|
|
TaskLogInfo:
|
|
type: object
|
|
description: Info about the log of a single task.
|
|
properties:
|
|
"task_id": { type: string, format: uuid }
|
|
"job_id": { type: string, format: uuid }
|
|
"url":
|
|
description: The URL at which the task log itself can be downloaded.
|
|
type: string
|
|
"size":
|
|
description: The size of the task log, in bytes.
|
|
type: integer
|
|
required: [task_id, job_id, url, size]
|
|
|
|
JobLastRenderedImageInfo:
|
|
description: >
|
|
Enough information for a client to piece together different strings to
|
|
form a host-relative URL to the last-rendered image. To construct the
|
|
URL, concatenate "{base}/{one of the suffixes}".
|
|
type: object
|
|
properties:
|
|
"base": { type: string, format: url }
|
|
"suffixes":
|
|
type: array
|
|
items: { type: string }
|
|
required: [base, suffixes]
|
|
|
|
JobBlocklist:
|
|
description: "List of workers that are not allowed certain task types on a specific job."
|
|
type: array
|
|
items: { $ref: "#/components/schemas/JobBlocklistEntry" }
|
|
|
|
JobBlocklistEntry:
|
|
type: object
|
|
properties:
|
|
worker_id: { type: string, format: uuid }
|
|
task_type: { type: string }
|
|
worker_name: { type: string }
|
|
required: [worker_id, task_type]
|
|
|
|
JobStatusChange:
|
|
type: object
|
|
properties:
|
|
status: { $ref: "#/components/schemas/JobStatus" }
|
|
reason:
|
|
type: string
|
|
description: The reason for this status change.
|
|
required: [status, reason]
|
|
|
|
JobPriorityChange:
|
|
type: object
|
|
properties:
|
|
priority:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 100
|
|
required: [priority]
|
|
|
|
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.
|
|
|
|
# Deletion-related info:
|
|
"delete_requested_at":
|
|
type: string
|
|
format: date-time
|
|
description: >
|
|
If job deletion was requested, this is the timestamp at which
|
|
that request was stored on Flamenco Manager.
|
|
"was_deleted":
|
|
type: boolean
|
|
description: >
|
|
When a job was just deleted, this is set to `true`.
|
|
If this is specified, only the 'id' field is set, the rest will be empty.
|
|
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]
|
|
|
|
SocketIOLastRenderedUpdate:
|
|
type: object
|
|
description: Indicator that the last-rendered image of this job was updated.
|
|
properties:
|
|
"job_id": { type: string, format: uuid }
|
|
"thumbnail": { $ref: "#/components/schemas/JobLastRenderedImageInfo" }
|
|
required: [job_id, task_id, thumbnail]
|
|
|
|
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
|
|
"name": { type: string, description: "Name of the worker" }
|
|
"updated":
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last update
|
|
"last_seen":
|
|
type: string
|
|
format: date-time
|
|
description: Last time this worker was seen by the Manager.
|
|
"status": { $ref: "#/components/schemas/WorkerStatus" }
|
|
"previous_status": { $ref: "#/components/schemas/WorkerStatus" }
|
|
"status_change":
|
|
$ref: "#/components/schemas/WorkerStatusChangeRequest"
|
|
"version": { type: string }
|
|
"deleted_at":
|
|
type: string
|
|
format: date-time
|
|
description: This is only set when the worker was deleted.
|
|
"can_restart":
|
|
type: boolean
|
|
description: Whether this Worker can auto-restart.
|
|
required: [id, name, updated, status, version, can_restart]
|
|
|
|
SocketIOWorkerTagUpdate:
|
|
type: object
|
|
description: >
|
|
Worker Tag, sent over SocketIO when it changes.
|
|
properties:
|
|
"tag": { $ref: "#/components/schemas/WorkerTag" }
|
|
"was_deleted":
|
|
type: boolean
|
|
description: When a tag was just deleted, this is set to `true`.
|
|
required: [tag]
|
|
|
|
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, allLastRendered, allWorkerTags]
|
|
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 }
|
|
"name": { 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
|
|
"can_restart":
|
|
type: boolean
|
|
description: Whether this worker can auto-restart.
|
|
required: [id, name, status, version, can_restart]
|
|
|
|
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 }
|
|
"task": { $ref: "#/components/schemas/WorkerTask" }
|
|
"tags":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/WorkerTag" }
|
|
description: Tags of which this Worker is a member.
|
|
required:
|
|
- id
|
|
- name
|
|
- status
|
|
- ip_address
|
|
- platform
|
|
- version
|
|
- supported_task_types
|
|
|
|
WorkerTask:
|
|
description: Task assigned to a Worker.
|
|
allOf:
|
|
- $ref: "#/components/schemas/TaskSummary"
|
|
- properties:
|
|
"job_id": { type: string, format: uuid }
|
|
required: [job_id]
|
|
|
|
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]
|
|
|
|
WorkerSleepSchedule:
|
|
type: object
|
|
description: >
|
|
Sleep schedule for a single Worker. Start and end time indicate the time
|
|
of each day at which the schedule is active. Applies only when today is
|
|
in `days_of_week`, or when `days_of_week` is empty.
|
|
|
|
Start and end time are in 24-hour HH:MM notation.
|
|
properties:
|
|
"is_active": { type: boolean }
|
|
"days_of_week":
|
|
type: string
|
|
description: >
|
|
Space-separated two-letter strings indicating days of week the
|
|
schedule is active ("mo", "tu", etc.). Empty means "every day".
|
|
"start_time": { type: string, format: "HH:MM" }
|
|
"end_time": { type: string, format: "HH:MM" }
|
|
required: [is_active, days_of_week, start_time, end_time]
|
|
example:
|
|
is_active: true
|
|
days_of_week: "mo tu th fr"
|
|
start_time: "09:00"
|
|
end_time: "18:00"
|
|
|
|
WorkerTag:
|
|
type: object
|
|
description: >
|
|
Tag of workers. A job can optionally specify which tag it should
|
|
be limited to. Workers can be part of multiple tags simultaneously.
|
|
properties:
|
|
"id":
|
|
type: string
|
|
format: uuid
|
|
description: >
|
|
UUID of the tag. Can be ommitted when creating a new tag, in
|
|
which case a random UUID will be assigned.
|
|
"name":
|
|
type: string
|
|
"description":
|
|
type: string
|
|
required: [name]
|
|
example:
|
|
name: GPU-EEVEE
|
|
description: All workers that can do GPU rendering with EEVEE.
|
|
|
|
WorkerTagList:
|
|
type: object
|
|
properties:
|
|
"tags":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/WorkerTag" }
|
|
|
|
WorkerTagChangeRequest:
|
|
type: object
|
|
description: Request to change which tags this Worker is assigned to.
|
|
properties:
|
|
"tag_ids":
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
required: [tag_ids]
|
|
example:
|
|
"tag_ids": ["4312d68c-ea6d-4566-9bf6-e9f09be48ceb"]
|
|
|
|
securitySchemes:
|
|
worker_auth:
|
|
description: Username is the worker ID, password is the secret given at worker registration.
|
|
type: http
|
|
scheme: basic
|