From 9985860c6690bbc3ac9975aef7ab69ad9bae0490 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Thu, 5 May 2022 16:02:47 +0200
Subject: [PATCH] OAPI: endpoint `/api/tasks/{task_id}/setstatus` for changing
 task status

This endpoint is for humans to manage individual tasks. Workers post task
updates to another endpoint.
---
 pkg/api/flamenco-manager.yaml | 41 +++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/pkg/api/flamenco-manager.yaml b/pkg/api/flamenco-manager.yaml
index 981e346a..2eb372e1 100644
--- a/pkg/api/flamenco-manager.yaml
+++ b/pkg/api/flamenco-manager.yaml
@@ -399,6 +399,38 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /api/tasks/{task_id}/setstatus:
+    summary: >
+      Request a status change for the given task. This may have effect on the
+      job status as well. This endpoint is meant for humans managing tasks via
+      the web interface. Workers post to `/api/worker/task/{task_id}` instead.
+    post:
+      operationId: setTaskStatus
+      tags: [jobs]
+      parameters:
+        - name: task_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/TaskStatusChange"
+      responses:
+        "204":
+          description: Status change was accepted.
+        "422":
+          description: The requested status change is not valid for the current status of the task.
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   ## Shaman
 
   /shaman/checkout/requirements:
@@ -990,6 +1022,15 @@ components:
           description: The reason for this status change.
       required: [status, reason]
 
+    TaskStatusChange:
+      type: object
+      properties:
+        status: { $ref: "#/components/schemas/TaskStatus" }
+        reason:
+          type: string
+          description: The reason for this status change.
+      required: [status, reason]
+
     Error:
       description: Generic error response.
       type: object