From 2b7e2ecf7e89d456594cf9b7a9b10f4f1beabb77 Mon Sep 17 00:00:00 2001 From: juancarmore Date: Thu, 15 May 2025 21:59:38 +0200 Subject: [PATCH] openapi: add recording token generation endpoint and associated API responses; add recordingTokenCookie authentication method to recording endpoints --- .../headers/set-cookie-recording-token.yaml | 6 ++++ .../internal/recording-token-request.yaml | 10 +++++++ .../internal/error-participant-not-found.yaml | 8 ----- .../error-room-metadata-not-found.yaml | 8 +++++ .../error-room-participant-not-found.yaml | 16 ++++++++++ .../success-generate-recording-token.yaml | 13 ++++++++ backend/openapi/components/security.yaml | 6 ++++ .../openapi/openvidu-meet-internal-api.yaml | 2 ++ backend/openapi/paths/internal/meetings.yaml | 2 +- .../openapi/paths/internal/participants.yaml | 6 +++- backend/openapi/paths/internal/rooms.yaml | 30 +++++++++++++++++++ backend/openapi/paths/recordings.yaml | 7 +++++ 12 files changed, 104 insertions(+), 10 deletions(-) create mode 100644 backend/openapi/components/headers/set-cookie-recording-token.yaml create mode 100644 backend/openapi/components/requestBodies/internal/recording-token-request.yaml delete mode 100644 backend/openapi/components/responses/internal/error-participant-not-found.yaml create mode 100644 backend/openapi/components/responses/internal/error-room-metadata-not-found.yaml create mode 100644 backend/openapi/components/responses/internal/error-room-participant-not-found.yaml create mode 100644 backend/openapi/components/responses/internal/success-generate-recording-token.yaml diff --git a/backend/openapi/components/headers/set-cookie-recording-token.yaml b/backend/openapi/components/headers/set-cookie-recording-token.yaml new file mode 100644 index 0000000..6592be1 --- /dev/null +++ b/backend/openapi/components/headers/set-cookie-recording-token.yaml @@ -0,0 +1,6 @@ +description: > + The cookie containing the recording token. + This cookie is used to access the recordings in a room. +schema: + type: string + example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/requestBodies/internal/recording-token-request.yaml b/backend/openapi/components/requestBodies/internal/recording-token-request.yaml new file mode 100644 index 0000000..47d7ea5 --- /dev/null +++ b/backend/openapi/components/requestBodies/internal/recording-token-request.yaml @@ -0,0 +1,10 @@ +description: Room secret +required: true +content: + application/json: + schema: + type: object + properties: + secret: + type: string + description: The secret value from the room URL used to connect to the room. diff --git a/backend/openapi/components/responses/internal/error-participant-not-found.yaml b/backend/openapi/components/responses/internal/error-participant-not-found.yaml deleted file mode 100644 index 8f7a861..0000000 --- a/backend/openapi/components/responses/internal/error-participant-not-found.yaml +++ /dev/null @@ -1,8 +0,0 @@ -description: Participant not found -content: - application/json: - schema: - $ref: '../../schemas/error.yaml' - example: - error: 'Participant Error' - message: 'Participant "Alice" not found in room "room_123"' diff --git a/backend/openapi/components/responses/internal/error-room-metadata-not-found.yaml b/backend/openapi/components/responses/internal/error-room-metadata-not-found.yaml new file mode 100644 index 0000000..c8cfb97 --- /dev/null +++ b/backend/openapi/components/responses/internal/error-room-metadata-not-found.yaml @@ -0,0 +1,8 @@ +description: Room metadata not found +content: + application/json: + schema: + $ref: '../../schemas/error.yaml' + example: + error: 'Room Error' + message: 'Room metadata for "room_123" not found. Room "room_123" does not exist or has no recordings associated' diff --git a/backend/openapi/components/responses/internal/error-room-participant-not-found.yaml b/backend/openapi/components/responses/internal/error-room-participant-not-found.yaml new file mode 100644 index 0000000..b888d6f --- /dev/null +++ b/backend/openapi/components/responses/internal/error-room-participant-not-found.yaml @@ -0,0 +1,16 @@ +description: Room or participant not found +content: + application/json: + schema: + $ref: '../../schemas/error.yaml' + examples: + participant_not_found: + summary: Participant not found + value: + error: 'Participant Error' + message: 'Participant "Alice" not found in room "room_123"' + room_not_found: + summary: Room not found + value: + error: 'Room Error' + message: 'Room "room_123" not found' diff --git a/backend/openapi/components/responses/internal/success-generate-recording-token.yaml b/backend/openapi/components/responses/internal/success-generate-recording-token.yaml new file mode 100644 index 0000000..8ec070e --- /dev/null +++ b/backend/openapi/components/responses/internal/success-generate-recording-token.yaml @@ -0,0 +1,13 @@ +description: Successfully generated the recording token +headers: + Set-Cookie: + $ref: '../../headers/set-cookie-recording-token.yaml' +content: + application/json: + schema: + type: object + properties: + token: + type: string + description: > + The token to access the recordings in the specified OpenVidu Meet room. diff --git a/backend/openapi/components/security.yaml b/backend/openapi/components/security.yaml index 456a855..1a367f2 100644 --- a/backend/openapi/components/security.yaml +++ b/backend/openapi/components/security.yaml @@ -22,3 +22,9 @@ participantTokenCookie: in: cookie description: > The JWT token to authenticate the participant when entering the room. +recordingTokenCookie: + type: apiKey + name: OvMeetRecordingToken + in: cookie + description: > + The JWT token containing permissions to access the recordings in a room. diff --git a/backend/openapi/openvidu-meet-internal-api.yaml b/backend/openapi/openvidu-meet-internal-api.yaml index 510ddc4..1511b54 100644 --- a/backend/openapi/openvidu-meet-internal-api.yaml +++ b/backend/openapi/openvidu-meet-internal-api.yaml @@ -18,6 +18,8 @@ paths: $ref: './paths/internal/auth.yaml#/~1auth~1profile' /rooms/{roomId}: $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}' + /rooms/{roomId}/recording-token: + $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1recording-token' /rooms/{roomId}/roles: $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1roles' /rooms/{roomId}/roles/{secret}: diff --git a/backend/openapi/paths/internal/meetings.yaml b/backend/openapi/paths/internal/meetings.yaml index f07b37b..7b0a4c2 100644 --- a/backend/openapi/paths/internal/meetings.yaml +++ b/backend/openapi/paths/internal/meetings.yaml @@ -44,6 +44,6 @@ '403': $ref: '../../components/responses/forbidden-error.yaml' '404': - $ref: '../../components/responses/internal/error-participant-not-found.yaml' + $ref: '../../components/responses/internal/error-room-participant-not-found.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' diff --git a/backend/openapi/paths/internal/participants.yaml b/backend/openapi/paths/internal/participants.yaml index 3fa564a..59d3783 100644 --- a/backend/openapi/paths/internal/participants.yaml +++ b/backend/openapi/paths/internal/participants.yaml @@ -23,6 +23,8 @@ $ref: '../../components/responses/error-room-not-found.yaml' '409': $ref: '../../components/responses/internal/error-participant-already-exists.yaml' + '422': + $ref: '../../components/responses/validation-error.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' /participants/token/refresh: @@ -47,8 +49,10 @@ '403': $ref: '../../components/responses/forbidden-error.yaml' '404': - $ref: '../../components/responses/error-room-not-found.yaml' + $ref: '../../components/responses/internal/error-room-participant-not-found.yaml' '409': $ref: '../../components/responses/internal/error-participant-token-still-valid.yaml' + '422': + $ref: '../../components/responses/validation-error.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' diff --git a/backend/openapi/paths/internal/rooms.yaml b/backend/openapi/paths/internal/rooms.yaml index 1c84062..1253fe4 100644 --- a/backend/openapi/paths/internal/rooms.yaml +++ b/backend/openapi/paths/internal/rooms.yaml @@ -25,6 +25,36 @@ $ref: '../../components/responses/validation-error.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' +/rooms/{roomId}/recording-token: + post: + operationId: generateRecordingToken + summary: Generate recording token + description: > + Generates a token with recording permissions for a specified OpenVidu Meet room. + This token can be used to access the recordings in a room. + tags: + - Internal API - Rooms + security: + - accessTokenCookie: [] + parameters: + - $ref: '../../components/parameters/room-id-path.yaml' + requestBody: + $ref: '../../components/requestBodies/internal/recording-token-request.yaml' + responses: + '200': + $ref: '../../components/responses/internal/success-generate-recording-token.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-room-secret.yaml' + '401': + $ref: '../../components/responses/unauthorized-error.yaml' + '403': + $ref: '../../components/responses/forbidden-error.yaml' + '404': + $ref: '../../components/responses/internal/error-room-metadata-not-found.yaml' + '422': + $ref: '../../components/responses/validation-error.yaml' + '500': + $ref: '../../components/responses/internal-server-error.yaml' /rooms/{roomId}/roles: get: operationId: getRoomRolesAndPermissions diff --git a/backend/openapi/paths/recordings.yaml b/backend/openapi/paths/recordings.yaml index 87bb6ab..648ae96 100644 --- a/backend/openapi/paths/recordings.yaml +++ b/backend/openapi/paths/recordings.yaml @@ -5,11 +5,15 @@ description: > Retrieves a paginated list of all recordings available in the system. You can apply filters to narrow down the results based on specific criteria. + + > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method, + the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] - accessTokenCookie: [] + - recordingTokenCookie: [] parameters: # - name: status # in: query @@ -90,6 +94,7 @@ security: - apiKeyInHeader: [] - accessTokenCookie: [] + - recordingTokenCookie: [] parameters: - $ref: '../components/parameters/recording-id.yaml' responses: @@ -116,6 +121,7 @@ security: - apiKeyInHeader: [] - accessTokenCookie: [] + - recordingTokenCookie: [] parameters: - $ref: '../components/parameters/recording-id.yaml' responses: @@ -147,6 +153,7 @@ security: - apiKeyInHeader: [] - accessTokenCookie: [] + - recordingTokenCookie: [] parameters: - $ref: '../components/parameters/recording-id.yaml' - $ref: '../components/parameters/recording-range.yaml'