navidrome/plugins/schemas/websocket_callback.yaml

version: v1-draft

exports:
  nd_websocket_on_text_message:
    description: |
      Called when a text message is received on a WebSocket connection.
      Plugins that use the WebSocket host service must export this function
      to handle incoming text messages.
    input:
      $ref: "#/components/schemas/OnTextMessageInput"
      contentType: application/json
    output:
      $ref: "#/components/schemas/OnTextMessageOutput"
      contentType: application/json

  nd_websocket_on_binary_message:
    description: |
      Called when a binary message is received on a WebSocket connection.
      Plugins that use the WebSocket host service must export this function
      to handle incoming binary data.
    input:
      $ref: "#/components/schemas/OnBinaryMessageInput"
      contentType: application/json
    output:
      $ref: "#/components/schemas/OnBinaryMessageOutput"
      contentType: application/json

  nd_websocket_on_error:
    description: |
      Called when an error occurs on a WebSocket connection.
      Plugins that use the WebSocket host service must export this function
      to handle connection errors.
    input:
      $ref: "#/components/schemas/OnErrorInput"
      contentType: application/json
    output:
      $ref: "#/components/schemas/OnErrorOutput"
      contentType: application/json

  nd_websocket_on_close:
    description: |
      Called when a WebSocket connection is closed.
      Plugins that use the WebSocket host service must export this function
      to handle connection closure events.
    input:
      $ref: "#/components/schemas/OnCloseInput"
      contentType: application/json
    output:
      $ref: "#/components/schemas/OnCloseOutput"
      contentType: application/json

components:
  schemas:
    OnTextMessageInput:
      description: Input provided when a text message is received
      properties:
        connectionId:
          type: string
          description: |
            The unique identifier for the WebSocket connection that received the message.
        message:
          type: string
          description: |
            The text message content received from the WebSocket.
      required:
        - connectionId
        - message

    OnTextMessageOutput:
      description: Output from the text message handler
      type: object
      properties:
        error:
          type: string
          nullable: true
          description: |
            Error message if the callback failed. Empty or null indicates success.

    OnBinaryMessageInput:
      description: Input provided when a binary message is received
      properties:
        connectionId:
          type: string
          description: |
            The unique identifier for the WebSocket connection that received the message.
        data:
          type: string
          format: byte
          description: |
            The binary data received from the WebSocket, encoded as base64.
      required:
        - connectionId
        - data

    OnBinaryMessageOutput:
      description: Output from the binary message handler
      type: object
      properties:
        error:
          type: string
          nullable: true
          description: |
            Error message if the callback failed. Empty or null indicates success.

    OnErrorInput:
      description: Input provided when an error occurs on a WebSocket connection
      properties:
        connectionId:
          type: string
          description: |
            The unique identifier for the WebSocket connection where the error occurred.
        error:
          type: string
          description: |
            The error message describing what went wrong.
      required:
        - connectionId
        - error

    OnErrorOutput:
      description: Output from the error handler
      type: object
      properties:
        error:
          type: string
          nullable: true
          description: |
            Error message if the callback failed. Empty or null indicates success.

    OnCloseInput:
      description: Input provided when a WebSocket connection is closed
      properties:
        connectionId:
          type: string
          description: |
            The unique identifier for the WebSocket connection that was closed.
        code:
          type: integer
          format: int32
          description: |
            The WebSocket close status code (e.g., 1000 for normal closure,
            1001 for going away, 1006 for abnormal closure).
        reason:
          type: string
          description: |
            The human-readable reason for the connection closure, if provided.
      required:
        - connectionId
        - code
        - reason

    OnCloseOutput:
      description: Output from the close handler
      type: object
      properties:
        error:
          type: string
          nullable: true
          description: |
            Error message if the callback failed. Empty or null indicates success.