"/admin/network/media-servers":
    get:
        tags: [Network]
        operationId: getMediaServers
        summary: List media servers
        description: Returns every registered media-server instance, with its current activation status, load, and room list.
        responses:
            "200":
                description: Array of media-server records.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/MediaServer.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]

"/admin/network/media-server/{mediaServerId}":
    parameters:
        - in: path
          name: mediaServerId
          required: true
          schema: { type: string }
    get:
        tags: [Network]
        operationId: getMediaServer
        summary: Fetch a media server
        description: Returns a specific media-server record by id.
        responses:
            "200":
                description: Media server record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/MediaServer.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No media server with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
    put:
        tags: [Network]
        operationId: updateMediaServer
        summary: Update activation status
        description: |
            Mutates the media server's `activationStatus`. The handler only allows
            this single field — anything else in the body is ignored. Used to take
            servers out of rotation for maintenance or roll them in after registration.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [activationStatus]
                        properties:
                            activationStatus:
                                type: string
                                description: "Must match a `MediaServerActivationStatus` member (`Active`, `Disabled`, etc.)."
        responses:
            "200":
                description: Updated media server.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/MediaServer.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: No media server with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
            "422":
                description: '`activationStatus` is not in the enum.'
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]

"/admin/network/redis":
    post:
        tags: [Network]
        operationId: searchRedis
        summary: Inspect Redis (prefix-allowlisted)
        description: |
            SuperUser-only Redis introspection. Either supply a `pattern` (calls
            `SCAN MATCH`) or a `key` (reads the value, dispatching on its type
            — hash → HGETALL, set → SMEMBERS, string → GET).

            Both `pattern` and `key` must start with one of an allowlisted set of
            prefixes — namespaces that hold operational state are exposed,
            namespaces that can carry PII or secrets are deliberately omitted.

            Every call is audit-logged to the Admin Discord channel.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            pattern:
                                type: string
                                description: SCAN-style pattern. Mutually exclusive with `key`.
                            key:
                                type: string
                                description: Specific key to read. Mutually exclusive with `pattern`.
        responses:
            "200":
                description: |
                    Pattern result is an array of matched keys. Key result is the
                    Redis value cast appropriately — object for hashes, array for
                    sets, string for strings.
                content:
                    application/json:
                        schema:
                            oneOf:
                                - type: array
                                  items: { type: string }
                                  description: Keys matched by `SCAN MATCH`.
                                - type: object
                                  additionalProperties: { type: string }
                                  description: Hash value (`HGETALL`).
                                - type: array
                                  items: { type: string }
                                  description: Set members (`SMEMBERS`).
                                - type: string
                                  description: String value (`GET`).
            "400":
                description: '`pattern` / `key` is outside the allowlist.'
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                error: { type: string }
                                allowedPrefixes:
                                    type: array
                                    items: { type: string }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "422":
                description: Neither `pattern` nor `key` was supplied.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [SuperUser]

"/admin/network/redis-info":
    get:
        tags: [Network]
        operationId: getRedisInfo
        summary: Redis cluster INFO
        description: |
            Returns the raw INFO payload from the Redis cluster — replication
            topology, keyspace cardinality, memory stats, etc. Restricted to
            SuperUser because the payload leaks operational detail. Audit-logged
            to the Admin Discord channel on every call.
        responses:
            "200":
                description: INFO payload.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [info]
                            properties:
                                info:
                                    type: string
                                    description: Raw multi-section INFO output (newline-delimited `key:value` pairs grouped by `# Section` headers).
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [SuperUser]
