131 lines
6.1 KiB
Markdown
131 lines
6.1 KiB
Markdown
# Platform Domain Resources
|
|
|
|
This file defines the first platform resource contracts. Concrete Go domain structs are implemented in `platform/domain/resources.go`; API DTO projections live in `platform/dto/resources.go`; database model projections live in `platform/model/resources.go`. Do not define these resource shapes inside handlers or service functions.
|
|
|
|
## Implemented Boundaries
|
|
|
|
- Domain constants centralize allowed status, state, provider kind, relay mode, artifact owner, storage backend, and audit result values.
|
|
- DTO responses expose `apiKeyRef` for AI providers but never raw key material.
|
|
- Model structs include JSON/database tags and explicit `TableName()` mappings for future persistence work.
|
|
- `platform/repo.NewFileStore` provides durable local metadata snapshots for platform startup, while `platform/repo.NewMemoryStore` provides deterministic in-memory repository behavior for unit tests and disposable local runs.
|
|
- Log stream metadata records the selected body backend. The current durable local body backend uses `local-segments`; future production adapters should target log-optimized stores such as `clickhouse`, `loki`, `opensearch`, or `elasticsearch` rather than row-per-line relational tables.
|
|
- `platform/service.Core` enforces create/list/get workflows and cross-resource invariants before resources are persisted.
|
|
|
|
## User
|
|
|
|
- `id`: stable user ID.
|
|
- `displayName`: visible user name.
|
|
- `email`: optional login email.
|
|
- `status`: `active`, `disabled`, or `pending`.
|
|
- `roles`: role keys assigned to the user.
|
|
- `createdAt`: creation time.
|
|
- `updatedAt`: last update time.
|
|
|
|
## AIProvider
|
|
|
|
- `id`: stable provider ID.
|
|
- `name`: display name.
|
|
- `kind`: `openai-compatible`, `openai`, `claude`, `gemini`, `ollama`, or `custom`.
|
|
- `baseUrl`: provider or relay base URL.
|
|
- `apiKeyRef`: secret reference, never the raw key.
|
|
- `models`: allowed model IDs.
|
|
- `defaultModel`: optional default model.
|
|
- `relayMode`: `direct`, `relay`, or `local`.
|
|
- `timeoutMs`: request timeout.
|
|
- `status`: `active`, `disabled`, or `error`.
|
|
- `redactionPolicy`: policy key for prompt/input/output redaction.
|
|
|
|
## GamePlugin
|
|
|
|
- `id`: plugin ID such as `game.example`.
|
|
- `name`: display name.
|
|
- `description`: bounded marketplace/registry summary.
|
|
- `version`: installed version.
|
|
- `serverType`: game/server type key.
|
|
- `serverDisplayName`: visible server type name.
|
|
- `supportedOs`: operating systems declared by the plugin manifest.
|
|
- `manifestRef`: immutable manifest artifact reference.
|
|
- `createFormSchemaRef`: create form schema reference.
|
|
- `requiredRunCapabilities`: run capabilities required by this plugin.
|
|
- `declaredPermissions`: scoped manifest permission keys used by plugin bridge and marketplace views.
|
|
- `permissions`: aggregate platform ability declarations for AI, logs, files, jobs, and artifacts.
|
|
- `lifecycleActions`: manifest action contract references for install/start/stop and optional restart/status.
|
|
- `pages`: plugin-local page metadata with scoped permission requirements.
|
|
- `tags`: bounded catalog tags.
|
|
- `aiPurposes`: platform-mediated AI purposes such as config suggestions or log diagnosis.
|
|
- `validationViolations`: safe validation findings for invalid plugin records.
|
|
- `status`: `installed`, `disabled`, `invalid`, or `updating`.
|
|
|
|
Manifest registration uses `GamePluginManifestRegistrationRequest` at `POST /api/v1/game-plugins/register-manifest`. Platform validation repeats plugin workspace safety checks and rejects raw host paths, direct run sockets, raw credentials, and raw AI/provider keys before metadata reaches the registry.
|
|
|
|
## ServerInstance
|
|
|
|
- `id`: server instance ID.
|
|
- `pluginId`: installed game management plugin ID.
|
|
- `pluginVersion`: plugin version used to create or last reconcile the instance.
|
|
- `runEndpointId`: selected run endpoint.
|
|
- `name`: server display name.
|
|
- `state`: `draft`, `installing`, `ready`, `running`, `stopped`, `failed`, or `deleted`.
|
|
- `configVersion`: optimistic concurrency version for platform-managed config.
|
|
- `createdAt`: creation time.
|
|
- `updatedAt`: last update time.
|
|
|
|
## RunEndpoint
|
|
|
|
- `id`: run endpoint ID.
|
|
- `displayName`: visible executor name.
|
|
- `version`: run binary version.
|
|
- `status`: `online`, `offline`, `degraded`, or `disabled`.
|
|
- `capabilities`: current capability keys.
|
|
- `capacity`: current queue and resource summary.
|
|
- `lastHeartbeatAt`: last control heartbeat time.
|
|
|
|
## Job
|
|
|
|
- `id`: job ID.
|
|
- `serverInstanceId`: optional target server.
|
|
- `runEndpointId`: target run endpoint.
|
|
- `capability`: requested capability key.
|
|
- `idempotencyKey`: duplicate detection key.
|
|
- `state`: `queued`, `accepted`, `running`, `succeeded`, `failed`, or `cancelled`.
|
|
- `progress`: bounded progress summary.
|
|
- `resultRef`: optional terminal result reference.
|
|
|
|
Lifecycle workflow jobs use fixed capabilities:
|
|
|
|
- `process.install`: dispatched by server create workflow and projects successful terminal results to `ready`.
|
|
- `process.start`: dispatched by server start workflow and projects successful terminal results to `running`.
|
|
- `process.stop`: dispatched by server stop workflow and projects successful terminal results to `stopped`.
|
|
|
|
Failed or cancelled lifecycle jobs project the server instance to `failed`. Active start/stop jobs are visible through job metadata; this change does not add separate `starting` or `stopping` server states.
|
|
|
|
## Artifact
|
|
|
|
- `id`: artifact ID.
|
|
- `ownerKind`: `platform`, `plugin`, `server-instance`, or `job`.
|
|
- `ownerId`: owning resource ID.
|
|
- `sizeBytes`: expected or final size.
|
|
- `checksum`: final checksum.
|
|
- `state`: `uploading`, `available`, `expired`, or `failed`.
|
|
|
|
## LogStream
|
|
|
|
- `id`: log stream ID.
|
|
- `serverInstanceId`: target server.
|
|
- `source`: `process`, `file`, `plugin`, or custom source.
|
|
- `streamKey`: stable stream key.
|
|
- `latestSeq`: latest accepted sequence.
|
|
- `storageBackend`: `local-segments`, `loki`, `clickhouse`, `opensearch`, or `elasticsearch`.
|
|
- `retentionPolicy`: retention key.
|
|
|
|
## AuditEvent
|
|
|
|
- `id`: audit event ID.
|
|
- `actorId`: user or system actor.
|
|
- `action`: stable action key.
|
|
- `resourceKind`: resource kind.
|
|
- `resourceId`: resource ID.
|
|
- `result`: `success`, `denied`, `failed`, or `queued`.
|
|
- `summary`: bounded redacted summary.
|
|
- `createdAt`: event time.
|