From cfb17b178da2055ef12b2aa2ad8f7f778a952bc3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Tue, 31 May 2022 17:17:37 +0200
Subject: [PATCH] OAPI: allow worker status change requests

This also introduces the 'lazy' status change boolean, which indicates
whether the status change should interrupt the worker's current task
(lazy=false), or only take effect after the task is finished (lazy=true).
---
 pkg/api/flamenco-openapi.yaml | 46 ++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/pkg/api/flamenco-openapi.yaml b/pkg/api/flamenco-openapi.yaml
index 103eecda..aa33ab02 100644
--- a/pkg/api/flamenco-openapi.yaml
+++ b/pkg/api/flamenco-openapi.yaml
@@ -281,6 +281,33 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/Worker" }
 
+  /api/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"
+
   ## Jobs
 
   /api/jobs/types:
@@ -1353,7 +1380,6 @@ components:
       type: object
       description: >
         Subset of a Worker, sent over SocketIO when a worker changes.
-        For new workers, `previous_status` will be excluded.
       properties:
         "id":
           type: string
@@ -1367,6 +1393,11 @@ components:
         "status": { $ref: "#/components/schemas/WorkerStatus" }
         "previous_status": { $ref: "#/components/schemas/WorkerStatus" }
         "status_requested": { $ref: "#/components/schemas/WorkerStatus" }
+        "lazy_status_request":
+          type: boolean
+          description: >
+            Whether the worker is allowed to finish its current task before the
+            status change is enforced. Mandatory when `status_requested` is set.
         "version": { type: string }
       required: [id, nickname, updated, status, version]
 
@@ -1415,6 +1446,7 @@ components:
         "nickname": { type: string }
         "status": { $ref: "#/components/schemas/WorkerStatus" }
         "status_requested": { $ref: "#/components/schemas/WorkerStatus" }
+        "lazy_status_request": { type: boolean }
         # These will be implemented soon:
         # "task_id":
         #   type: string
@@ -1452,6 +1484,18 @@ components:
             - version
             - supported_task_types
 
+    WorkerStatusChangeRequest:
+      type: object
+      description: Request for a Worker to change its status.
+      properties:
+        "status_requested": { $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_requested, is_lazy]
+
   securitySchemes:
     worker_auth:
       description: Username is the worker ID, password is the secret given at worker registration.