Documentation
¶
Overview ¶
Package api_impl implements the OpenAPI API from pkg/api/flamenco-openapi.yaml.
SPDX-License-Identifier: GPL-3.0-or-later
Package api_impl implements the OpenAPI API from pkg/api/flamenco-openapi.yaml.
Package api_impl implements the OpenAPI API from pkg/api/flamenco-openapi.yaml.
Index ¶
- Constants
- Variables
- func SwaggerValidator(swagger *openapi3.T, persist PersistenceService) echo.MiddlewareFunc
- func WorkerAuth(ctx context.Context, authInfo *openapi3filter.AuthenticationInput, ...) error
- type BCryptHasher
- type ChangeBroadcaster
- type ConfigService
- type FarmStatusService
- type Flamenco
- func (f *Flamenco) CheckBlenderExePath(e echo.Context) error
- func (f *Flamenco) CheckSharedStoragePath(e echo.Context) error
- func (f *Flamenco) CreateWorkerTag(e echo.Context) error
- func (f *Flamenco) DeleteJob(e echo.Context, jobID string) error
- func (f *Flamenco) DeleteJobMass(e echo.Context) error
- func (f *Flamenco) DeleteJobWhatWouldItDo(e echo.Context, jobID string) error
- func (f *Flamenco) DeleteWorker(e echo.Context, workerUUID string) error
- func (f *Flamenco) DeleteWorkerTag(e echo.Context, tagUUID string) error
- func (f *Flamenco) FetchGlobalLastRenderedInfo(e echo.Context) error
- func (f *Flamenco) FetchJob(e echo.Context, jobID string) error
- func (f *Flamenco) FetchJobBlocklist(e echo.Context, jobID string) error
- func (f *Flamenco) FetchJobLastRenderedInfo(e echo.Context, jobID string) error
- func (f *Flamenco) FetchJobTasks(e echo.Context, jobID string) error
- func (f *Flamenco) FetchJobs(e echo.Context) error
- func (f *Flamenco) FetchTask(e echo.Context, taskID string) error
- func (f *Flamenco) FetchTaskLogInfo(e echo.Context, taskID string) error
- func (f *Flamenco) FetchTaskLogTail(e echo.Context, taskID string) error
- func (f *Flamenco) FetchWorker(e echo.Context, workerUUID string) error
- func (f *Flamenco) FetchWorkerSleepSchedule(e echo.Context, workerUUID string) error
- func (f *Flamenco) FetchWorkerTag(e echo.Context, tagUUID string) error
- func (f *Flamenco) FetchWorkerTags(e echo.Context) error
- func (f *Flamenco) FetchWorkers(e echo.Context) error
- func (f *Flamenco) FindBlenderExePath(e echo.Context) error
- func (f *Flamenco) GetConfiguration(e echo.Context) error
- func (f *Flamenco) GetConfigurationFile(e echo.Context) error
- func (f *Flamenco) GetFarmStatus(e echo.Context) error
- func (f *Flamenco) GetJobType(e echo.Context, typeName string) error
- func (f *Flamenco) GetJobTypes(e echo.Context) error
- func (f *Flamenco) GetSharedStorage(e echo.Context, audience api.ManagerVariableAudience, platform string) error
- func (f *Flamenco) GetVariables(e echo.Context, audience api.ManagerVariableAudience, platform string) error
- func (f *Flamenco) GetVersion(e echo.Context) error
- func (f *Flamenco) MayWorkerRun(e echo.Context, taskID string) error
- func (f *Flamenco) RegisterWorker(e echo.Context) error
- func (f *Flamenco) RemoveJobBlocklist(e echo.Context, jobID string) error
- func (f *Flamenco) RequestWorkerStatusChange(e echo.Context, workerUUID string) error
- func (f *Flamenco) SaveSetupAssistantConfig(e echo.Context) error
- func (f *Flamenco) ScheduleTask(e echo.Context) error
- func (f *Flamenco) SetJobPriority(e echo.Context, jobID string) error
- func (f *Flamenco) SetJobStatus(e echo.Context, jobID string) error
- func (f *Flamenco) SetTaskStatus(e echo.Context, taskID string) error
- func (f *Flamenco) SetWorkerSleepSchedule(e echo.Context, workerUUID string) error
- func (f *Flamenco) SetWorkerTags(e echo.Context, workerUUID string) error
- func (f *Flamenco) ShamanCheckout(e echo.Context) error
- func (f *Flamenco) ShamanCheckoutRequirements(e echo.Context) error
- func (f *Flamenco) ShamanFileStore(e echo.Context, checksum string, filesize int, ...) error
- func (f *Flamenco) ShamanFileStoreCheck(e echo.Context, checksum string, filesize int) error
- func (f *Flamenco) SignOff(e echo.Context) error
- func (f *Flamenco) SignOn(e echo.Context) error
- func (f *Flamenco) SubmitJob(e echo.Context) error
- func (f *Flamenco) SubmitJobCheck(e echo.Context) error
- func (f *Flamenco) TaskOutputProduced(e echo.Context, taskID string) error
- func (f *Flamenco) TaskUpdate(e echo.Context, taskID string) error
- func (f *Flamenco) UpdateWorkerTag(e echo.Context, tagUUID string) error
- func (f *Flamenco) WaitForShutdown(ctx context.Context) bool
- func (f *Flamenco) WorkerState(e echo.Context) error
- func (f *Flamenco) WorkerStateChanged(e echo.Context) error
- type JobCompiler
- type JobDeleter
- type LastRendered
- type LocalStorage
- type LogStorage
- type PersistenceService
- type SHA256Hasher
- type Shaman
- type TaskStateMachine
- type TimeService
- type VariableReplacer
- type WorkerPasswordHasher
- type WorkerSleepScheduler
Constants ¶
const JobFilesURLPrefix = "/job-files"
JobFilesURLPrefix is the URL prefix that the Flamenco API expects to serve the job-specific local files, i.e. the ones that are managed by `local_storage.StorageInfo`.
Variables ¶
var ( ErrSetupConfigUnusableSource = errors.New("sources should not have the 'is_usable' field set to false") ErrSetupConfigEmptyStorageLocation = errors.New("'storageLocation' field must not be empty") ErrSetupConfigEmptyPath = errors.New("'path' field must not be empty while using the 'file_association' source") ErrSetupConfigEmptyPathOrInput = errors.New("'path' or 'input' fields must not be empty while using the 'input_path' or 'path_envvar' sources") ErrSetupConfigEmptySource = errors.New("'source' field must not be empty") )
Functions ¶
func SwaggerValidator ¶
func SwaggerValidator(swagger *openapi3.T, persist PersistenceService) echo.MiddlewareFunc
SwaggerValidator constructs the OpenAPI validator, which also handles authentication.
func WorkerAuth ¶
func WorkerAuth(ctx context.Context, authInfo *openapi3filter.AuthenticationInput, persist PersistenceService) error
OpenAPI authentication function for authing workers. The worker will be fetched from the database and stored in the request context.
Types ¶
type BCryptHasher ¶
type BCryptHasher struct{}
BCryptHasher uses BCrypt to hash the worker passwords.
func (BCryptHasher) CompareHashAndPassword ¶
func (h BCryptHasher) CompareHashAndPassword(hashedPassword, password []byte) error
func (BCryptHasher) GenerateHashedPassword ¶
func (h BCryptHasher) GenerateHashedPassword(password []byte) ([]byte, error)
type ChangeBroadcaster ¶
type ChangeBroadcaster interface {
// BroadcastNewJob sends a 'new job' notification to all SocketIO clients.
BroadcastNewJob(jobUpdate api.EventJobUpdate)
BroadcastJobUpdate(jobUpdate api.EventJobUpdate)
BroadcastLastRenderedImage(update api.EventLastRenderedUpdate)
BroadcastWorkerUpdate(workerUpdate api.EventWorkerUpdate)
BroadcastNewWorker(workerUpdate api.EventWorkerUpdate)
BroadcastWorkerTagUpdate(workerTagUpdate api.EventWorkerTagUpdate)
BroadcastNewWorkerTag(workerTagUpdate api.EventWorkerTagUpdate)
}
type ConfigService ¶
type ConfigService interface {
VariableReplacer
Get() *config.Conf
// EffectiveStoragePath returns the job storage path used by Flamenco. It's
// basically the configured storage path, but can be influenced by other
// options (like Shaman).
EffectiveStoragePath() string
// IsFirstRun returns true if this is likely to be the first run of Flamenco.
IsFirstRun() (bool, error)
// ForceFirstRun forces IsFirstRun() to return true. This is used to force the
// setup assistant on a configured system.
ForceFirstRun()
// Save writes the in-memory configuration to the config file.
Save() error
}
type FarmStatusService ¶
type FarmStatusService interface {
Report() api.FarmStatusReport
}
type Flamenco ¶
type Flamenco struct {
// contains filtered or unexported fields
}
func NewFlamenco ¶
func NewFlamenco( jc JobCompiler, jps PersistenceService, b ChangeBroadcaster, logStorage LogStorage, cs ConfigService, sm TaskStateMachine, sha Shaman, ts TimeService, lr LastRendered, localStorage LocalStorage, wss WorkerSleepScheduler, jd JobDeleter, farmstatus FarmStatusService, ) *Flamenco
NewFlamenco creates a new Flamenco service.
func (*Flamenco) CheckSharedStoragePath ¶
func (*Flamenco) DeleteJob ¶
DeleteJob marks the job as "deletion requested" so that the job deletion service can actually delete it.
func (*Flamenco) DeleteJobWhatWouldItDo ¶
func (*Flamenco) DeleteWorker ¶
func (*Flamenco) DeleteWorkerTag ¶
func (*Flamenco) FetchGlobalLastRenderedInfo ¶
func (*Flamenco) FetchJobBlocklist ¶
func (*Flamenco) FetchJobLastRenderedInfo ¶
func (*Flamenco) FetchJobTasks ¶
func (*Flamenco) FetchTaskLogInfo ¶
func (*Flamenco) FetchTaskLogTail ¶
func (*Flamenco) FetchWorker ¶
func (*Flamenco) FetchWorkerSleepSchedule ¶
func (*Flamenco) FetchWorkerTag ¶
func (*Flamenco) GetConfigurationFile ¶
func (*Flamenco) GetSharedStorage ¶
func (*Flamenco) GetVariables ¶
func (*Flamenco) MayWorkerRun ¶
func (*Flamenco) RegisterWorker ¶
RegisterWorker registers a new worker and stores it in the database.
func (*Flamenco) RemoveJobBlocklist ¶
func (*Flamenco) RequestWorkerStatusChange ¶
func (*Flamenco) SaveSetupAssistantConfig ¶
func (*Flamenco) SetJobPriority ¶
SetJobPriority is used by the web interface to change a job's priority.
func (*Flamenco) SetJobStatus ¶
SetJobStatus is used by the web interface to change a job's status.
func (*Flamenco) SetTaskStatus ¶
SetTaskStatus is used by the web interface to change a task's status.
func (*Flamenco) SetWorkerSleepSchedule ¶
func (*Flamenco) SetWorkerTags ¶
func (*Flamenco) ShamanCheckout ¶
Create a directory, and symlink the required files into it. The files must all have been uploaded to Shaman before calling this endpoint. (POST /shaman/checkout/create/{checkoutID})
func (*Flamenco) ShamanCheckoutRequirements ¶
Checks a Shaman Requirements file, and reports which files are unknown. (POST /shaman/checkout/requirements)
func (*Flamenco) ShamanFileStore ¶
func (f *Flamenco) ShamanFileStore(e echo.Context, checksum string, filesize int, params api.ShamanFileStoreParams) error
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. (POST /shaman/files/{checksum}/{filesize})
func (*Flamenco) ShamanFileStoreCheck ¶
Check the status of a file on the Shaman server. (OPTIONS /shaman/files/{checksum}/{filesize})
func (*Flamenco) TaskOutputProduced ¶
func (*Flamenco) UpdateWorkerTag ¶
func (*Flamenco) WaitForShutdown ¶
WaitForShutdown waits until Flamenco wants to shut down the application. Returns `true` when the application should restart. Returns `false` when the context closes.
func (*Flamenco) WorkerState ¶
(GET /api/worker/state)
type JobCompiler ¶
type JobCompiler interface {
ListJobTypes() api.AvailableJobTypes
GetJobType(typeName string) (api.AvailableJobType, error)
Compile(ctx context.Context, job api.SubmittedJob) (*job_compilers.AuthoredJob, error)
}
type JobDeleter ¶
type JobDeleter interface {
QueueJobDeletion(ctx context.Context, job *persistence.Job) error
QueueMassJobDeletion(ctx context.Context, lastUpdatedMax time.Time) error
WhatWouldBeDeleted(job *persistence.Job) api.JobDeletionInfo
}
type LastRendered ¶
type LastRendered interface {
// QueueImage queues an image for processing. Returns
// `last_rendered.ErrQueueFull` if there is no more space in the queue for
// new images.
QueueImage(payload last_rendered.Payload) error
// PathForJob returns the base path for this job's last-rendered images.
PathForJob(jobUUID string) string
// ThumbSpecs returns the thumbnail specifications.
ThumbSpecs() []last_rendered.Thumbspec
// JobHasImage returns true only if the job actually has a last-rendered image.
JobHasImage(jobUUID string) bool
}
LastRendered processes the "last rendered" images.
type LocalStorage ¶
type LocalStorage interface {
// RelPath tries to make the given path relative to the local storage root.
// Assumes `path` is already an absolute path.
RelPath(path string) (string, error)
}
LocalStorage handles the storage organisation of local files like the last-rendered images.
type LogStorage ¶
type LogStorage interface {
Write(logger zerolog.Logger, jobID, taskID string, logText string) error
WriteTimestamped(logger zerolog.Logger, jobID, taskID string, logText string) error
RotateFile(logger zerolog.Logger, jobID, taskID string)
Tail(jobID, taskID string) (string, error)
TaskLogSize(jobID, taskID string) (int64, error)
Filepath(jobID, taskID string) string
}
LogStorage handles incoming task logs.
type PersistenceService ¶
type PersistenceService interface {
StoreAuthoredJob(ctx context.Context, authoredJob job_compilers.AuthoredJob) error
// FetchJob fetches a single job, without fetching its tasks.
FetchJob(ctx context.Context, jobID string) (*persistence.Job, error)
FetchJobs(ctx context.Context) ([]*persistence.Job, error)
SaveJobPriority(ctx context.Context, job *persistence.Job) error
// FetchTask fetches the given task and the accompanying job.
FetchTask(ctx context.Context, taskID string) (*persistence.Task, error)
// FetchTaskJobUUID fetches the UUID of the job this task belongs to.
FetchTaskJobUUID(ctx context.Context, taskID string) (string, error)
FetchTaskFailureList(context.Context, *persistence.Task) ([]*persistence.Worker, error)
SaveTaskActivity(ctx context.Context, t *persistence.Task) error
// TaskTouchedByWorker marks the task as 'touched' by a worker. This is used for timeout detection.
TaskTouchedByWorker(context.Context, *persistence.Task) error
CreateWorker(ctx context.Context, w *persistence.Worker) error
FetchWorker(ctx context.Context, uuid string) (*persistence.Worker, error)
FetchWorkers(ctx context.Context) ([]*persistence.Worker, error)
FetchWorkerTask(context.Context, *persistence.Worker) (*persistence.Task, error)
SaveWorker(ctx context.Context, w *persistence.Worker) error
SaveWorkerStatus(ctx context.Context, w *persistence.Worker) error
WorkerSeen(ctx context.Context, w *persistence.Worker) error
DeleteWorker(ctx context.Context, uuid string) error
// ScheduleTask finds a task to execute by the given worker, and assigns it to that worker.
// If no task is available, (nil, nil) is returned, as this is not an error situation.
ScheduleTask(ctx context.Context, w *persistence.Worker) (*persistence.Task, error)
AddWorkerToTaskFailedList(context.Context, *persistence.Task, *persistence.Worker) (numFailed int, err error)
// ClearFailureListOfTask clears the list of workers that failed this task.
ClearFailureListOfTask(context.Context, *persistence.Task) error
// ClearFailureListOfJob en-mass, for all tasks of this job, clears the list of workers that failed those tasks.
ClearFailureListOfJob(context.Context, *persistence.Job) error
// AddWorkerToJobBlocklist prevents this Worker of getting any task, of this type, on this job, from the task scheduler.
AddWorkerToJobBlocklist(ctx context.Context, job *persistence.Job, worker *persistence.Worker, taskType string) error
FetchJobBlocklist(ctx context.Context, jobUUID string) ([]persistence.JobBlock, error)
RemoveFromJobBlocklist(ctx context.Context, jobUUID, workerUUID, taskType string) error
ClearJobBlocklist(ctx context.Context, job *persistence.Job) error
// Worker tag management.
WorkerSetTags(ctx context.Context, worker *persistence.Worker, tagUUIDs []string) error
CreateWorkerTag(ctx context.Context, tag *persistence.WorkerTag) error
FetchWorkerTag(ctx context.Context, uuid string) (*persistence.WorkerTag, error)
FetchWorkerTags(ctx context.Context) ([]*persistence.WorkerTag, error)
DeleteWorkerTag(ctx context.Context, uuid string) error
SaveWorkerTag(ctx context.Context, tag *persistence.WorkerTag) error
// WorkersLeftToRun returns a set of worker UUIDs that can run tasks of the given type on the given job.
WorkersLeftToRun(ctx context.Context, job *persistence.Job, taskType string) (map[string]bool, error)
// CountTaskFailuresOfWorker returns the number of task failures of this worker, on this particular job and task type.
CountTaskFailuresOfWorker(ctx context.Context, job *persistence.Job, worker *persistence.Worker, taskType string) (int, error)
// Database queries.
QueryJobTaskSummaries(ctx context.Context, jobUUID string) ([]*persistence.Task, error)
// SetLastRendered sets this job as the one with the most recent rendered image.
SetLastRendered(ctx context.Context, j *persistence.Job) error
// GetLastRendered returns the UUID of the job with the most recent rendered image.
GetLastRenderedJobUUID(ctx context.Context) (string, error)
}
type SHA256Hasher ¶
type SHA256Hasher struct{}
func (SHA256Hasher) CompareHashAndPassword ¶
func (h SHA256Hasher) CompareHashAndPassword(hashedPassword, password []byte) error
func (SHA256Hasher) GenerateHashedPassword ¶
func (h SHA256Hasher) GenerateHashedPassword(password []byte) ([]byte, error)
type Shaman ¶
type Shaman interface {
// IsEnabled returns whether this Shaman service is enabled or not.
IsEnabled() bool
// Checkout creates a directory, and symlinks the required files into it. The
// files must all have been uploaded to Shaman before calling this.
// Returns the final checkout directory, as it may be modified to ensure uniqueness.
Checkout(ctx context.Context, checkout api.ShamanCheckout) (string, error)
// Requirements checks a Shaman Requirements file, and returns the subset
// containing the unknown files.
Requirements(ctx context.Context, requirements api.ShamanRequirementsRequest) (api.ShamanRequirementsResponse, error)
// Check the status of a file on the Shaman server.
FileStoreCheck(ctx context.Context, checksum string, filesize int64) api.ShamanFileStatus
// Store a new file on the Shaman server. Note that the Shaman server can
// return early when another client finishes uploading the exact same file, to
// prevent double uploads.
FileStore(ctx context.Context, file io.ReadCloser, checksum string, filesize int64, canDefer bool, originalFilename string) error
// EraseCheckout deletes the symlinks and the directory structure that makes up the checkout.
EraseCheckout(checkoutID string) error
}
type TaskStateMachine ¶
type TaskStateMachine interface {
// TaskStatusChange gives a Task a new status, and handles the resulting status changes on the job.
TaskStatusChange(ctx context.Context, task *persistence.Task, newStatus api.TaskStatus) error
// JobStatusChange gives a Job a new status, and handles the resulting status changes on its tasks.
JobStatusChange(ctx context.Context, job *persistence.Job, newJobStatus api.JobStatus, reason string) error
RequeueActiveTasksOfWorker(ctx context.Context, worker *persistence.Worker, reason string) error
RequeueFailedTasksOfWorkerOfJob(ctx context.Context, worker *persistence.Worker, job *persistence.Job, reason string) error
}
type TimeService ¶
TimeService provides functionality from the stdlib `time` module, but in a way that allows mocking.
type VariableReplacer ¶
type VariableReplacer interface {
NewVariableExpander(audience config.VariableAudience, platform config.VariablePlatform) *config.VariableExpander
ResolveVariables(audience config.VariableAudience, platform config.VariablePlatform) map[string]config.ResolvedVariable
NewVariableToValueConverter(audience config.VariableAudience, platform config.VariablePlatform) *config.ValueToVariableReplacer
}
type WorkerPasswordHasher ¶
type WorkerSleepScheduler ¶
type WorkerSleepScheduler interface {
FetchSchedule(ctx context.Context, workerUUID string) (*persistence.SleepSchedule, error)
SetSchedule(ctx context.Context, workerUUID string, schedule *persistence.SleepSchedule) error
WorkerStatus(ctx context.Context, workerUUID string) (api.WorkerStatus, error)
}