309 lines
9.4 KiB
YAML
309 lines
9.4 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/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/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"}
|
|
|
|
/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]
|
|
# TODO: Security!
|
|
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/SubmittedJob"}
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: {$ref: "#/components/schemas/Error"}
|
|
|
|
tags:
|
|
- name: jobs
|
|
description: Blablabla for users to get job metadata balbla
|
|
- name: worker
|
|
description: API for Flamenco Workers to communicate with Flamenco Manager.
|
|
|
|
components:
|
|
schemas:
|
|
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:
|
|
id: {type: string}
|
|
nickname: {type: string}
|
|
address: {type: string}
|
|
status: {type: string}
|
|
platform: {type: string}
|
|
last_activity: {type: string}
|
|
software: {type: string}
|
|
supported_task_types:
|
|
type: array
|
|
items: {type: string}
|
|
required: [id, nickname, address, status, platform, current_task, last_activity, software, supported_task_types]
|
|
|
|
AssignedTask:
|
|
type: object
|
|
description: AssignedTask is a task as it is received by the Worker.
|
|
properties:
|
|
id: {type: string}
|
|
job: {type: string}
|
|
user: {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: [id, job, user, name, status, priority, job_priority, job_type, task_type, commands]
|
|
|
|
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, fail-requested, paused, processing]
|
|
|
|
Command:
|
|
type: object
|
|
description: Command represents a single command to execute by the Worker.
|
|
properties:
|
|
name: {type: string}
|
|
settings: {type: object}
|
|
required: [name, settings]
|
|
|
|
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}
|
|
"default":
|
|
description: The default value shown to the user when determining 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:
|
|
"id": {type: string}
|
|
"name": {type: string}
|
|
"type": {type: string}
|
|
"status": {$ref: "#/components/schemas/JobStatus"}
|
|
"priority": {type: integer, default: 50}
|
|
"settings":
|
|
type: object
|
|
"metadata":
|
|
type: object
|
|
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"
|
|
|
|
|
|
Error:
|
|
type: object
|
|
required: [code, message]
|
|
properties:
|
|
code: {type: integer, format: int32}
|
|
message: {type: string}
|
|
|
|
SecurityError:
|
|
type: object
|
|
required: [message]
|
|
properties:
|
|
message: {type: string}
|
|
|
|
Configuration:
|
|
type: object
|
|
description: Flamenco Manager configuration
|
|
properties:
|
|
"_meta":
|
|
type: object
|
|
properties:
|
|
"schema_version": {type: integer}
|
|
required: [schema_version]
|
|
"settings":
|
|
description: Key-value pairs for settings.
|
|
type: object
|
|
additionalProperties: true
|
|
required: [_meta, settings]
|
|
|
|
securitySchemes:
|
|
worker_auth:
|
|
description: Username is the worker ID, password is the secret given at worker registration.
|
|
type: http
|
|
scheme: basic
|