09a476e11a
Compute render output path when evaluating job settings, which is done within the Flamenco add-on, instead of in the job compiler script. This allows the UI to show the render path, rather than it only being known after the job has been submitted.
532 lines
17 KiB
YAML
532 lines
17 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:
|
|
/api/version:
|
|
summary: Workers 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/worker/register-worker:
|
|
summary: Registration of new workers
|
|
post:
|
|
summary: Register a new worker
|
|
operationId: registerWorker
|
|
tags: [worker]
|
|
requestBody:
|
|
description: Worker to register
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerRegistration"
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RegisteredWorker"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/worker/sign-on:
|
|
summary: Called by Workers to let the Manager know they're ready to work, and to update their metadata.
|
|
post:
|
|
summary: Authenticate & sign in the worker.
|
|
operationId: signOn
|
|
security: [{worker_auth: []}]
|
|
tags: [worker]
|
|
requestBody:
|
|
description: Worker metadata
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerSignOn"
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/worker/sign-off:
|
|
summary: Called by Workers to let the Manager know they're going offline.
|
|
post:
|
|
summary: Mark the worker as offline
|
|
operationId: signOff
|
|
security: [{worker_auth: []}]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: normal response
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/worker/state:
|
|
summary: Called by Workers to check whether there is any state change requested.
|
|
get:
|
|
operationId: workerState
|
|
security: [{worker_auth: []}]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: no state change requested
|
|
"200":
|
|
description: state change requested
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/worker/state-changed:
|
|
summary: Called by Workers to let the Manager know they've changed status.
|
|
post:
|
|
summary: Worker changed state. This could be as acknowledgement of a Manager-requested state change, or in response to worker-local signals.
|
|
operationId: workerStateChanged
|
|
security: [{worker_auth: []}]
|
|
tags: [worker]
|
|
requestBody:
|
|
description: New worker state
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChanged"
|
|
responses:
|
|
"204":
|
|
description: normal response
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/worker/task:
|
|
summary: Task scheduler endpoint.
|
|
post:
|
|
operationId: scheduleTask
|
|
summary: Obtain a new task to execute
|
|
security: [{worker_auth: []}]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: No tasks available for this Worker.
|
|
"200":
|
|
description: Task to execute.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: "#/components/schemas/AssignedTask"}
|
|
"403":
|
|
description: Permission Denied
|
|
content:
|
|
application/json:
|
|
schema: {$ref: "#/components/schemas/SecurityError"}
|
|
"409":
|
|
description: Worker is not in the active state, so is not allowed to execute tasks right now.
|
|
"423":
|
|
description: Worker cannot obtain new tasks, but must go to another state.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
|
|
/api/worker/task/{task_id}:
|
|
summary: Workers send info about task progression here.
|
|
post:
|
|
operationId: taskUpdate
|
|
summary: Update the task, typically to indicate progress, completion, or failure.
|
|
security: [{worker_auth: []}]
|
|
tags: [worker]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: {type: string, format: uuid}
|
|
requestBody:
|
|
description: Task update information
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskUpdate"
|
|
responses:
|
|
"204":
|
|
description: The update was accepted.
|
|
"409":
|
|
description: The task is assigned to another worker, so the update was not accepted.
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/jobs/types:
|
|
summary: Available Flamenco job types.
|
|
get:
|
|
operationId: getJobTypes
|
|
summary: Get list of job types and their parameters.
|
|
tags: [jobs]
|
|
responses:
|
|
"200":
|
|
description: Available job types
|
|
content:
|
|
application/json:
|
|
schema: {$ref: "#/components/schemas/AvailableJobTypes"}
|
|
|
|
/api/jobs:
|
|
summary: Job submission endpoint.
|
|
post:
|
|
operationId: submitJob
|
|
summary: Submit a new job for Flamenco Manager to execute.
|
|
tags: [jobs]
|
|
requestBody:
|
|
description: Job to submit
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SubmittedJob"
|
|
responses:
|
|
"200":
|
|
description: Job was succesfully compiled into individual tasks.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: "#/components/schemas/Job"}
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: {$ref: "#/components/schemas/Error"}
|
|
|
|
/api/jobs/{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"}
|
|
|
|
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.
|
|
|
|
components:
|
|
schemas:
|
|
FlamencoVersion:
|
|
type: object
|
|
required: [version, name]
|
|
properties:
|
|
version: { type: string }
|
|
name: { type: string }
|
|
|
|
WorkerRegistration:
|
|
type: object
|
|
required: [secret, platform, supported_task_types, nickname]
|
|
properties:
|
|
secret: {type: string}
|
|
platform: {type: string}
|
|
supported_task_types:
|
|
type: array
|
|
items: {type: string}
|
|
nickname: {type: string}
|
|
|
|
RegisteredWorker:
|
|
type: object
|
|
properties:
|
|
uuid: {type: string, format: uuid}
|
|
nickname: {type: string}
|
|
address: {type: string}
|
|
status: {$ref: "#/components/schemas/WorkerStatus"}
|
|
platform: {type: string}
|
|
last_activity: {type: string}
|
|
software: {type: string}
|
|
supported_task_types:
|
|
type: array
|
|
items: {type: string}
|
|
required: [uuid, nickname, address, status, platform, current_task, last_activity, software, supported_task_types]
|
|
|
|
WorkerStatus:
|
|
type: string
|
|
enum: [starting, awake, asleep, error, shutdown, testing, offline]
|
|
|
|
WorkerSignOn:
|
|
type: object
|
|
properties:
|
|
nickname: {type: string}
|
|
supported_task_types:
|
|
type: array
|
|
items: {type: string}
|
|
software_version: {type: string}
|
|
required: [nickname, supported_task_types, software_version]
|
|
|
|
WorkerStateChange:
|
|
type: object
|
|
properties:
|
|
status_requested: {$ref: "#/components/schemas/WorkerStatus"}
|
|
required: [status_requested]
|
|
|
|
WorkerStateChanged:
|
|
type: object
|
|
properties:
|
|
status: {$ref: "#/components/schemas/WorkerStatus"}
|
|
required: [status]
|
|
|
|
AssignedTask:
|
|
type: object
|
|
description: AssignedTask is a task as it is received by the Worker.
|
|
properties:
|
|
uuid: {type: string, format: uuid}
|
|
job: {type: string}
|
|
name: {type: string}
|
|
status: {$ref: "#/components/schemas/TaskStatus"}
|
|
priority: {type: integer}
|
|
job_priority: {type: integer}
|
|
job_type: {type: string}
|
|
task_type: {type: string}
|
|
commands:
|
|
type: array
|
|
items: {$ref: "#/components/schemas/Command"}
|
|
required: [uuid, job, name, status, priority, job_priority, job_type, task_type, commands]
|
|
|
|
TaskUpdate:
|
|
type: object
|
|
description: TaskUpdate is sent by a Worker to update the status & logs of a task it's executing.
|
|
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."}
|
|
|
|
JobStatus:
|
|
type: string
|
|
enum: [active, canceled, completed, construction-failed, failed, paused, queued, archived, archiving, cancel-requested, fail-requested, requeued, under-construction, waiting-for-files]
|
|
|
|
TaskStatus:
|
|
type: string
|
|
enum: [active, canceled, completed, failed, queued, soft-failed, cancel-requested, paused]
|
|
|
|
Command:
|
|
type: object
|
|
description: Command represents a single command to execute by the Worker.
|
|
properties:
|
|
name: {type: string}
|
|
parameters: {type: object}
|
|
required: [name, parameters]
|
|
|
|
AvailableJobTypes:
|
|
type: object
|
|
description: List of job types supported by this Manager.
|
|
properties:
|
|
"job_types":
|
|
type: array
|
|
items: {$ref: "#/components/schemas/AvailableJobType"}
|
|
required: [job_types]
|
|
|
|
AvailableJobType:
|
|
type: object
|
|
description: Job type supported by this Manager, and its parameters.
|
|
properties:
|
|
"name": {type: string}
|
|
"label": {type: string}
|
|
"settings":
|
|
type: array
|
|
items: {$ref: "#/components/schemas/AvailableJobSetting"}
|
|
required: [name, label, settings]
|
|
|
|
AvailableJobSetting:
|
|
type: object
|
|
description: Single setting of a Job types.
|
|
properties:
|
|
"key":
|
|
type: string
|
|
description: Identifier for the setting, must be unique within the job type.
|
|
"type": {$ref: "#/components/schemas/AvailableJobSettingType"}
|
|
"subtype": {$ref: "#/components/schemas/AvailableJobSettingSubtype"}
|
|
"choices":
|
|
description: When given, limit the valid values to these choices. Only usable with string type.
|
|
type: array
|
|
items: {type: string}
|
|
"propargs":
|
|
description: Any extra arguments to the bpy.props.SomeProperty() call used to create this property.
|
|
type: object
|
|
"description":
|
|
description: The description/tooltip shown in the user interface.
|
|
"default":
|
|
description: The default value shown to the user when determining this setting.
|
|
"eval":
|
|
type: string
|
|
description: Python expression to be evaluated in order to determine the default value for this setting.
|
|
"visible":
|
|
type: boolean
|
|
description: >
|
|
Whether to show this setting in the UI of a job submitter (like a
|
|
Blender add-on). Set to `false` when it is an internal setting that
|
|
shouldn't be shown to end users.
|
|
default: true
|
|
"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"]
|
|
|
|
SubmittedJob:
|
|
type: object
|
|
description: Job definition submitted to Flamenco.
|
|
properties:
|
|
"name": {type: string}
|
|
"type": {type: string}
|
|
"priority": {type: integer, default: 50}
|
|
"settings": {$ref: "#/components/schemas/JobSettings"}
|
|
"metadata": {$ref: "#/components/schemas/JobMetadata"}
|
|
required: [name, type, priority]
|
|
example:
|
|
type: "simple-blender-render"
|
|
name: 3Д рендеринг
|
|
priority: 50
|
|
settings:
|
|
blender_cmd: "{blender}"
|
|
filepath: "/render/sf/jobs/scene123.blend"
|
|
render_output: "/render/sf/frames/scene123"
|
|
frames: "1-10"
|
|
chunk_size: 3
|
|
fps: 24
|
|
extract_audio: true
|
|
images_or_video: "images"
|
|
format: "PNG"
|
|
output_file_extension: ".png"
|
|
metadata:
|
|
"user.name": "Sybren Stüvel"
|
|
"user.email": "sybren@blender.org"
|
|
"project": "Sprite Fright"
|
|
Job:
|
|
allOf:
|
|
- $ref: '#/components/schemas/SubmittedJob'
|
|
- properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Job
|
|
created:
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp
|
|
updated:
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp
|
|
status: {$ref: "#/components/schemas/JobStatus"}
|
|
required: [id, created, updated, status]
|
|
|
|
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"
|
|
|
|
Error:
|
|
type: object
|
|
required: [code, message]
|
|
properties:
|
|
code: {type: integer, format: int32}
|
|
message: {type: string}
|
|
|
|
SecurityError:
|
|
type: object
|
|
required: [message]
|
|
properties:
|
|
message: {type: string}
|
|
|
|
securitySchemes:
|
|
worker_auth:
|
|
description: Username is the worker ID, password is the secret given at worker registration.
|
|
type: http
|
|
scheme: basic
|