first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,39 @@
|
||||
# AI Provider Contracts
|
||||
|
||||
AI providers are platform-managed model endpoints used by plugins through scoped platform capabilities.
|
||||
|
||||
## AIProviderConfig
|
||||
|
||||
- `id`: provider ID.
|
||||
- `name`: display name.
|
||||
- `kind`: provider kind.
|
||||
- `baseUrl`: base URL or relay URL.
|
||||
- `apiKeyRef`: secret reference.
|
||||
- `models`: allowed model list.
|
||||
- `defaultModel`: default model.
|
||||
- `relayMode`: direct, relay, or local.
|
||||
- `timeoutMs`: timeout.
|
||||
- `status`: active, disabled, or error.
|
||||
- `redactionPolicy`: redaction policy key.
|
||||
|
||||
## AIInvocationRequest
|
||||
|
||||
- `providerId`: selected provider.
|
||||
- `purpose`: scoped purpose such as `config.suggest` or `logs.diagnose`.
|
||||
- `serverInstanceId`: optional server context.
|
||||
- `pluginId`: caller plugin.
|
||||
- `inputRef`: artifact or bounded structured input.
|
||||
- `model`: optional model override.
|
||||
|
||||
AI invocation responses must be bounded and must not include raw provider credentials. Config write suggestions must be presented as a diff or recommendation before dispatching run jobs.
|
||||
|
||||
## Management API Contracts
|
||||
|
||||
- `AIProviderCreateRequest`: create provider metadata with `apiKeyRef`, never raw key material.
|
||||
- `AIProviderUpdateRequest`: replace editable provider metadata while preserving status through the service layer.
|
||||
- `AIProviderStatusRequest`: set provider status to `active` or `disabled`.
|
||||
- `AIProviderResponse`: redacted provider response with `apiKeyRef` only.
|
||||
- `AIProviderTestResponse`: local metadata validation result with `mode=metadata`; live external connectivity is deferred.
|
||||
- `AIProviderModelsResponse`: configured model list and default model, without credentials.
|
||||
|
||||
Management endpoints must reject raw key-shaped values in `apiKeyRef`. Platform-mediated AI invocation is implemented through the platform service boundary; live external connectivity tests and remote model discovery are deferred to later changes.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Run Protocol Contracts
|
||||
|
||||
The platform side of run communication is split into independent contracts.
|
||||
|
||||
## Control
|
||||
|
||||
Implemented HTTP JSON routes:
|
||||
|
||||
- `POST /api/v1/run/control/hello`
|
||||
- `POST /api/v1/run/control/heartbeat`
|
||||
|
||||
Named control DTOs:
|
||||
|
||||
- `RunHelloRequest`
|
||||
- `RunHelloResponse`
|
||||
- `RunHeartbeatRequest`
|
||||
- `RunHeartbeatResponse`
|
||||
- `RunCapabilityReport`
|
||||
- `RunCapacityReport`
|
||||
|
||||
Control payloads must remain small and must not include logs, artifact chunks, host paths, raw credentials, direct sockets, or long task results. Hello creates or updates run endpoint metadata and issues an in-memory platform session token. Heartbeat requires that active session token and may request capability refresh when the fingerprint changes.
|
||||
|
||||
Control is the highest-priority run/platform path. Artifact/file transfer load must not delay heartbeat acceptance or mutate heartbeat capacity state through heavy payload fields.
|
||||
|
||||
## Job
|
||||
|
||||
Implemented HTTP JSON routes:
|
||||
|
||||
- `POST /api/v1/run/jobs/claim`
|
||||
- `POST /api/v1/run/jobs/ack`
|
||||
- `POST /api/v1/run/jobs/progress`
|
||||
- `POST /api/v1/run/jobs/result`
|
||||
- `POST /api/v1/run/jobs/cancel`
|
||||
- `POST /api/v1/run/jobs/reconcile`
|
||||
|
||||
Named job DTOs:
|
||||
|
||||
- `RunJobClaimRequest`
|
||||
- `RunJobClaimResponse`
|
||||
- `RunJobAckRequest`
|
||||
- `RunJobProgressRequest`
|
||||
- `RunJobResultRequest`
|
||||
- `RunJobCancelPollRequest`
|
||||
- `RunJobReconcileRequest`
|
||||
- `RunJobReconcileResponse`
|
||||
|
||||
Jobs must carry bounded metadata such as `jobId`, `runEndpointId`, `serverInstanceId`, `capability`, `idempotencyKey`, lease token, attempt, progress, terminal state, message, error code, and result reference. Job payloads must not carry logs, artifact chunks, host paths, raw credentials, direct sockets, or large inline result bodies.
|
||||
|
||||
Job ack, progress, cancellation polling, reconciliation, and terminal result calls are lightweight lifecycle metadata. They must remain valid while artifact chunks or log retries are pending, and duplicate equivalent terminal results remain idempotent under channel pressure.
|
||||
|
||||
## Log Ingest
|
||||
|
||||
Implemented HTTP JSON routes:
|
||||
|
||||
- `POST /api/v1/run/logs/batches`
|
||||
- `POST /api/v1/log-streams/query`
|
||||
|
||||
Named log DTOs:
|
||||
|
||||
- `LogBatchIngestRequest`
|
||||
- `LogBatchIngestResponse`
|
||||
- `LogEntry`
|
||||
- `LogStreamCursorRequest`
|
||||
- `LogStreamCursorResponse`
|
||||
|
||||
Log ingest supports bounded batches, sequence ranges, checksum validation, retry-safe duplicate acknowledgement, latest sequence tracking, and cursor query. Log payloads must not carry artifact chunks, host paths, raw credentials, direct sockets, or unbounded inline data.
|
||||
|
||||
Log ingest is durable and independently retried. Artifact/file transfer backlog must not prevent log batch acknowledgement, duplicate acknowledgement, cursor state updates, or spool cleanup.
|
||||
|
||||
The platform stores log stream metadata through `repo.Store` and stores log bodies through the configured `LogBodyStore`. The default `file` backend persists platform metadata to `PLATFORM_METADATA_PATH` and appends log entries to segmented JSONL files under `PLATFORM_LOG_DIR`; the `memory` backend is only for tests and disposable local development. MySQL/Postgres are appropriate for platform metadata, stream state, retention policy, indexes, and audit records, but should not be the primary row-per-log-line store for hundreds or thousands of servers. Production log bodies should move behind the same boundary to append/query backends such as ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments with compact indexes.
|
||||
|
||||
## Artifact
|
||||
|
||||
Implemented HTTP JSON routes:
|
||||
|
||||
- `POST /api/v1/run/artifacts/open`
|
||||
- `POST /api/v1/run/artifacts/chunks`
|
||||
- `POST /api/v1/run/artifacts/status`
|
||||
- `POST /api/v1/run/artifacts/complete`
|
||||
|
||||
Named artifact DTOs:
|
||||
|
||||
- `ArtifactTransferOpenRequest`
|
||||
- `ArtifactTransferOpenResponse`
|
||||
- `ArtifactChunkUploadRequest`
|
||||
- `ArtifactChunkUploadResponse`
|
||||
- `ArtifactTransferStatusRequest`
|
||||
- `ArtifactTransferStatusResponse`
|
||||
- `ArtifactTransferCompleteRequest`
|
||||
- `ArtifactTransferCompleteResponse`
|
||||
- `ArtifactResponse`
|
||||
|
||||
Artifact upload supports active run session validation, job/server-instance owner scoping, bounded JSON chunk payloads, per-chunk checksum validation, duplicate chunk acknowledgement, resume status, and final checksum verification before an artifact becomes available. Artifact transport is separate from control, job result, log ingest, plugin bridge, and browser file APIs.
|
||||
|
||||
Artifact/file transfer is the lower-priority heavy channel. Chunk upload and completion must not block control heartbeat, job ack/result delivery, cancellation/reconcile calls, or log ingest acknowledgement. Lightweight routes must reject heavy transfer payloads instead of accepting or storing them.
|
||||
|
||||
## Game Client Bridge
|
||||
|
||||
The optional game client bridge is separate from run lifecycle, control registration, job handling, log ingest, and artifact transport.
|
||||
@@ -0,0 +1,77 @@
|
||||
# Server Plugin and Instance Lifecycle Contract
|
||||
|
||||
## Installed Server Plugin
|
||||
|
||||
An installed game management plugin is reusable. It defines a server type, but it is not a server instance.
|
||||
|
||||
The plugin marketplace API is a platform-facing projection over this installed registry metadata. It is not a package store, billing system, provider marketplace, or cloud host sales surface.
|
||||
|
||||
### States
|
||||
|
||||
- `installed`: plugin manifest and schemas are valid.
|
||||
- `disabled`: plugin cannot create new servers but existing instances remain inspectable.
|
||||
- `invalid`: plugin failed validation and cannot create or manage instances.
|
||||
- `updating`: plugin version is being changed.
|
||||
|
||||
## Server Instance
|
||||
|
||||
A server instance is created from one installed game management plugin and bound to one run endpoint.
|
||||
|
||||
### States
|
||||
|
||||
- `draft`: instance record exists but install job has not completed.
|
||||
- `installing`: run install job is active.
|
||||
- `ready`: install succeeded and the server can start.
|
||||
- `running`: server process is running.
|
||||
- `stopped`: server process is stopped.
|
||||
- `failed`: last lifecycle operation failed.
|
||||
- `deleted`: instance is no longer active.
|
||||
|
||||
## Invariants
|
||||
|
||||
- One `GamePlugin` installation may own many `ServerInstance` records.
|
||||
- A `ServerInstance` must keep its own config version, artifacts, jobs, log streams, and permissions.
|
||||
- Updating a plugin must not silently mutate existing server instances without a recorded reconcile job.
|
||||
- Deleting a plugin must be blocked or explicitly require handling existing server instances first.
|
||||
|
||||
## Lifecycle Actions
|
||||
|
||||
- `create`: validate plugin, create instance record, dispatch install job.
|
||||
- `start`: dispatch process start job through the bound run endpoint.
|
||||
- `stop`: dispatch process stop job through the bound run endpoint.
|
||||
- `restart`: dispatch stop/start or plugin-defined restart job.
|
||||
- `update`: dispatch server update job and record version/result.
|
||||
- `delete`: stop server when needed, preserve or remove artifacts according to policy, mark deleted.
|
||||
|
||||
## Implemented Workflow Routes
|
||||
|
||||
- `GET /api/v1/plugin-marketplace/plugins` lists plugin marketplace summaries from registry metadata with status, server type, capability, and keyword filters.
|
||||
- `GET /api/v1/plugin-marketplace/plugins/{id}` returns one registry-backed marketplace detail.
|
||||
- `POST /api/v1/plugin-marketplace/plugins/{id}/state` applies metadata-only `install`, `enable`, or `disable` state changes.
|
||||
- `POST /api/v1/server-instances/workflows/create` validates an installed plugin, a compatible run endpoint, a non-empty idempotency key, and required lifecycle action references. It creates the instance in `installing` state and queues a `process.install` job.
|
||||
- `POST /api/v1/server-instances/{id}/start` validates the instance is `ready` or `stopped`, checks the expected config version, verifies the plugin start action and run endpoint `process.start` capability, and queues a start job.
|
||||
- `POST /api/v1/server-instances/{id}/stop` validates the instance is `running`, checks the expected config version, verifies the plugin stop action and run endpoint `process.stop` capability, and queues a stop job.
|
||||
- `GET /api/v1/server-instances/{id}/config` returns logical read-only config content for an authorized server instance with config version, format, key, source, and update timestamp metadata.
|
||||
- `POST /api/v1/server-instances/{id}/config/diff` validates an authorized proposed config write against the current config version and returns a bounded platform diff without queuing work.
|
||||
- `POST /api/v1/server-instances/{id}/config/approve` revalidates an explicitly reviewed config diff and queues a scoped `config.write` job using a logical config key and input ref.
|
||||
- `POST /api/v1/file-operations/dispatch` queues scoped `files.read` or `files.write` jobs for logical server/plugin file keys after role and permission checks.
|
||||
- `GET /api/v1/metrics/server-instances` returns bounded per-server metrics for instances visible to the authenticated user.
|
||||
|
||||
Workflow route responses include the accepted action, bounded server instance metadata, and bounded job metadata. They do not expose run session tokens, host paths, raw credentials, direct sockets, AI provider keys, or plugin action file contents.
|
||||
|
||||
Config read and server metrics responses are also bounded and platform-mediated. They do not expose host filesystem paths, run sockets, raw credentials, direct storage backends, or AI provider keys.
|
||||
|
||||
Config write approval and file dispatch are platform-mediated. They carry logical keys such as `server.properties` or `logs/latest.log`, scoped refs such as `input://...` or `artifact://...`, and bounded job metadata only. They do not mutate local files in the platform process and do not expose raw host paths, run credentials, direct sockets, AI provider keys, or inline large payloads.
|
||||
|
||||
Marketplace state actions update only registry install state. They do not download packages, dispatch run jobs, execute plugin bridge code, write server files, expose package bytes, or contact external services. Package acquisition and runtime execution remain deferred to explicit future changes.
|
||||
|
||||
## Lifecycle Job Projection
|
||||
|
||||
Terminal run job results update the associated server instance when the job capability is a lifecycle capability:
|
||||
|
||||
- `process.install` + `succeeded` marks the instance `ready`.
|
||||
- `process.start` + `succeeded` marks the instance `running`.
|
||||
- `process.stop` + `succeeded` marks the instance `stopped`.
|
||||
- `process.install`, `process.start`, or `process.stop` + `failed` or `cancelled` marks the instance `failed`.
|
||||
|
||||
Active start and stop jobs do not introduce separate `starting` or `stopping` states in this change. Operators can inspect pending job state through the job list while the instance remains in its last terminal server state.
|
||||
Reference in New Issue
Block a user