openapi.yaml

openapi: 3.1.0
info:
  title: Druid CLI
  version: 0.1.0
  description: |
    Druid CLI launches and manages container-backed scroll applications, like
    game servers, databases, and web servers.
  contact: {}

servers:
  - url: /
    description: Druid CLI API

tags:
  - name: scroll
    description: Scroll management and command execution
  - name: logs
    description: Log streaming and retrieval
  - name: queue
    description: Command queue management
  - name: websocket
    description: WebSocket connections and tokens
  - name: port
    description: Port information and status
  - name: health
    description: Health checks and status
  - name: runtime
    description: Multi-scroll runtime management
  - name: daemon
    description: Daemon lifecycle management
  - name: watch
    description: File watching and development mode
  - name: annotations
    description: Annotation file access

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from identity provider

    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: Short-lived query token for WebSocket connections

  schemas:
    HealthResponse:
      type: object
      required:
        - mode
      properties:
        mode:
          type: string
          description: Current health status mode
          example: "ok"
        progress:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Progress percentage for loading operations
        start_date:
          type: string
          format: date-time
          nullable: true
          description: When the daemon started

    CreateScrollRequest:
      type: object
      required:
        - artifact
      properties:
        id:
          type: string
          description: Deprecated alias for name. Optional stable runtime id/name. If omitted, the daemon generates an id.
          example: jobs
        name:
          type: string
          description: Optional stable runtime id/name. If omitted, the daemon generates an id; the display name still comes from scroll.yaml.
          example: jobs
        artifact:
          type: string
          description: OCI artifact reference or local scroll path
          example: artifacts.druid.gg/test/test:test
        owner_id:
          type: string
          description: Runtime owner id used for customer-facing route authorization.
        namespace:
          type: string
          description: Kubernetes namespace for runtime resources. Ignored by non-Kubernetes backends.
        registry_credentials:
          type: array
          items:
            $ref: '#/components/schemas/RegistryCredential'

    EnsureScrollRequest:
      type: object
      required:
        - artifact
      properties:
        id:
          type: string
        name:
          type: string
        artifact:
          type: string
        artifact_digest:
          type: string
        owner_id:
          type: string
          description: Runtime owner id used for customer-facing route authorization.
        namespace:
          type: string
          description: Kubernetes namespace for runtime resources. Ignored by non-Kubernetes backends.
        registry_credentials:
          type: array
          items:
            $ref: '#/components/schemas/RegistryCredential'

    RegistryCredential:
      type: object
      required:
        - host
        - username
        - password
      properties:
        host:
          type: string
        username:
          type: string
        password:
          type: string

    RuntimeRoutingTarget:
      type: object
      required:
        - name
        - procedure
        - port_name
        - port
        - protocol
        - service_name
        - service_port
      properties:
        name:
          type: string
        procedure:
          type: string
        port_name:
          type: string
        port:
          type: integer
        protocol:
          type: string
        namespace:
          type: string
        service_name:
          type: string
        service_port:
          type: integer
        selector:
          type: object
          additionalProperties:
            type: string

    RuntimeRouteAssignment:
      type: object
      properties:
        name:
          type: string
        port_name:
          type: string
        host:
          type: string
        external_ip:
          type: string
        public_port:
          type: integer
        url:
          type: string
        protocol:
          type: string

    ApplyRoutingRequest:
      type: object
      required:
        - assignments
      properties:
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/RuntimeRouteAssignment'

    UpdateScrollRequest:
      type: object
      properties:
        artifact:
          type: string
          description: Optional target artifact. If omitted, the daemon refreshes the runtime's current artifact.
        registry_credentials:
          type: array
          items:
            $ref: '#/components/schemas/RegistryCredential'

    RuntimeArtifactOperationRequest:
      type: object
      required:
        - artifact
      properties:
        artifact:
          type: string
        restart:
          type: boolean
        registry_credentials:
          type: array
          items:
            $ref: '#/components/schemas/RegistryCredential'
          default: false

    PublishUIPackageRequest:
      type: object
      properties:
        path:
          type: string
          description: Optional scroll-root-relative .wasm path. Defaults to private/dist/app.wasm or public/dist/app.wasm.

    RuntimeUIPackage:
      type: object
      required:
        - url
        - path
        - sha256
        - updated_at
      properties:
        url:
          type: string
        path:
          type: string
        sha256:
          type: string
        updated_at:
          type: string
          format: date-time

    RuntimeUIPackages:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/RuntimeUIPackage'

    LockStatus:
      type: object
      required:
        - status
        - last_status_change
      properties:
        status:
          type: string
          enum: [running, done, error, waiting]
        exit_code:
          type: integer
          nullable: true
        last_status_change:
          type: integer
          format: int64

    ProcedureStatusMap:
      type: object
      additionalProperties:
        type: object
        additionalProperties:
          $ref: '#/components/schemas/LockStatus'

    ScrollLogMap:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    RuntimeScroll:
      type: object
      required:
        - id
        - artifact
        - root
        - scroll_name
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
        owner_id:
          type: string
        artifact:
          type: string
        root:
          type: string
        scroll_name:
          type: string
        status:
          type: string
          enum: [created, running, stopped, error, deleted]
        last_error:
          type: string
        routing:
          type: array
          items:
            $ref: '#/components/schemas/RuntimeRouteAssignment'
        ui_packages:
          $ref: '#/components/schemas/RuntimeUIPackages'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        procedures:
          $ref: '#/components/schemas/ProcedureStatusMap'

    DeletedScroll:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
        status:
          type: string
          example: deleted

    RuntimePortStatus:
      type: object
      required:
        - name
        - procedure
        - port
        - protocol
        - bound
        - traffic
        - source
      properties:
        name:
          type: string
        procedure:
          type: string
        port:
          type: integer
        protocol:
          type: string
        bound:
          type: boolean
        host_ip:
          type: string
        host_port:
          type: integer
        traffic:
          type: boolean
        traffic_bytes:
          type: integer
          format: int64
        rx_bytes:
          type: integer
          format: int64
        tx_bytes:
          type: integer
          format: int64
        keepAliveTraffic:
          type: string
        traffic_window:
          type: string
        traffic_ok:
          type: boolean
        last_activity_at:
          type: string
          format: date-time
        source:
          type: string

