From 52e9db6ef493f66a6d5d5e2726cc781ed8a6a4b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Thu, 12 May 2022 11:02:24 +0200
Subject: [PATCH] OAPI: add may-worker-run endpoint

Add an endpoint for Workers to poll while they're running a task, to see
if they're allowed to keep running it.
---
 pkg/api/flamenco-manager.yaml | 42 +++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/pkg/api/flamenco-manager.yaml b/pkg/api/flamenco-manager.yaml
index 5977531c..b027e178 100644
--- a/pkg/api/flamenco-manager.yaml
+++ b/pkg/api/flamenco-manager.yaml
@@ -221,6 +221,34 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /api/worker/task/{task_id}/may-i-run:
+    summary: Workers check whether they're allowed to keep running this task.
+    get:
+      operationId: mayWorkerRun
+      summary: >
+        The response indicates whether the worker is allowed to run / keep
+        running the task. Optionally contains a queued worker status change.
+      security: [{ worker_auth: [] }]
+      tags: [worker]
+      parameters:
+        - name: task_id
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: normal response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MayKeepRunning"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   ## Jobs
 
   /api/jobs/types:
@@ -727,6 +755,20 @@ components:
           type: string
           description: Log lines for this task, will be appended to logs sent earlier.
 
+    MayKeepRunning:
+      type: object
+      description: Indicates whether the worker may keep running the task.
+      properties:
+        "mayKeepRunning": { type: boolean }
+        "reason": { type: string }
+        "statusChangeRequested":
+          type: boolean
+          description: >
+            Indicates that a status change requested for the worker. It should
+            use the `workerState` operation to determine which state to go to
+            next. If this is `true`, `mayKeepRunning` MUST be `false`.
+      required: ["mayKeepRunning", "reason", "statusChangeRequested"]
+
     JobStatus:
       type: string
       enum: