openapi: 3.1.0
info:
  title: Athena WebSocket Gateway API
  version: 1.3.0
  description: |
    The Athena WebSocket gateway mirrors the HTTP gateway contract over a persistent `wss`
    transport. Clients upgrade at `/wss/gateway`, exchange JSON messages described by
    `GatewayWsRequest`/`GatewayWsResponse`, and can introspect rollout metadata at
    `/wss/info`. Health probes are exposed at `/health` and `/ready` for Bun deployments.
servers:
- url: wss://your-athena-host.example.com
  description: Hosted Athena WebSocket gateway
- url: ws://localhost:7070
  description: Local Bun WebSocket gateway (default port)
paths:
  /wss/gateway:
    get:
      summary: Upgrade to the Athena WebSocket gateway
      description: |
        Upgrade the connection to `wss` and exchange JSON messages following the
        `GatewayWsRequest` schema. A connection-level `GatewayWsResponse` with a
        `status` of `success` is sent immediately after the upgrade, followed by
        one response per inbound request (matched by `request_id` when provided).
        Actions mirror the HTTP gateway surface.
      responses:
        "101":
          description: Switching Protocols
        "426":
          description: Missing or invalid WebSocket upgrade headers
  /wss/info:
    get:
      summary: Read the WebSocket gateway contract
      description: Provides supported actions, handshake path, and upstream base.
      responses:
        "200":
          description: Gateway contract metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayWsInfoResponse'
  /health:
    get:
      summary: Liveness probe for the WebSocket gateway
      responses:
        "200":
          description: Gateway is reachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayWsHealthResponse'
  /ready:
    get:
      summary: Readiness probe for the WebSocket gateway
      responses:
        "200":
          description: Gateway is ready to serve traffic
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayWsHealthResponse'
components:
  schemas:
    GatewayWsRequest:
      type: object
      required:
      - action
      - client_name
      - path
      properties:
        action:
          type: string
          enum:
          - gateway.fetch
          - gateway.insert
          - gateway.update
          - gateway.delete
          - gateway.query
        request_id:
          type: string
          description: Correlates responses when multiplexing requests over one socket.
        client_name:
          type: string
          description: Logical Athena client name (maps to X-Athena-Client).
        path:
          type: string
          description: Target gateway path (e.g., `/gateway/fetch`).
        method:
          type: string
          description: Optional explicit HTTP verb for multiplexed query actions.
        headers:
          type: object
          additionalProperties:
            type: string
          description: Optional headers to forward to the upstream HTTP gateway.
        query:
          type: object
          additionalProperties: true
          description: Query parameters appended to the upstream request URL.
        body:
          type: object
          additionalProperties: true
          description: JSON body forwarded to the upstream gateway.
          nullable: true
    GatewayWsResponse:
      type: object
      required:
      - status
      - message
      properties:
        request_id:
          type: string
          description: Mirrors the originating request_id when supplied by the client.
        status:
          type: string
          enum:
          - success
          - error
        message:
          type: string
        data:
          type: object
          description: |
            Envelope for upstream responses, errors, and connection metadata. May
            include `upstream` details, the upstream `body`, or connection info.
          properties:
            upstream:
              $ref: '#/components/schemas/GatewayWsUpstream'
            body:
              description: Parsed upstream response body, if available.
              nullable: true
            error:
              type: string
              description: Error message when the upstream call fails or times out.
            started_at:
              type: number
              format: int64
              description: Server start timestamp (sent on initial connect).
            api_base:
              type: string
              description: Upstream HTTP base URL used by the proxy.
          additionalProperties: true
    GatewayWsUpstream:
      type: object
      properties:
        status:
          type: integer
          format: int32
        status_text:
          type: string
    GatewayWsInfoResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Athena WebSocket gateway
        data:
          $ref: '#/components/schemas/GatewayWsInfoResponseData'
    GatewayWsInfoResponseData:
      type: object
      properties:
        transport:
          type: string
          example: wss
        path:
          type: string
          example: /wss/gateway
        api_base:
          type: string
          example: http://localhost:4052
        actions:
          type: array
          items:
            type: string
          example:
          - gateway.fetch
          - gateway.insert
          - gateway.update
          - gateway.delete
          - gateway.query
    GatewayWsHealthResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        port:
          type: integer
          example: 7070
        api_base:
          type: string
          example: http://localhost:4052
