openapi: 3.0.3
info:
  title: Galaxy Runtime Manager Internal REST API
  version: v1
  description: |
    This specification documents the internal trusted REST contract of
    `galaxy/rtmanager` served on `RTMANAGER_INTERNAL_HTTP_ADDR`
    (default `:8096`).

    The listener is not reachable from the public internet. Two caller
    classes use it: `Game Master` (inspect / restart / patch / stop /
    cleanup) and `Admin Service` (operational tooling, including
    force-cleanup). Runtime Manager treats every caller on this port as
    trusted and performs no user-level authorization; downstream services
    rely on network segmentation. There is no `X-User-ID` header
    contract.

    Transport rules:
    - request bodies are strict JSON only; unknown fields are rejected
      with `invalid_request`;
    - error responses use `{ "error": { "code", "message" } }`, identical
      to the Lobby contract;
    - stable error codes are: `invalid_request`, `not_found`, `conflict`,
      `service_unavailable`, `internal_error`, `image_pull_failed`,
      `image_ref_not_semver`, `semver_patch_only`,
      `container_start_failed`, `start_config_invalid`,
      `docker_unavailable`, `replay_no_op`.

    Caller identification:
    - the optional `X-Galaxy-Caller` request header carries the calling
      service identity (`gm` for `Game Master`, `admin` for `Admin
      Service`). Runtime Manager records the value as `op_source` in
      the `operation_log` (`gm_rest` or `admin_rest`). When the header
      is missing or carries an unknown value, Runtime Manager defaults
      to `op_source = admin_rest`.
servers:
  - url: http://localhost:8096
    description: Default local internal listener for Runtime Manager.
tags:
  - name: Runtimes
    description: Runtime lifecycle endpoints called by Game Master and Admin Service.
  - name: Probes
    description: Health and readiness probes.
paths:
  /healthz:
    get:
      tags:
        - Probes
      operationId: internalHealthz
      summary: Internal listener health probe
      responses:
        "200":
          description: Service is alive.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeResponse"
              examples:
                ok:
                  value:
                    status: ok
  /readyz:
    get:
      tags:
        - Probes
      operationId: internalReadyz
      summary: Internal listener readiness probe
      description: |
        Returns `200` only when the PostgreSQL primary, Redis master, and
        Docker daemon are reachable and the configured Docker network
        exists. Returns `503` with the standard error envelope otherwise.
      responses:
        "200":
          description: Service is ready to serve traffic.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeResponse"
              examples:
                ready:
                  value:
                    status: ready
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/runtimes:
    get:
      tags:
        - Runtimes
      operationId: internalListRuntimes
      summary: List all known runtime records
      description: |
        Returns the full list of runtime records known to Runtime Manager.
        Pagination is not supported in v1 — the working set is bounded by
        the number of games tracked by Lobby and is small enough to return
        in one response.
      parameters:
        - $ref: "#/components/parameters/XGalaxyCallerHeader"
      responses:
        "200":
          description: All runtime records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimesList"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/runtimes/{game_id}:
    get:
      tags:
        - Runtimes
      operationId: internalGetRuntime
      summary: Get one runtime record by game id
      parameters:
        - $ref: "#/components/parameters/GameIDPath"
        - $ref: "#/components/parameters/XGalaxyCallerHeader"
      responses:
        "200":
          description: Runtime record for the game.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeRecord"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/runtimes/{game_id}/start:
    post:
      tags:
        - Runtimes
      operationId: internalStartRuntime
      summary: Start a game engine container
      description: |
        Pulls the supplied `image_ref` per the configured pull policy and
        creates the engine container. Idempotent: a re-start with the same
        `image_ref` for an already-running record returns `200` with the
        current record and `error_code=replay_no_op` recorded in the
        operation log.
      parameters:
        - $ref: "#/components/parameters/GameIDPath"
        - $ref: "#/components/parameters/XGalaxyCallerHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRequest"
      responses:
        "200":
          description: Runtime record after the start operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeRecord"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/runtimes/{game_id}/stop:
    post:
      tags:
        - Runtimes
      operationId: internalStopRuntime
      summary: Stop a running game engine container
      description: |
        Issues `docker stop` with the configured timeout. Idempotent: stop
        on a record that is already `stopped` or `removed` returns
        success with `error_code=replay_no_op` recorded in the operation
        log.
      parameters:
        - $ref: "#/components/parameters/GameIDPath"
        - $ref: "#/components/parameters/XGalaxyCallerHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StopRequest"
      responses:
        "200":
          description: Runtime record after the stop operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeRecord"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/runtimes/{game_id}/restart:
    post:
      tags:
        - Runtimes
      operationId: internalRestartRuntime
      summary: Recreate a game engine container with the same image
      description: |
        Stops, removes, and re-runs the container with the current
        `image_ref`. The container id changes; the engine endpoint stays
        stable.
      parameters:
        - $ref: "#/components/parameters/GameIDPath"
        - $ref: "#/components/parameters/XGalaxyCallerHeader"
      responses:
        "200":
          description: Runtime record after the restart operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeRecord"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/runtimes/{game_id}/patch:
    post:
      tags:
        - Runtimes
      operationId: internalPatchRuntime
      summary: Recreate a game engine container with a new image
      description: |
        Restart with a new `image_ref`. Allowed only as a semver patch
        within the same major and minor line. Cross-major or cross-minor
        attempts return `409 conflict` with `error_code=semver_patch_only`.
        A non-semver `image_ref` returns `400 invalid_request` with
        `error_code=image_ref_not_semver`.
      parameters:
        - $ref: "#/components/parameters/GameIDPath"
        - $ref: "#/components/parameters/XGalaxyCallerHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchRequest"
      responses:
        "200":
          description: Runtime record after the patch operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeRecord"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /api/v1/internal/runtimes/{game_id}/container:
    delete:
      tags:
        - Runtimes
      operationId: internalCleanupRuntimeContainer
      summary: Remove an exited container
      description: |
        Calls `docker rm` for an already-stopped container and updates the
        runtime record to `removed`. Refuses with `409 conflict` if the
        record is still `running`. The host state directory is not
        deleted.
      parameters:
        - $ref: "#/components/parameters/GameIDPath"
        - $ref: "#/components/parameters/XGalaxyCallerHeader"
      responses:
        "200":
          description: Runtime record after the cleanup operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeRecord"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
components:
  parameters:
    GameIDPath:
      name: game_id
      in: path
      required: true
      description: Opaque stable game identifier owned by Lobby.
      schema:
        type: string
    XGalaxyCallerHeader:
      name: X-Galaxy-Caller
      in: header
      required: false
      description: |
        Identifies the calling service so Runtime Manager can record the
        right `op_source` in `operation_log` (`gm_rest` for `gm`,
        `admin_rest` for `admin`). Missing or unknown values default to
        `admin_rest`.
      schema:
        type: string
        enum:
          - gm
          - admin
  schemas:
    RuntimeRecord:
      type: object
      additionalProperties: false
      required:
        - game_id
        - status
        - state_path
        - docker_network
        - last_op_at
        - created_at
      properties:
        game_id:
          type: string
          description: Opaque stable game identifier owned by Lobby.
        status:
          type: string
          enum:
            - running
            - stopped
            - removed
          description: Current runtime status maintained by Runtime Manager.
        current_container_id:
          type: string
          nullable: true
          description: Docker container id; null when status is removed.
        current_image_ref:
          type: string
          nullable: true
          description: Image reference of the current container; null when status is removed.
        engine_endpoint:
          type: string
          nullable: true
          description: Stable engine URL `http://galaxy-game-{game_id}:8080`; null when status is removed.
        state_path:
          type: string
          description: Absolute host path of the per-game bind-mounted state directory.
        docker_network:
          type: string
          description: Docker network name observed when the container was created.
        started_at:
          type: string
          format: date-time
          nullable: true
          description: UTC timestamp of the most recent successful start.
        stopped_at:
          type: string
          format: date-time
          nullable: true
          description: UTC timestamp of the most recent stop.
        removed_at:
          type: string
          format: date-time
          nullable: true
          description: UTC timestamp of the most recent container removal.
        last_op_at:
          type: string
          format: date-time
          description: UTC timestamp of the most recent operation; drives retention TTL.
        created_at:
          type: string
          format: date-time
          description: UTC timestamp of the first observation of this game.
    RuntimesList:
      type: object
      additionalProperties: false
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeRecord"
    StartRequest:
      type: object
      additionalProperties: false
      required:
        - image_ref
      properties:
        image_ref:
          type: string
          description: Docker reference resolved by the producer (Game Master or Admin Service).
    StopRequest:
      type: object
      additionalProperties: false
      required:
        - reason
      properties:
        reason:
          $ref: "#/components/schemas/StopReason"
    PatchRequest:
      type: object
      additionalProperties: false
      required:
        - image_ref
      properties:
        image_ref:
          type: string
          description: New Docker reference within the same semver major and minor line.
    StopReason:
      type: string
      enum:
        - orphan_cleanup
        - cancelled
        - finished
        - admin_request
        - timeout
      description: Reason carried in the stop envelope and recorded in the operation log.
    ErrorCode:
      type: string
      enum:
        - invalid_request
        - not_found
        - conflict
        - service_unavailable
        - internal_error
        - image_pull_failed
        - image_ref_not_semver
        - semver_patch_only
        - container_start_failed
        - start_config_invalid
        - docker_unavailable
        - replay_no_op
      description: Stable internal API error code.
    ProbeResponse:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          type: string
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: "#/components/schemas/ErrorBody"
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        message:
          type: string
          description: Human-readable trusted error message.
  responses:
    InvalidRequestError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            invalidRequest:
              value:
                error:
                  code: invalid_request
                  message: request is invalid
    NotFoundError:
      description: The requested runtime record does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            notFound:
              value:
                error:
                  code: not_found
                  message: runtime record not found
    ConflictError:
      description: The requested operation is not allowed in the current runtime state.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            conflict:
              value:
                error:
                  code: conflict
                  message: operation not allowed in current status
    InternalError:
      description: Unexpected internal service error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            internal:
              value:
                error:
                  code: internal_error
                  message: internal server error
    ServiceUnavailableError:
      description: An upstream dependency is unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            unavailable:
              value:
                error:
                  code: service_unavailable
                  message: service is unavailable