Ilia Denisov
1084 lines
36 KiB
YAML
1084 lines
36 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Galaxy Game Master Internal REST API
|
|
version: v1
|
|
description: |
|
|
This specification documents the internal trusted REST contract of
|
|
`galaxy/gamemaster` served on `GAMEMASTER_INTERNAL_HTTP_ADDR`
|
|
(default `:8097`).
|
|
|
|
This port is not reachable from the public internet. Callers are:
|
|
|
|
- `Edge Gateway` for verified player commands, orders, and reports.
|
|
- `Game Lobby` for runtime registration, image-ref resolution,
|
|
membership-cache invalidation, race banishment, and liveness
|
|
probes.
|
|
- `Admin Service` (future) for runtime control operations and the
|
|
engine version registry.
|
|
|
|
Transport rules:
|
|
|
|
- request bodies are strict JSON only; unknown fields are rejected
|
|
- error responses use `{ "error": { "code", "message" } }` matching
|
|
the envelope used by `galaxy/lobby` and `galaxy/rtmanager`
|
|
- timestamps are UTC Unix milliseconds (`integer, format: int64`)
|
|
- the listener is unauthenticated; downstream services rely on
|
|
network segmentation. The `X-User-ID` header is required only on
|
|
the three Edge Gateway hot-path operations
|
|
(`internalExecuteCommands`, `internalPutOrders`,
|
|
`internalGetReport`) and carries the verified player identity.
|
|
|
|
Schema closure:
|
|
|
|
- every body schema owned by `Game Master` sets
|
|
`additionalProperties: false`
|
|
- three operations forward engine-owned payloads verbatim
|
|
(`internalExecuteCommands`, `internalPutOrders`,
|
|
`internalGetReport`) and therefore use
|
|
`additionalProperties: true` on the corresponding request and
|
|
response bodies. The source of truth for those shapes is
|
|
`galaxy/game/openapi.yaml`.
|
|
- `EngineVersion.options` is a free-form `jsonb` document and uses
|
|
`additionalProperties: true` for the same reason.
|
|
servers:
|
|
- url: http://localhost:8097
|
|
description: Default local internal listener for Game Master.
|
|
tags:
|
|
- name: Probes
|
|
description: Health and readiness probes.
|
|
- name: Runtimes
|
|
description: Runtime control surface used by Admin Service.
|
|
- name: GMIntegration
|
|
description: Game Lobby integration paths under /api/v1/internal/games.
|
|
- name: EngineVersions
|
|
description: Engine version registry CRUD and image-ref resolve.
|
|
- name: Gateway
|
|
description: Edge Gateway hot-path commands, orders, and reports.
|
|
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
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
/readyz:
|
|
get:
|
|
tags:
|
|
- Probes
|
|
operationId: internalReadyz
|
|
summary: Internal listener readiness probe
|
|
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/games/{game_id}/register-runtime:
|
|
post:
|
|
tags:
|
|
- GMIntegration
|
|
operationId: internalRegisterRuntime
|
|
summary: Register a runtime after a successful container start
|
|
description: |
|
|
Called by `Game Lobby` after `Runtime Manager` has reported a
|
|
successful container start. Game Master persists the runtime
|
|
record, calls the engine `/api/v1/admin/init`, persists player
|
|
mappings derived from the engine response, and transitions the
|
|
runtime to `running`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RegisterRuntimeRequest"
|
|
responses:
|
|
"200":
|
|
description: Runtime registered and transitioned to `running`.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RuntimeRecord"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"404":
|
|
$ref: "#/components/responses/EngineVersionNotFoundError"
|
|
"409":
|
|
$ref: "#/components/responses/ConflictError"
|
|
"502":
|
|
$ref: "#/components/responses/EngineUnreachableError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
/api/v1/internal/games/{game_id}/race/{race_name}/banish:
|
|
post:
|
|
tags:
|
|
- GMIntegration
|
|
operationId: internalBanishRace
|
|
summary: Banish a race from the running engine after a permanent removal
|
|
description: |
|
|
Called by `Game Lobby` synchronously after a permanent
|
|
platform-level membership removal. Game Master forwards the call
|
|
to the engine `/api/v1/admin/race/banish` and records the
|
|
outcome in the operation log.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
- $ref: "#/components/parameters/RaceNamePath"
|
|
responses:
|
|
"204":
|
|
description: Race banished from the engine.
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"502":
|
|
$ref: "#/components/responses/EngineUnreachableError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/games/{game_id}/memberships/invalidate:
|
|
post:
|
|
tags:
|
|
- GMIntegration
|
|
operationId: internalInvalidateMemberships
|
|
summary: Invalidate the membership cache for a game
|
|
description: |
|
|
Called by `Game Lobby` post-commit on every roster mutation
|
|
(application approval, rejection, invite redeem, member remove,
|
|
member block, user-lifecycle cascade). Game Master purges the
|
|
in-process per-game membership cache; the TTL is the safety net
|
|
for missed calls.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
responses:
|
|
"204":
|
|
description: Membership cache entry invalidated.
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/games/{game_id}/liveness:
|
|
get:
|
|
tags:
|
|
- GMIntegration
|
|
operationId: internalGameLiveness
|
|
summary: Report whether a runtime is ready
|
|
description: |
|
|
Called by `Game Lobby` as part of the resume flow for a paused
|
|
game. Reflects Game Master's own runtime view; the engine is not
|
|
contacted by this endpoint.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
responses:
|
|
"200":
|
|
description: Liveness reply.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/LivenessResponse"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/runtimes:
|
|
get:
|
|
tags:
|
|
- Runtimes
|
|
operationId: internalListRuntimes
|
|
summary: List runtime records
|
|
description: |
|
|
Returns runtime records ordered by `created_at` descending. The
|
|
optional `status` query parameter narrows the result to runtimes
|
|
in the given runtime status.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RuntimeStatusQuery"
|
|
responses:
|
|
"200":
|
|
description: Page of runtime records.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RuntimeListResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/runtimes/{game_id}:
|
|
get:
|
|
tags:
|
|
- Runtimes
|
|
operationId: internalGetRuntime
|
|
summary: Read one runtime record
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
responses:
|
|
"200":
|
|
description: Runtime record.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RuntimeRecord"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/runtimes/{game_id}/force-next-turn:
|
|
post:
|
|
tags:
|
|
- Runtimes
|
|
operationId: internalForceNextTurn
|
|
summary: Force immediate generation of the next turn
|
|
description: |
|
|
Runs the turn-generation flow synchronously and sets
|
|
`skip_next_tick` so the next regular cron tick is consumed
|
|
without producing back-to-back turns.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
responses:
|
|
"200":
|
|
description: Turn generated; runtime record reflects the new turn number and scheduling state.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RuntimeRecord"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"409":
|
|
$ref: "#/components/responses/ConflictError"
|
|
"502":
|
|
$ref: "#/components/responses/EngineUnreachableError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/runtimes/{game_id}/stop:
|
|
post:
|
|
tags:
|
|
- Runtimes
|
|
operationId: internalStopRuntime
|
|
summary: Stop a runtime through Runtime Manager
|
|
description: |
|
|
Game Master forwards the request to `Runtime Manager` and CASes
|
|
the runtime status to `stopped` on success.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StopRuntimeRequest"
|
|
responses:
|
|
"200":
|
|
description: Runtime stopped.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RuntimeRecord"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
/api/v1/internal/runtimes/{game_id}/patch:
|
|
post:
|
|
tags:
|
|
- Runtimes
|
|
operationId: internalPatchRuntime
|
|
summary: Patch the engine version of a runtime through Runtime Manager
|
|
description: |
|
|
Resolves the new image reference from the engine version
|
|
registry, validates the target version is a semver-patch of the
|
|
currently running version, and forwards the patch call to
|
|
`Runtime Manager`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PatchRuntimeRequest"
|
|
responses:
|
|
"200":
|
|
description: Runtime patched; `current_engine_version` and `current_image_ref` updated.
|
|
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/engine-versions:
|
|
get:
|
|
tags:
|
|
- EngineVersions
|
|
operationId: internalListEngineVersions
|
|
summary: List engine versions
|
|
parameters:
|
|
- $ref: "#/components/parameters/EngineVersionStatusQuery"
|
|
responses:
|
|
"200":
|
|
description: Engine version registry contents.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/EngineVersionListResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
post:
|
|
tags:
|
|
- EngineVersions
|
|
operationId: internalCreateEngineVersion
|
|
summary: Create a new engine version record
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreateEngineVersionRequest"
|
|
responses:
|
|
"201":
|
|
description: Engine version created.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/EngineVersion"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"409":
|
|
$ref: "#/components/responses/ConflictError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/engine-versions/{version}:
|
|
get:
|
|
tags:
|
|
- EngineVersions
|
|
operationId: internalGetEngineVersion
|
|
summary: Read one engine version record
|
|
parameters:
|
|
- $ref: "#/components/parameters/VersionPath"
|
|
responses:
|
|
"200":
|
|
description: Engine version record.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/EngineVersion"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
patch:
|
|
tags:
|
|
- EngineVersions
|
|
operationId: internalUpdateEngineVersion
|
|
summary: Patch an engine version record
|
|
parameters:
|
|
- $ref: "#/components/parameters/VersionPath"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UpdateEngineVersionRequest"
|
|
responses:
|
|
"200":
|
|
description: Engine version updated.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/EngineVersion"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
delete:
|
|
tags:
|
|
- EngineVersions
|
|
operationId: internalDeprecateEngineVersion
|
|
summary: Deprecate an engine version
|
|
description: |
|
|
Sets the engine version status to `deprecated`. Hard removal of
|
|
a version that is referenced by a non-finished runtime is
|
|
rejected with `engine_version_in_use`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/VersionPath"
|
|
responses:
|
|
"204":
|
|
description: Engine version deprecated.
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"409":
|
|
$ref: "#/components/responses/EngineVersionInUseError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/engine-versions/{version}/image-ref:
|
|
get:
|
|
tags:
|
|
- EngineVersions
|
|
operationId: internalResolveEngineVersionImageRef
|
|
summary: Resolve the image reference of an engine version
|
|
description: |
|
|
Hot path used by `Game Lobby` synchronously before publishing
|
|
a `runtime:start_jobs` envelope. Returns the `image_ref` only.
|
|
parameters:
|
|
- $ref: "#/components/parameters/VersionPath"
|
|
responses:
|
|
"200":
|
|
description: Image reference of the requested version.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ImageRefResponse"
|
|
"404":
|
|
$ref: "#/components/responses/EngineVersionNotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/games/{game_id}/commands:
|
|
post:
|
|
tags:
|
|
- Gateway
|
|
operationId: internalExecuteCommands
|
|
summary: Execute a batch of player commands
|
|
description: |
|
|
Edge Gateway hot path for `game.command.execute`. Game Master
|
|
authorises the user, resolves `actor=race_name` from its own
|
|
player mappings, and forwards the request to the engine
|
|
`/api/v1/command`. The request and response bodies are
|
|
engine-owned and pass through unchanged
|
|
(`additionalProperties: true`).
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
- $ref: "#/components/parameters/XUserIDHeader"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ExecuteCommandsRequest"
|
|
responses:
|
|
"200":
|
|
description: Engine response forwarded verbatim.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ExecuteCommandsResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"403":
|
|
$ref: "#/components/responses/ForbiddenError"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"409":
|
|
$ref: "#/components/responses/ConflictError"
|
|
"502":
|
|
$ref: "#/components/responses/EngineUnreachableError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/games/{game_id}/orders:
|
|
post:
|
|
tags:
|
|
- Gateway
|
|
operationId: internalPutOrders
|
|
summary: Submit a batch of player orders
|
|
description: |
|
|
Edge Gateway hot path for `game.order.put`. Same authorisation
|
|
and forwarding semantics as `internalExecuteCommands`; the
|
|
engine endpoint is `/api/v1/order`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
- $ref: "#/components/parameters/XUserIDHeader"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PutOrdersRequest"
|
|
responses:
|
|
"200":
|
|
description: Engine response forwarded verbatim.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PutOrdersResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"403":
|
|
$ref: "#/components/responses/ForbiddenError"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"409":
|
|
$ref: "#/components/responses/ConflictError"
|
|
"502":
|
|
$ref: "#/components/responses/EngineUnreachableError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/api/v1/internal/games/{game_id}/reports/{turn}:
|
|
get:
|
|
tags:
|
|
- Gateway
|
|
operationId: internalGetReport
|
|
summary: Read a per-player turn report
|
|
description: |
|
|
Edge Gateway hot path for `game.report.get`. Game Master
|
|
authorises the user and forwards
|
|
`GET /api/v1/report?player={race_name}&turn={turn}` to the
|
|
engine. The response body is engine-owned and pass-through.
|
|
parameters:
|
|
- $ref: "#/components/parameters/GameIDPath"
|
|
- $ref: "#/components/parameters/TurnPath"
|
|
- $ref: "#/components/parameters/XUserIDHeader"
|
|
responses:
|
|
"200":
|
|
description: Engine response forwarded verbatim.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ReportResponse"
|
|
"403":
|
|
$ref: "#/components/responses/ForbiddenError"
|
|
"404":
|
|
$ref: "#/components/responses/NotFoundError"
|
|
"502":
|
|
$ref: "#/components/responses/EngineUnreachableError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
components:
|
|
parameters:
|
|
GameIDPath:
|
|
name: game_id
|
|
in: path
|
|
required: true
|
|
description: Opaque stable game identifier owned by Game Lobby.
|
|
schema:
|
|
type: string
|
|
VersionPath:
|
|
name: version
|
|
in: path
|
|
required: true
|
|
description: Semver string of an engine version registered with Game Master.
|
|
schema:
|
|
type: string
|
|
RaceNamePath:
|
|
name: race_name
|
|
in: path
|
|
required: true
|
|
description: Race name registered for a player in the running game.
|
|
schema:
|
|
type: string
|
|
TurnPath:
|
|
name: turn
|
|
in: path
|
|
required: true
|
|
description: Turn number for which the per-player report is fetched.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
XUserIDHeader:
|
|
name: X-User-ID
|
|
in: header
|
|
required: true
|
|
description: Verified player identity propagated by Edge Gateway. Trusted as authoritative.
|
|
schema:
|
|
type: string
|
|
RuntimeStatusQuery:
|
|
name: status
|
|
in: query
|
|
required: false
|
|
description: Optional filter; when set, only runtimes in the given runtime status are returned.
|
|
schema:
|
|
$ref: "#/components/schemas/RuntimeStatus"
|
|
EngineVersionStatusQuery:
|
|
name: status
|
|
in: query
|
|
required: false
|
|
description: Optional filter; when set, only engine versions in the given status are returned.
|
|
schema:
|
|
$ref: "#/components/schemas/EngineVersionStatus"
|
|
schemas:
|
|
RuntimeStatus:
|
|
type: string
|
|
enum:
|
|
- starting
|
|
- running
|
|
- generation_in_progress
|
|
- generation_failed
|
|
- stopped
|
|
- engine_unreachable
|
|
- finished
|
|
description: Current runtime status of a registered game.
|
|
EngineVersionStatus:
|
|
type: string
|
|
enum:
|
|
- active
|
|
- deprecated
|
|
description: Engine version registry status.
|
|
StopReason:
|
|
type: string
|
|
enum:
|
|
- admin_request
|
|
- finished
|
|
- timeout
|
|
description: Reason argument passed to Runtime Manager when stopping a runtime.
|
|
ProbeResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- status
|
|
properties:
|
|
status:
|
|
type: string
|
|
description: Probe outcome string (`ok` or `ready`).
|
|
LivenessResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- ready
|
|
- status
|
|
properties:
|
|
ready:
|
|
type: boolean
|
|
description: True when the runtime is in `running`; false otherwise.
|
|
status:
|
|
$ref: "#/components/schemas/RuntimeStatus"
|
|
ImageRefResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- image_ref
|
|
properties:
|
|
image_ref:
|
|
type: string
|
|
description: Docker reference of the engine image registered for the requested version.
|
|
RegisterRuntimeMember:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- user_id
|
|
- race_name
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
description: Platform user identifier of an active member.
|
|
race_name:
|
|
type: string
|
|
description: Race name reserved for the member in this game.
|
|
RegisterRuntimeRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- engine_endpoint
|
|
- members
|
|
- target_engine_version
|
|
- turn_schedule
|
|
properties:
|
|
engine_endpoint:
|
|
type: string
|
|
description: Engine container DNS endpoint, e.g. http://galaxy-game-{game_id}:8080.
|
|
members:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: "#/components/schemas/RegisterRuntimeMember"
|
|
description: Members included in the engine init roster.
|
|
target_engine_version:
|
|
type: string
|
|
description: Semver of the engine version under which the container was started.
|
|
turn_schedule:
|
|
type: string
|
|
description: Five-field cron expression copied from the platform game record.
|
|
RuntimeRecord:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- game_id
|
|
- runtime_status
|
|
- engine_endpoint
|
|
- current_image_ref
|
|
- current_engine_version
|
|
- turn_schedule
|
|
- current_turn
|
|
- next_generation_at
|
|
- skip_next_tick
|
|
- engine_health_summary
|
|
- created_at
|
|
- updated_at
|
|
properties:
|
|
game_id:
|
|
type: string
|
|
description: Opaque stable game identifier; primary key.
|
|
runtime_status:
|
|
$ref: "#/components/schemas/RuntimeStatus"
|
|
engine_endpoint:
|
|
type: string
|
|
description: Engine container DNS endpoint observed at register-runtime time.
|
|
current_image_ref:
|
|
type: string
|
|
description: Docker reference of the running image.
|
|
current_engine_version:
|
|
type: string
|
|
description: Semver of the running engine version.
|
|
turn_schedule:
|
|
type: string
|
|
description: Five-field cron expression governing the scheduler ticker.
|
|
current_turn:
|
|
type: integer
|
|
minimum: 0
|
|
description: Last completed turn number; zero until the first turn generates.
|
|
next_generation_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds of the next scheduled tick.
|
|
skip_next_tick:
|
|
type: boolean
|
|
description: True when force-next-turn has set the skip flag for the next regular tick.
|
|
engine_health_summary:
|
|
type: string
|
|
description: Short text summary derived from runtime:health_events; empty until the first health observation.
|
|
created_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds; record creation timestamp.
|
|
updated_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds; last mutation timestamp.
|
|
started_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds; set when status first becomes running. Optional.
|
|
stopped_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds; set when status becomes stopped. Optional.
|
|
finished_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds; set when status becomes finished. Optional.
|
|
RuntimeListResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- runtimes
|
|
properties:
|
|
runtimes:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RuntimeRecord"
|
|
StopRuntimeRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- reason
|
|
properties:
|
|
reason:
|
|
$ref: "#/components/schemas/StopReason"
|
|
PatchRuntimeRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- version
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: Target engine version; must be a semver-patch of the running version.
|
|
EngineVersion:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- version
|
|
- image_ref
|
|
- options
|
|
- status
|
|
- created_at
|
|
- updated_at
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: Semver string; primary key in the registry.
|
|
image_ref:
|
|
type: string
|
|
description: Non-empty Docker reference of the engine image.
|
|
options:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Free-form jsonb document of engine-side options. Pass-through; Game Master does not enforce a schema.
|
|
status:
|
|
$ref: "#/components/schemas/EngineVersionStatus"
|
|
created_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds; record creation timestamp.
|
|
updated_at:
|
|
type: integer
|
|
format: int64
|
|
description: UTC Unix milliseconds; last mutation timestamp.
|
|
EngineVersionListResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- versions
|
|
properties:
|
|
versions:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/EngineVersion"
|
|
CreateEngineVersionRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- version
|
|
- image_ref
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: Semver string of the new version.
|
|
image_ref:
|
|
type: string
|
|
description: Non-empty Docker reference of the engine image.
|
|
options:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Optional engine-side options document. Free-form jsonb.
|
|
UpdateEngineVersionRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
description: PATCH body. Every field is optional; at least one must be present.
|
|
properties:
|
|
image_ref:
|
|
type: string
|
|
description: New Docker reference for the version.
|
|
options:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Replacement options document.
|
|
status:
|
|
$ref: "#/components/schemas/EngineVersionStatus"
|
|
ExecuteCommandsRequest:
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- commands
|
|
description: |
|
|
Player command batch carried inside `commands`. Game Master rewrites
|
|
the envelope before forwarding to the engine `/api/v1/command`: the
|
|
`commands` array is renamed to `cmd` and a top-level `actor` field
|
|
is set to the caller's race name resolved from `player_mappings`.
|
|
Caller-supplied envelope fields other than `commands` are dropped;
|
|
Game Master never trusts a caller-supplied `actor` per
|
|
`gamemaster/README.md` §Hot Path.
|
|
properties:
|
|
commands:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: true
|
|
ExecuteCommandsResponse:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Engine-owned shape; the response from the engine /api/v1/command endpoint, returned to Edge Gateway unchanged.
|
|
PutOrdersRequest:
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- commands
|
|
description: |
|
|
Player order batch carried inside `commands`. Same envelope-rewrite
|
|
semantics as `ExecuteCommandsRequest`: Game Master renames
|
|
`commands` to `cmd` and sets `actor` from the caller identity
|
|
before forwarding to the engine `/api/v1/order`.
|
|
properties:
|
|
commands:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: true
|
|
PutOrdersResponse:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Engine-owned shape; the response from the engine /api/v1/order endpoint, returned to Edge Gateway unchanged.
|
|
ReportResponse:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Engine-owned shape; the response from the engine /api/v1/report endpoint, returned to Edge Gateway unchanged.
|
|
ErrorResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- error
|
|
properties:
|
|
error:
|
|
$ref: "#/components/schemas/ErrorBody"
|
|
ErrorBody:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: Stable internal API error code.
|
|
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
|
|
ForbiddenError:
|
|
description: Caller is not an active member of the game or is otherwise not authorised.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
forbidden:
|
|
value:
|
|
error:
|
|
code: forbidden
|
|
message: caller is not authorised for this operation
|
|
NotFoundError:
|
|
description: The requested runtime, race, or engine version does not exist.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
runtimeNotFound:
|
|
value:
|
|
error:
|
|
code: runtime_not_found
|
|
message: runtime not found
|
|
EngineVersionNotFoundError:
|
|
description: The requested engine version is missing or has been deprecated.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
engineVersionNotFound:
|
|
value:
|
|
error:
|
|
code: engine_version_not_found
|
|
message: engine version not found
|
|
EngineVersionInUseError:
|
|
description: Hard delete attempt against a version referenced by a non-finished runtime.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
engineVersionInUse:
|
|
value:
|
|
error:
|
|
code: engine_version_in_use
|
|
message: engine version is referenced by a non-finished runtime
|
|
ConflictError:
|
|
description: The requested state transition is not allowed from the current status.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
conflict:
|
|
value:
|
|
error:
|
|
code: conflict
|
|
message: operation not allowed in current status
|
|
runtimeNotRunning:
|
|
value:
|
|
error:
|
|
code: runtime_not_running
|
|
message: operation requires runtime status running
|
|
semverPatchOnly:
|
|
value:
|
|
error:
|
|
code: semver_patch_only
|
|
message: patch attempt across major or minor boundary
|
|
EngineUnreachableError:
|
|
description: The engine container returned 5xx or could not be reached.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
engineUnreachable:
|
|
value:
|
|
error:
|
|
code: engine_unreachable
|
|
message: engine container is unreachable
|
|
engineProtocolViolation:
|
|
value:
|
|
error:
|
|
code: engine_protocol_violation
|
|
message: engine response missing required fields or malformed
|
|
engineValidationError:
|
|
value:
|
|
error:
|
|
code: engine_validation_error
|
|
message: engine rejected one or more commands
|
|
ServiceUnavailableError:
|
|
description: An upstream dependency (PostgreSQL, Redis, Lobby, RTM) is unavailable.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
unavailable:
|
|
value:
|
|
error:
|
|
code: service_unavailable
|
|
message: service is unavailable
|
|
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
|