paths:
  # Runtime Scroll Endpoints
  /api/v1/scrolls:
    get:
      operationId: listScrolls
      summary: List runtime scrolls
      tags: [runtime, daemon]
      responses:
        '200':
          description: Runtime scrolls
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuntimeScroll'
    post:
      operationId: createScroll
      summary: Create runtime scroll
      tags: [runtime, daemon]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScrollRequest'
      responses:
        '201':
          description: Runtime scroll created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  /api/v1/scrolls/ensure:
    post:
      operationId: ensureScroll
      summary: Ensure runtime scroll exists and optionally starts
      tags: [runtime, daemon]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnsureScrollRequest'
      responses:
        '200':
          description: Runtime scroll ensured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  /api/v1/scrolls/{id}:
    get:
      operationId: getScroll
      summary: Get runtime scroll
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Runtime scroll
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'
        '404':
          description: Runtime scroll not found
    delete:
      operationId: deleteScroll
      summary: Delete runtime scroll
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Runtime scroll deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedScroll'
        '404':
          description: Runtime scroll not found

  /api/v1/scrolls/{id}/start:
    post:
      operationId: startScroll
      summary: Start runtime scroll
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Started runtime scroll
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  /api/v1/scrolls/{id}/stop:
    post:
      operationId: stopScroll
      summary: Stop runtime scroll workloads while preserving data
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Stopped runtime scroll
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  /api/v1/scrolls/{id}/update:
    post:
      operationId: updateScroll
      summary: Update runtime scroll files and state
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScrollRequest'
      responses:
        '200':
          description: Updated runtime scroll
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'
        '404':
          description: Runtime scroll not found

  /api/v1/scrolls/{id}/commands/{command}:
    post:
      operationId: runScrollCommand
      summary: Run runtime scroll command
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: command
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated runtime scroll
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'
        '404':
          description: Runtime scroll not found

  /api/v1/scrolls/{id}/config:
    get:
      operationId: getScrollConfig
      summary: Get parsed scroll config
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Parsed scroll config
          content:
            application/json:
              schema:
                type: object

  /api/v1/scrolls/{id}/queue:
    get:
      operationId: getScrollQueue
      summary: Get runtime queue state
      tags: [queue, runtime]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Queue state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcedureStatusMap'

  /api/v1/scrolls/{id}/consoles:
    get:
      operationId: getScrollConsoles
      summary: Get scroll-scoped consoles
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Consoles keyed by procedure
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/scrolls/{id}/logs:
    get:
      operationId: getScrollLogs
      summary: Get scroll-scoped logs
      tags: [logs, runtime]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Logs keyed by procedure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrollLogMap'

  /api/v1/scrolls/{id}/ports:
    get:
      operationId: getScrollPorts
      summary: Get runtime scroll port status
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Runtime scroll port status
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuntimePortStatus'
        '404':
          description: Runtime scroll not found

  /api/v1/scrolls/{id}/routing/targets:
    get:
      operationId: getScrollRoutingTargets
      summary: Get stable backend routing targets
      tags: [runtime, port]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Routing targets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuntimeRoutingTarget'

  /api/v1/scrolls/{id}/routing:
    post:
      operationId: applyScrollRouting
      summary: Persist operator-assigned public routing
      tags: [runtime, port]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyRoutingRequest'
      responses:
        '200':
          description: Updated runtime scroll
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  /api/v1/scrolls/{id}/ui/packages:
    get:
      operationId: getScrollUIPackages
      summary: Get published UI package URLs
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Published UI packages by scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeUIPackages'

  /api/v1/scrolls/{id}/ui/packages/{scope}/publish:
    post:
      operationId: publishScrollUIPackage
      summary: Publish an already-built Druid UI WASM package
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: scope
          in: path
          required: true
          schema:
            type: string
            enum: [private, public]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishUIPackageRequest'
      responses:
        '200':
          description: Runtime scroll with updated UI package metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  /api/v1/scrolls/{id}/backup:
    post:
      operationId: backupScroll
      summary: Execute runtime backup
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuntimeArtifactOperationRequest'
      responses:
        '200':
          description: Backup completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  /api/v1/scrolls/{id}/restore:
    post:
      operationId: restoreScroll
      summary: Execute runtime restore
      tags: [runtime, daemon]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuntimeArtifactOperationRequest'
      responses:
        '200':
          description: Restore completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeScroll'

  # Health Endpoint
  /api/v1/health:
    get:
      operationId: getHealthAuth
      summary: Get health status
      description: Get daemon health status
      tags: [health, daemon]
      responses:
        '200':
          description: Healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'