2616 lines
85 KiB
YAML
2616 lines
85 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.blender.org/
|
|
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" }
|
|
|
|
/api/v3/status:
|
|
summary: Report the status of the Flamenco farm.
|
|
get:
|
|
summary: Get the status of this Flamenco farm.
|
|
operationId: getFarmStatus
|
|
tags: [meta]
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FarmStatusReport"
|
|
|
|
## 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
|
|
|
|
FarmStatusReport:
|
|
type: object
|
|
properties:
|
|
"status":
|
|
$ref: "#/components/schemas/FarmStatus"
|
|
required: [status]
|
|
example:
|
|
status: idle
|
|
|
|
FarmStatus:
|
|
type: string
|
|
enum:
|
|
- "active" # Actively working on jobs.
|
|
- "idle" # Farm could be active, but has no work to do.
|
|
- "waiting" # Work has been queued, but all workers are asleep.
|
|
- "asleep" # Farm is idle, and all workers are asleep.
|
|
- "inoperative" # Cannot work: no workers, or all are offline/error.
|
|
- "unknown" # Unexpected configuration of worker and job statuses.
|
|
- "starting" # Farm is starting up.
|
|
|
|
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 }
|
|
"description":
|
|
type: string
|
|
description: The description/tooltip shown in the user interface.
|
|
"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.
|
|
"label":
|
|
description: Label for displaying this setting. If not specified, the key is used to generate a reasonable label.
|
|
"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]
|
|
|
|
# Events 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.
|
|
|
|
EventJobUpdate:
|
|
type: object
|
|
description: >
|
|
Subset of a Job, sent over SocketIO/MQTT 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]
|
|
|
|
EventTaskUpdate:
|
|
type: object
|
|
description: >
|
|
Subset of a Task, sent over SocketIO/MQTT 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]
|
|
|
|
EventTaskLogUpdate:
|
|
type: object
|
|
description: >
|
|
Task log chunk, sent to a MQTT topic/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]
|
|
|
|
EventLastRenderedUpdate:
|
|
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]
|
|
|
|
EventWorkerUpdate:
|
|
type: object
|
|
description: >
|
|
Subset of a Worker, sent over SocketIO/MQTT 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]
|
|
|
|
EventWorkerTagUpdate:
|
|
type: object
|
|
description: >
|
|
Worker Tag, sent over SocketIO/MQTT 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]
|
|
|
|
EventLifeCycle:
|
|
type: object
|
|
description: >
|
|
Flamenco life-cycle event, for things like shutting down, starting up, etc.
|
|
properties:
|
|
"type": { $ref: "#/components/schemas/LifeCycleEventType" }
|
|
required: [type]
|
|
|
|
LifeCycleEventType:
|
|
type: string
|
|
enum: [manager-startup, manager-shutdown]
|
|
|
|
EventFarmStatus:
|
|
$ref: "#/components/schemas/FarmStatusReport"
|
|
|
|
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.
|
|
|
|
This is not used by MQTT, as with that protocol the subscriptions are
|
|
managed by the MQTT broker, not Flamenco.
|
|
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
|