add video upload types, add doc middleware to more routes

6 files changed, 88 insertions, 21 deletions

diff --git a/server/controllers/api/videos/index.ts b/server/controllers/api/videos/index.ts
index 703051ee2..8c6c44144 100644
--- a/server/controllers/api/videos/index.ts
+++ b/server/controllers/api/videos/index.ts
@@ -60,12 +60,25 @@ videosRouter.use('/', liveRouter)
 videosRouter.use('/', uploadRouter)
 videosRouter.use('/', updateRouter)
 
-videosRouter.get('/categories', listVideoCategories)
-videosRouter.get('/licences', listVideoLicences)
-videosRouter.get('/languages', listVideoLanguages)
-videosRouter.get('/privacies', listVideoPrivacies)
+videosRouter.get('/categories',
+  openapiOperationDoc({ operationId: 'getCategories' }),
+  listVideoCategories
+)
+videosRouter.get('/licences',
+  openapiOperationDoc({ operationId: 'getLicences' }),
+  listVideoLicences
+)
+videosRouter.get('/languages',
+  openapiOperationDoc({ operationId: 'getLanguages' }),
+  listVideoLanguages
+)
+videosRouter.get('/privacies',
+  openapiOperationDoc({ operationId: 'getPrivacies' }),
+  listVideoPrivacies
+)
 
 videosRouter.get('/',
+  openapiOperationDoc({ operationId: 'getVideos' }),
   paginationValidator,
   videosSortValidator,
   setDefaultVideosSort,
@@ -76,6 +89,7 @@ videosRouter.get('/',
 )
 
 videosRouter.get('/:id/description',
+  openapiOperationDoc({ operationId: 'getVideoDesc' }),
   asyncMiddleware(videosGetValidator),
   asyncMiddleware(getVideoDescription)
 )
@@ -91,6 +105,7 @@ videosRouter.get('/:id',
   asyncMiddleware(getVideo)
 )
 videosRouter.post('/:id/views',
+  openapiOperationDoc({ operationId: 'addView' }),
   asyncMiddleware(videosCustomGetValidator('only-immutable-attributes')),
   asyncMiddleware(viewVideo)
 )
diff --git a/server/controllers/api/videos/watching.ts b/server/controllers/api/videos/watching.ts
index 08190e583..8b15525aa 100644
--- a/server/controllers/api/videos/watching.ts
+++ b/server/controllers/api/videos/watching.ts
@@ -1,12 +1,19 @@
 import * as express from 'express'
 import { UserWatchingVideo } from '../../../../shared'
-import { asyncMiddleware, asyncRetryTransactionMiddleware, authenticate, videoWatchingValidator } from '../../../middlewares'
+import {
+  asyncMiddleware,
+  asyncRetryTransactionMiddleware,
+  authenticate,
+  openapiOperationDoc,
+  videoWatchingValidator
+} from '../../../middlewares'
 import { UserVideoHistoryModel } from '../../../models/user/user-video-history'
 import { HttpStatusCode } from '../../../../shared/core-utils/miscs/http-error-codes'
 
 const watchingRouter = express.Router()
 
 watchingRouter.put('/:videoId/watching',
+  openapiOperationDoc({ operationId: 'setProgress' }),
   authenticate,
   asyncMiddleware(videoWatchingValidator),
   asyncRetryTransactionMiddleware(userWatchVideo)
diff --git a/server/middlewares/validators/videos/video-live.ts b/server/middlewares/validators/videos/video-live.ts
index ffc8c47b3..b058ff5c1 100644
--- a/server/middlewares/validators/videos/video-live.ts
+++ b/server/middlewares/validators/videos/video-live.ts
@@ -72,7 +72,8 @@ const videoLiveAddValidator = getCommonVideoEditAttributes().concat([
 
       return res.fail({
         status: HttpStatusCode.FORBIDDEN_403,
-        message: 'Live is not enabled on this instance'
+        message: 'Live is not enabled on this instance',
+        type: ServerErrorCode.LIVE_NOT_ENABLED
       })
     }
 
@@ -81,7 +82,8 @@ const videoLiveAddValidator = getCommonVideoEditAttributes().concat([
 
       return res.fail({
         status: HttpStatusCode.FORBIDDEN_403,
-        message: 'Saving live replay is not allowed instance'
+        message: 'Saving live replay is not enabled on this instance',
+        type: ServerErrorCode.LIVE_NOT_ALLOWING_REPLAY
       })
     }
 
@@ -116,8 +118,8 @@ const videoLiveAddValidator = getCommonVideoEditAttributes().concat([
 
         return res.fail({
           status: HttpStatusCode.FORBIDDEN_403,
-          type: ServerErrorCode.MAX_USER_LIVES_LIMIT_REACHED,
-          message: 'Cannot create this live because the max user lives limit is reached.'
+          message: 'Cannot create this live because the max user lives limit is reached.',
+          type: ServerErrorCode.MAX_USER_LIVES_LIMIT_REACHED
         })
       }
     }
diff --git a/server/middlewares/validators/videos/videos.ts b/server/middlewares/validators/videos/videos.ts
index 52e6c5762..7f278c9f6 100644
--- a/server/middlewares/validators/videos/videos.ts
+++ b/server/middlewares/validators/videos/videos.ts
@@ -402,7 +402,8 @@ const videosAcceptChangeOwnershipValidator = [
     if (isAble === false) {
       res.fail({
         status: HttpStatusCode.PAYLOAD_TOO_LARGE_413,
-        message: 'The user video quota is exceeded with this video.'
+        message: 'The user video quota is exceeded with this video.',
+        type: ServerErrorCode.QUOTA_REACHED
       })
       return
     }
@@ -628,7 +629,8 @@ async function commonVideoChecksPass (parameters: {
   if (!isVideoFileSizeValid(videoFileSize.toString())) {
     res.fail({
       status: HttpStatusCode.PAYLOAD_TOO_LARGE_413,
-      message: 'This file is too large. It exceeds the maximum file size authorized.'
+      message: 'This file is too large. It exceeds the maximum file size authorized.',
+      type: ServerErrorCode.MAX_FILE_SIZE_REACHED
     })
     return false
   }
@@ -636,7 +638,8 @@ async function commonVideoChecksPass (parameters: {
   if (await isAbleToUploadVideo(user.id, videoFileSize) === false) {
     res.fail({
       status: HttpStatusCode.PAYLOAD_TOO_LARGE_413,
-      message: 'The user video quota is exceeded with this video.'
+      message: 'The user video quota is exceeded with this video.',
+      type: ServerErrorCode.QUOTA_REACHED
     })
     return false
   }
diff --git a/shared/models/server/server-error-code.enum.ts b/shared/models/server/server-error-code.enum.ts
index 2795fa569..115421d4d 100644
--- a/shared/models/server/server-error-code.enum.ts
+++ b/shared/models/server/server-error-code.enum.ts
@@ -1,18 +1,31 @@
 export const enum ServerErrorCode {
   /**
+   * The simplest form of payload too large: when the file size is over the
+   * global file size limit
+   */
+  MAX_FILE_SIZE_REACHED = 'max_file_size_reached',
+
+  /**
+   * The payload is too large for the user quota set
+   */
+  QUOTA_REACHED = 'quota_reached',
+
+  /**
    * Error yielded upon trying to access a video that is not federated, nor can
    * be. This may be due to: remote videos on instances that are not followed by
    * yours, and with your instance disallowing unknown instances being accessed.
    */
   DOES_NOT_RESPECT_FOLLOW_CONSTRAINTS = 'does_not_respect_follow_constraints',
 
+  LIVE_NOT_ENABLED = 'live_not_enabled',
+  LIVE_NOT_ALLOWING_REPLAY = 'live_not_allowing_replay',
+  LIVE_CONFLICTING_PERMANENT_AND_SAVE_REPLAY = 'live_conflicting_permanent_and_save_replay',
   /**
    * Pretty self-explanatory: the set maximum number of simultaneous lives was
    * reached, and this error is typically there to inform the user trying to
    * broadcast one.
    */
   MAX_INSTANCE_LIVES_LIMIT_REACHED = 'max_instance_lives_limit_reached',
-
   /**
    * Pretty self-explanatory: the set maximum number of simultaneous lives FOR
    * THIS USER was reached, and this error is typically there to inform the user
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 6c5a15087..b43b6bfa0 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1802,6 +1802,7 @@ paths:
   '/videos/{id}/views':
     post:
       summary: Add a view to a video
+      operationId: addView
       tags:
         - Video
       parameters:
@@ -1813,6 +1814,7 @@ paths:
   '/videos/{id}/watching':
     put:
       summary: Set watching progress of a video
+      operationId: setProgress
       tags:
         - Video
       security:
@@ -1851,7 +1853,10 @@ paths:
         '408':
           description: upload has timed out
         '413':
-          description: video file too large, due to quota or max body size limit set by the reverse-proxy
+          x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
+          description: |
+            If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
+            - `quota_reached` for quota limits wether daily or global
           headers:
             X-File-Maximum-Size:
               schema:
@@ -1951,7 +1956,11 @@ paths:
                 type: number
                 example: 0
         '413':
-          description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+          x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+          description: |
+            Disambiguate via `type`:
+            - `max_file_size_reached` for the absolute file size limit
+            - `quota_reached` for quota limits whether daily or global
         '415':
           description: video type unsupported
     put:
@@ -2027,10 +2036,14 @@ paths:
                 example: 0
         '403':
           description: video didn't pass upload filter
-        '413':
-          description: video file too large, due to quota or max body size limit set by the reverse-proxy
+        '404':
+          description: upload not found
+        '409':
+          description: chunk doesn't match range
         '422':
           description: video unreadable
+        '429':
+          description: too many concurrent requests
     delete:
       summary: Cancel the resumable upload of a video, deleting any data uploaded so far
       description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
@@ -2063,6 +2076,8 @@ paths:
               schema:
                 type: number
                 example: 0
+        '404':
+          description: upload not found
 
   /videos/imports:
     post:
@@ -2116,8 +2131,20 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoUploadResponse'
+        '400':
+          x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
+          description: |
+            Disambiguate via `type`:
+            - default type for a validation error
+            - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
         '403':
-          description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+          x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+          description: |
+            Disambiguate via `type`:
+            - `live_not_enabled` for a disabled live feature
+            - `live_not_allowing_replay` for a disabled replay feature
+            - `max_instance_lives_limit_reached` for the absolute concurrent live limit
+            - `max_user_lives_limit_reached` for the user concurrent live limit
       requestBody:
         content:
           multipart/form-data:
@@ -2318,7 +2345,7 @@ paths:
             type: string
         - name: videoIs
           in: query
-          description: only list blacklisted or deleted videos
+          description: only list deleted or blocklisted videos
           schema:
             type: string
             enum:
@@ -4396,7 +4423,7 @@ components:
       name: sort
       in: query
       required: false
-      description: Sort blacklists by criteria
+      description: Sort blocklists by criteria
       schema:
         type: string
         enum:
@@ -4859,7 +4886,7 @@ components:
       enum:
         - 0
         - 1
-      description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
+      description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
       example: 1
 
     VideoStateConstant: