From f6532fa281bc14e4a632226953c26ff9acb1a642 Mon Sep 17 00:00:00 2001
From: Carlos Santos <4a.santos@gmail.com>
Date: Wed, 16 Apr 2025 11:09:18 +0200
Subject: [PATCH] backend: Add error responses for recording conflicts and
 service unavailability; update success response status

---
 .../error-recording-already-started.yaml         |  8 --------
 .../internal/error-recording-conflict.yaml       | 16 ++++++++++++++++
 .../internal/error-service-unavailable.yaml      | 11 +++++++++++
 .../internal/success-start-recording.yaml        |  2 +-
 backend/openapi/paths/internal/recordings.yaml   |  4 +++-
 5 files changed, 31 insertions(+), 10 deletions(-)
 delete mode 100644 backend/openapi/components/responses/internal/error-recording-already-started.yaml
 create mode 100644 backend/openapi/components/responses/internal/error-recording-conflict.yaml
 create mode 100644 backend/openapi/components/responses/internal/error-service-unavailable.yaml

diff --git a/backend/openapi/components/responses/internal/error-recording-already-started.yaml b/backend/openapi/components/responses/internal/error-recording-already-started.yaml
deleted file mode 100644
index f7e9dca..0000000
--- a/backend/openapi/components/responses/internal/error-recording-already-started.yaml
+++ /dev/null
@@ -1,8 +0,0 @@
-description: Conflict — The room is already being recorded
-content:
-    application/json:
-        schema:
-            $ref: '../../schemas/error.yaml'
-        example:
-            name: 'Recording Error'
-            message: 'The room "room-123" is already being recorded'
diff --git a/backend/openapi/components/responses/internal/error-recording-conflict.yaml b/backend/openapi/components/responses/internal/error-recording-conflict.yaml
new file mode 100644
index 0000000..5daa49c
--- /dev/null
+++ b/backend/openapi/components/responses/internal/error-recording-conflict.yaml
@@ -0,0 +1,16 @@
+description: Conflict — The recording cannot be started due to resource state conflicts
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/error.yaml'
+        examples:
+            already_recording:
+                summary: Room is already being recorded
+                value:
+                    name: 'Recording Error'
+                    message: 'The room "room-123" is already being recorded'
+            no_participants:
+                summary: Room has no participants
+                value:
+                    name: 'Recording Error'
+                    message: 'The room "room-123" has no participants'
diff --git a/backend/openapi/components/responses/internal/error-service-unavailable.yaml b/backend/openapi/components/responses/internal/error-service-unavailable.yaml
new file mode 100644
index 0000000..b662579
--- /dev/null
+++ b/backend/openapi/components/responses/internal/error-service-unavailable.yaml
@@ -0,0 +1,11 @@
+description: Service Unavailable — The recording service is unavailable
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/error.yaml'
+        examples:
+            starting_timeout:
+                summary: Recording service timed out
+                value:
+                    name: 'Recording Error'
+                    message: Recording in room 'room-123' timed out while starting
diff --git a/backend/openapi/components/responses/internal/success-start-recording.yaml b/backend/openapi/components/responses/internal/success-start-recording.yaml
index 3c090c2..9a92f79 100644
--- a/backend/openapi/components/responses/internal/success-start-recording.yaml
+++ b/backend/openapi/components/responses/internal/success-start-recording.yaml
@@ -6,7 +6,7 @@ content:
         example:
             recordingId: 'room-123--EG_XYZ--XX445'
             roomId: 'room-123'
-            status: 'STARTING'
+            status: 'ACTIVE'
             filename: 'room-123--XX445.mp4'
             startDate: 1600000000000
 headers:
diff --git a/backend/openapi/paths/internal/recordings.yaml b/backend/openapi/paths/internal/recordings.yaml
index 11d2bf7..ce7c257 100644
--- a/backend/openapi/paths/internal/recordings.yaml
+++ b/backend/openapi/paths/internal/recordings.yaml
@@ -20,11 +20,13 @@
             '404':
                 $ref: '../../components/responses/error-room-not-found.yaml'
             '409':
-                $ref: '../../components/responses/internal/error-recording-already-started.yaml'
+                $ref: '../../components/responses/internal/error-recording-conflict.yaml'
             '422':
                 $ref: '../../components/responses/validation-error.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
+            '503':
+                $ref: '../../components/responses/internal/error-service-unavailable.yaml'
 /recordings/{recordingId}/stop:
     post:
         operationId: stopRecording