634d59e622
This commit includes settings for Visual Studio Code, so that at least different people with the same editor (or me on multiple machines) get the same formatting. No functional changes.
1020 lines
33 KiB
YAML
1020 lines
33 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
version: 1.0.0
|
|
title: Flamenco manager
|
|
description: Render Farm manager API
|
|
contact:
|
|
name: Flamenco Team
|
|
url: https://flamenco.io/
|
|
license:
|
|
name: GPLv3
|
|
url: https://www.gnu.org/licenses/gpl-3.0.en.html
|
|
servers:
|
|
- url: /
|
|
paths:
|
|
## Meta
|
|
|
|
/api/version:
|
|
summary: Clients can use this to check this is actually a Flamenco server.
|
|
get:
|
|
summary: Get the Flamenco version of this Manager
|
|
operationId: getVersion
|
|
tags: [meta]
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FlamencoVersion"
|
|
|
|
/api/configuration:
|
|
summary: Endpoint for getting configuration of Flamenco Manager.
|
|
get:
|
|
summary: Get the configuration of this Manager.
|
|
operationId: getConfiguration
|
|
tags: [meta]
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/ManagerConfiguration" }
|
|
|
|
## Worker
|
|
|
|
/api/worker/register-worker:
|
|
summary: Registration of new workers
|
|
post:
|
|
summary: Register a new worker
|
|
operationId: registerWorker
|
|
tags: [worker]
|
|
requestBody:
|
|
description: Worker to register
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerRegistration"
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RegisteredWorker"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/sign-on:
|
|
summary: Called by Workers to let the Manager know they're ready to work, and to update their metadata.
|
|
post:
|
|
summary: Authenticate & sign in the worker.
|
|
operationId: signOn
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
requestBody:
|
|
description: Worker metadata
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerSignOn"
|
|
responses:
|
|
"200":
|
|
description: normal response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/sign-off:
|
|
summary: Called by Workers to let the Manager know they're going offline.
|
|
post:
|
|
summary: Mark the worker as offline
|
|
operationId: signOff
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: normal response
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/state:
|
|
summary: Called by Workers to check whether there is any state change requested.
|
|
get:
|
|
operationId: workerState
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: no state change requested
|
|
"200":
|
|
description: state change requested
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/state-changed:
|
|
summary: Called by Workers to let the Manager know they've changed status.
|
|
post:
|
|
summary: Worker changed state. This could be as acknowledgement of a Manager-requested state change, or in response to worker-local signals.
|
|
operationId: workerStateChanged
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
requestBody:
|
|
description: New worker state
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChanged"
|
|
responses:
|
|
"204":
|
|
description: normal response
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/api/worker/task:
|
|
summary: Task scheduler endpoint.
|
|
post:
|
|
operationId: scheduleTask
|
|
summary: Obtain a new task to execute
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
responses:
|
|
"204":
|
|
description: No tasks available for this Worker.
|
|
"200":
|
|
description: Task to execute.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/AssignedTask" }
|
|
"403":
|
|
description: Permission Denied
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/SecurityError" }
|
|
"409":
|
|
description: Worker is not in the active state, so is not allowed to execute tasks right now.
|
|
"423":
|
|
description: Worker cannot obtain new tasks, but must go to another state.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkerStateChange"
|
|
|
|
/api/worker/task/{task_id}:
|
|
summary: Workers send info about task progression here.
|
|
post:
|
|
operationId: taskUpdate
|
|
summary: Update the task, typically to indicate progress, completion, or failure.
|
|
security: [{ worker_auth: [] }]
|
|
tags: [worker]
|
|
parameters:
|
|
- name: task_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: Task update information
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskUpdate"
|
|
responses:
|
|
"204":
|
|
description: The update was accepted.
|
|
"409":
|
|
description: The task is assigned to another worker, so the update was not accepted.
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
## Jobs
|
|
|
|
/api/jobs/types:
|
|
summary: Available Flamenco job types.
|
|
get:
|
|
operationId: getJobTypes
|
|
summary: Get list of job types and their parameters.
|
|
tags: [jobs]
|
|
responses:
|
|
"200":
|
|
description: Available job types
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/AvailableJobTypes" }
|
|
|
|
/api/jobs/type/{typeName}:
|
|
summary: Info about a specific job type.
|
|
get:
|
|
operationId: getJobType
|
|
summary: Get single job type and its parameters.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: typeName
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Job type
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/AvailableJobType" }
|
|
|
|
/api/jobs:
|
|
summary: Job submission endpoint.
|
|
post:
|
|
operationId: submitJob
|
|
summary: Submit a new job for Flamenco Manager to execute.
|
|
tags: [jobs]
|
|
requestBody:
|
|
description: Job to submit
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SubmittedJob"
|
|
responses:
|
|
"200":
|
|
description: Job was succesfully compiled into individual tasks.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Job" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/jobs/query:
|
|
summary: Obtain jobs with filtering and sorting.
|
|
post:
|
|
operationId: queryJobs
|
|
summary: Fetch list of jobs.
|
|
tags: [jobs]
|
|
requestBody:
|
|
description: Specification of which jobs to get.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JobsQuery"
|
|
responses:
|
|
"200":
|
|
description: Normal query response, can be empty list if nothing matched the query.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/JobsQueryResult" }
|
|
default:
|
|
description: Error message
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Error" }
|
|
|
|
/api/jobs/{job_id}:
|
|
summary: Job info and management
|
|
get:
|
|
operationId: fetchJob
|
|
summary: Fetch info about the job.
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Job info
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/Job" }
|
|
|
|
/api/jobs/{job_id}/setstatus:
|
|
summary: Request a status change for the given job.
|
|
post:
|
|
operationId: setJobStatus
|
|
tags: [jobs]
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
description: The status change to request.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JobStatusChange"
|
|
responses:
|
|
"204":
|
|
description: Status change was accepted.
|
|
"422":
|
|
description: The requested status change is not valid for the current status of the job.
|
|
default:
|
|
description: Unexpected error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
|
|
## Shaman
|
|
|
|
/shaman/checkout/requirements:
|
|
summary: Allows a client to check which files are available on the server, and which ones are still unknown.
|
|
post:
|
|
operationId: shamanCheckoutRequirements
|
|
summary: Checks a Shaman Requirements file, and reports which files are unknown.
|
|
tags: [shaman]
|
|
requestBody:
|
|
description: Set of files to check
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ShamanRequirementsRequest"
|
|
responses:
|
|
"200":
|
|
description: Subset of the posted requirements, indicating the unknown files.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/ShamanRequirementsResponse" }
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/shaman/checkout/create:
|
|
summary: Symlink a set of files into the checkout area.
|
|
post:
|
|
operationId: shamanCheckout
|
|
summary: Create a directory, and symlink the required files into it. The files must all have been uploaded to Shaman before calling this endpoint.
|
|
tags: [shaman]
|
|
requestBody:
|
|
description: Set of files to check out.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ShamanCheckout"
|
|
responses:
|
|
"200":
|
|
description: Checkout was created succesfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ShamanCheckoutResult"
|
|
"424":
|
|
description: There were files missing. Use `shamanCheckoutRequirements` to figure out which ones.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"409":
|
|
description: Checkout already exists.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/shaman/files/{checksum}/{filesize}:
|
|
summary: Upload files to the Shaman server.
|
|
get:
|
|
operationId: shamanFileStoreCheck
|
|
summary: >
|
|
Check the status of a file on the Shaman server.
|
|
tags: [shaman]
|
|
parameters:
|
|
- name: checksum
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
description: SHA256 checksum of the file.
|
|
- name: filesize
|
|
in: path
|
|
required: true
|
|
schema: { type: integer }
|
|
description: Size of the file in bytes.
|
|
responses:
|
|
"200":
|
|
description: Normal response.
|
|
content:
|
|
application/json:
|
|
schema: { $ref: "#/components/schemas/ShamanSingleFileStatus" }
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
post:
|
|
operationId: shamanFileStore
|
|
summary: >
|
|
Store a new file on the Shaman server. Note that the Shaman server can
|
|
forcibly close the HTTP connection when another client finishes uploading
|
|
the exact same file, to prevent double uploads.
|
|
|
|
The file's contents should be sent in the request body.
|
|
tags: [shaman]
|
|
parameters:
|
|
- name: checksum
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
description: SHA256 checksum of the file.
|
|
- name: filesize
|
|
in: path
|
|
required: true
|
|
schema: { type: integer }
|
|
description: Size of the file in bytes.
|
|
- name: X-Shaman-Can-Defer-Upload
|
|
in: header
|
|
required: false
|
|
schema: { type: boolean }
|
|
description: >
|
|
The client indicates that it can defer uploading this file. The
|
|
"208" response will not only be returned when the file is already
|
|
fully known to the Shaman server, but also when someone else is
|
|
currently uploading this file.
|
|
- name: X-Shaman-Original-Filename
|
|
in: header
|
|
required: false
|
|
schema: { type: string }
|
|
description: >
|
|
The original filename. If sent along with the request, it will be
|
|
included in the server logs, which can aid in debugging.
|
|
requestBody:
|
|
description: Contents of the file
|
|
required: true
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
|
|
responses:
|
|
"204":
|
|
description: The file was accepted.
|
|
"208":
|
|
description: The file was already known to the server.
|
|
"417":
|
|
description: >
|
|
There was a mismatch between the request parameters and the actual
|
|
file size or checksum of the uploaded file.
|
|
"425":
|
|
description: >
|
|
Client should defer uploading this file. The file is currently in
|
|
the process of being uploaded by someone else, and
|
|
`X-Shaman-Can-Defer-Upload: true` was sent in the request.
|
|
default:
|
|
description: unexpected error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
tags:
|
|
- name: meta
|
|
description: Info about the Flamenco Manager itself.
|
|
- name: jobs
|
|
description: Job & task queries, submission, and management.
|
|
- name: worker
|
|
description: API for Flamenco Workers to communicate with Flamenco Manager.
|
|
- name: shaman
|
|
description: Shaman API, for file uploading & creating job checkouts.
|
|
|
|
components:
|
|
schemas:
|
|
FlamencoVersion:
|
|
type: object
|
|
required: [version, name]
|
|
properties:
|
|
version: { type: string }
|
|
name: { type: string }
|
|
|
|
ManagerConfiguration:
|
|
type: object
|
|
properties:
|
|
"storageLocation":
|
|
description: Directory used for job file storage.
|
|
type: string
|
|
"shamanEnabled":
|
|
description: Whether the Shaman file transfer API is available.
|
|
type: boolean
|
|
required: [storageLocation, shamanEnabled]
|
|
|
|
WorkerRegistration:
|
|
type: object
|
|
required: [secret, platform, supported_task_types, nickname]
|
|
properties:
|
|
secret: { type: string }
|
|
platform: { type: string }
|
|
supported_task_types:
|
|
type: array
|
|
items: { type: string }
|
|
nickname: { type: string }
|
|
|
|
RegisteredWorker:
|
|
type: object
|
|
properties:
|
|
uuid: { type: string, format: uuid }
|
|
nickname: { type: string }
|
|
address: { type: string }
|
|
status: { $ref: "#/components/schemas/WorkerStatus" }
|
|
platform: { type: string }
|
|
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_root: "/render/sf/frames/scene123"
|
|
render_output_path: "/render/sf/frames/scene123/3Д рендеринг/######"
|
|
frames: "1-10"
|
|
chunk_size: 3
|
|
fps: 24
|
|
extract_audio: true
|
|
images_or_video: "images"
|
|
format: "PNG"
|
|
output_file_extension: ".png"
|
|
metadata:
|
|
"user.name": "Sybren Stüvel"
|
|
"user.email": "sybren@blender.org"
|
|
"project": "Sprite Fright"
|
|
Job:
|
|
allOf:
|
|
- $ref: "#/components/schemas/SubmittedJob"
|
|
- properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Job
|
|
created:
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp
|
|
updated:
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp
|
|
status: { $ref: "#/components/schemas/JobStatus" }
|
|
activity: { type: string, description: "Description of the last activity on this job." }
|
|
required: [id, created, updated, status, activity]
|
|
|
|
JobSettings:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
JobMetadata:
|
|
type: object
|
|
description: Arbitrary metadata strings. More complex structures can be modeled by using `a.b.c` notation for the key.
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
"user.name": Sybren Stüvel
|
|
"user.email": sybren@blender.org
|
|
"project": "Sprite Fright"
|
|
|
|
JobsQuery:
|
|
type: object
|
|
properties:
|
|
"offset":
|
|
type: integer
|
|
minimum: 0
|
|
"limit":
|
|
type: integer
|
|
minimum: 1
|
|
"order_by":
|
|
type: array
|
|
items: { type: string }
|
|
"status_in":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/JobStatus" }
|
|
description: Return only jobs with a status in this array.
|
|
"metadata":
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Filter by metadata, using `LIKE` notation.
|
|
"settings":
|
|
type: object
|
|
additionalProperties: true
|
|
description: Filter by job settings, using `LIKE` notation.
|
|
example:
|
|
"limit": 5
|
|
"order_by": ["updated", "status"]
|
|
"status_in": ["active", "queued", "failed"]
|
|
"metadata": { project: "Sprite Fright" }
|
|
|
|
JobsQueryResult:
|
|
type: object
|
|
properties:
|
|
jobs:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/Job" }
|
|
required: [jobs]
|
|
|
|
JobStatusChange:
|
|
type: object
|
|
properties:
|
|
status: { $ref: "#/components/schemas/JobStatus" }
|
|
reason: { type: string, description: The reason for this status change. }
|
|
required: [status, reason]
|
|
|
|
Error:
|
|
description: Generic error response.
|
|
type: object
|
|
required: [code, message]
|
|
properties:
|
|
code:
|
|
type: integer
|
|
format: int32
|
|
description: >
|
|
HTTP status code of this response. Is included in the payload so
|
|
that a single object represents all error information.
|
|
|
|
Code 503 is used when the database is busy. The HTTP response will
|
|
contain a 'Retry-After' HTTP header that indicates after which time
|
|
the request can be retried. Following the header is not mandatory,
|
|
and it's up to the client to do something reasonable like
|
|
exponential backoff.
|
|
message: { type: string }
|
|
|
|
SecurityError:
|
|
type: object
|
|
required: [message]
|
|
properties:
|
|
message: { type: string }
|
|
|
|
ShamanRequirementsRequest:
|
|
type: object
|
|
description: Set of files with their SHA256 checksum and size in bytes.
|
|
properties:
|
|
"files":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/ShamanFileSpec" }
|
|
required: [files]
|
|
example:
|
|
files:
|
|
- sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0
|
|
size: 1424
|
|
- sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079
|
|
size: 127
|
|
|
|
ShamanRequirementsResponse:
|
|
type: object
|
|
description: The files from a requirements request, with their status on the Shaman server. Files that are known to Shaman are excluded from the response.
|
|
properties:
|
|
"files":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/ShamanFileSpecWithStatus" }
|
|
required: [files]
|
|
example:
|
|
files:
|
|
- sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0
|
|
size: 1424
|
|
status: unknown
|
|
- sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079
|
|
size: 127
|
|
status: uploading
|
|
|
|
ShamanFileSpec:
|
|
type: object
|
|
description: Specification of a file in the Shaman storage.
|
|
properties:
|
|
"sha": { type: string, description: "SHA256 checksum of the file" }
|
|
"size": { type: integer, description: "File size in bytes" }
|
|
"path": { type: string, description: "Location of the file in the checkout" }
|
|
required: [sha, size, path]
|
|
|
|
ShamanFileSpecWithStatus:
|
|
# Using allOf here would trigger a bug in the Python code generator,
|
|
# resulting in this error:
|
|
#
|
|
# Values stored for property status in ShamanFileSpecWithStatus differ
|
|
# when looking at self and self's composed instances. All values must be
|
|
# the same at ['['received_data', 'files', 0]']['status']
|
|
#
|
|
# The underlying cause is that composited types can apparently store
|
|
# property values multiple times, and these have to be equal. However, one
|
|
# is using the `ShamanFileStatus` type, and the other is using the `str`
|
|
# type to store the same status value.
|
|
#
|
|
# To work around this, even though this should be a composition of
|
|
# `ShamanFileSpec` with some extra properties, we just repeat those same
|
|
# properties here.
|
|
type: object
|
|
description: Specification of a file, which could be in the Shaman storage, or not, depending on its status.
|
|
properties:
|
|
"sha": { type: string, description: "SHA256 checksum of the file" }
|
|
"size": { type: integer, description: "File size in bytes" }
|
|
"path": { type: string, description: "Location of the file in the checkout" }
|
|
"status": { $ref: "#/components/schemas/ShamanFileStatus" }
|
|
required: [sha, size, path, status]
|
|
|
|
ShamanCheckout:
|
|
type: object
|
|
description: Set of files with their SHA256 checksum, size in bytes, and desired location in the checkout directory.
|
|
properties:
|
|
"files":
|
|
type: array
|
|
items: { $ref: "#/components/schemas/ShamanFileSpec" }
|
|
"checkoutPath":
|
|
type: string
|
|
description: >
|
|
Path where the Manager should create this checkout. It is relative
|
|
to the Shaman checkout path as configured on the Manager. In older
|
|
versions of the Shaman this was just the "checkout ID", but in this
|
|
version it can be a path like `project-slug/scene-name/unique-ID`.
|
|
required: [files, checkoutPath]
|
|
example:
|
|
files:
|
|
- sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0
|
|
size: 1424
|
|
path: definition.go
|
|
- sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079
|
|
size: 127
|
|
path: logging.go
|
|
|
|
ShamanCheckoutResult:
|
|
type: object
|
|
description: The result of a Shaman checkout.
|
|
properties:
|
|
"checkoutPath":
|
|
type: string
|
|
description: >
|
|
Path where the Manager created this checkout. This can be different
|
|
than what was requested, as the Manager will ensure a unique
|
|
directory. The path is relative to the Shaman checkout path as
|
|
configured on the Manager.
|
|
required: [checkoutPath]
|
|
|
|
ShamanFileStatus:
|
|
type: string
|
|
enum: [unknown, uploading, stored]
|
|
|
|
ShamanSingleFileStatus:
|
|
type: object
|
|
description: Status of a file in the Shaman storage.
|
|
properties:
|
|
"status": { $ref: "#/components/schemas/ShamanFileStatus" }
|
|
required: [status]
|
|
|
|
# SocketIO API. These types are not used in any HTTP operation defined in
|
|
# the 'paths' section of this document, so some code generators may choose
|
|
# to skip these.
|
|
|
|
JobUpdate:
|
|
type: object
|
|
description: >
|
|
Subset of a Job, sent over SocketIO when a job changes.
|
|
For new jobs, `previous_status` will be excluded.
|
|
properties:
|
|
"id":
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the Job
|
|
"name": { type: string, description: "Name of the job" }
|
|
"updated":
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last update
|
|
"status": { $ref: "#/components/schemas/JobStatus" }
|
|
"previous_status": { $ref: "#/components/schemas/JobStatus" }
|
|
"type": { type: string }
|
|
"priority": { type: integer, default: 50 }
|
|
required: [id, updated, status, type, priority]
|
|
|
|
securitySchemes:
|
|
worker_auth:
|
|
description: Username is the worker ID, password is the secret given at worker registration.
|
|
type: http
|
|
scheme: basic
|