147 lines
14 KiB
Markdown
147 lines
14 KiB
Markdown
# 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`
|
|
- `POST /api/v1/run/control/events`
|
|
|
|
Named control DTOs:
|
|
|
|
- `RunHelloRequest`
|
|
- `RunHelloResponse`
|
|
- `RunHeartbeatRequest`
|
|
- `RunHeartbeatResponse`
|
|
- `RunControlStreamRequest`
|
|
- `RunControlEvent`
|
|
- `RunCapabilityReport`
|
|
- `RunCapacityReport`
|
|
|
|
Control payloads must remain small and must not include logs, artifact chunks, host paths, raw credentials, direct sockets, job assignments, execution input, or long task results. Hello creates or updates run endpoint metadata and issues an in-memory platform session token. A server-scoped generated Run must use the endpoint identity reserved for its server; Platform rejects a valid component key presented for another endpoint. Registration is binding/authentication only for generated Run bootstrap and must not enqueue lifecycle or status jobs merely because Run appeared. Heartbeat requires that active session token and may request capability refresh when the fingerprint changes. The control event stream is a signed Run-only `text/event-stream` wake channel; events such as `job.changed` only tell Run to claim durable work through `/run/jobs/claim`.
|
|
|
|
Capacity reports include bounded `maxJobs`, `runningJobs`, `queuedJobs`, compatibility `logBacklogBatches`, `artifactBacklogChunks`, and enumerated pressure codes. Current Run implementations must not use `logBacklogBatches` as a durable live-log spool; capacity reports never include log bodies, artifact chunks, machine paths, PIDs, sockets, credentials, or transport endpoints.
|
|
|
|
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. Current Run workers use the persistent control event stream for wakeups and keep claim/ack/progress/result as the durable lease and execution channel; bounded claim long-poll remains a compatibility fallback for older workers.
|
|
|
|
Plugin lifecycle assignments may add only a validated plugin identifier, enumerated lifecycle operation, target version, and logical workspace scope. Explicit operator-requested install, enable, disable, upgrade, rollback, retire, dependency-check, and bounded lifecycle commands remain Platform-authorized jobs. Generated Run package startup is not dependent on registration-time job assignment; it is driven by the autonomous lifecycle plan embedded by the platform builder. Assignments cannot carry arbitrary shell, provider configuration, raw credentials, host paths, PIDs, sockets, DSNs, or RCON secrets.
|
|
|
|
Approved `config.write` and bounded `files.list`/`files.read`/`files.write` assignments carry logical directory keys, file keys, scoped refs, and compare-and-swap revision/checksum inputs. Run executes them inside its scoped workspace with atomic writes and returns bounded logical result metadata; resolved machine paths remain Run-local.
|
|
|
|
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.
|
|
|
|
## Generated Run autonomous lifecycle plan
|
|
|
|
Platform-owned Run distribution builds embed an autonomous lifecycle plan for the server-scoped generated Run. The plan carries the server/plugin identity, selected runtime profile, target OS/architecture/release, plugin lifecycle action refs, dependency probes/install plans, plugin-declared runtime log sources such as supervised process channels and file tails, optional DLL extension plans, runtime bindings, and redacted deployment inputs. The builder includes the same JSON as internal build input and as `.platform/autonomous-lifecycle-plan.json` in the generated workspace seed. Run reads this package-local plan on startup and performs plugin-declared init, dependency verification/install, install-if-needed, readiness/status, and start behavior locally before reporting observed state back to Platform.
|
|
|
|
The plan is build input for the generated package, not a machine-side job-channel payload. Generated Run registration must not be treated as a trigger to enqueue `process.start`, `process.install`, or `process.status` work; Platform state converges from Run heartbeats, logs, lifecycle reports, supervised process facts, and terminal job/report messages. Platform and Run must not add game-specific hardcoding to interpret the plan.
|
|
|
|
Autonomous lifecycle reports use `POST /api/v1/run/lifecycle/report` with the active Run session and signed envelope when required. The route accepts only bounded terminal lifecycle facts for `process.install`, `process.start`, `process.stop`, or `process.status`; it validates the server/run binding, records bounded evidence, and projects server state from Run-reported process facts without creating or completing a Platform job. A managed-process report includes an opaque `managedProcessId`, monotonic `observationSeq`, and `observedAt`; retries are idempotent and a lower sequence cannot regress a newer fact for that process.
|
|
|
|
## Live Log Relay And Compatibility Log Ingest
|
|
|
|
|
|
Implemented HTTP JSON routes:
|
|
|
|
- `POST /api/v1/run/logs/relay`
|
|
- `POST /api/v1/run/logs/batches`
|
|
- `GET /api/v1/server-instances/{id}/logs/events`
|
|
- `POST /api/v1/game-client-bridge/companion/logs/events`
|
|
- `POST /api/v1/log-streams/query`
|
|
|
|
Named log DTOs:
|
|
|
|
- `LogBatchIngestRequest`
|
|
- `LogBatchIngestResponse`
|
|
- `RunLogStreamProgressRequest` / `RunLogStreamProgressResponse`: compatibility signed Run-only cursor metadata for older durable-ingest streams. Current live relay does not depend on this route for delivery or progress.
|
|
- `LogEntry`
|
|
- `LogStreamCursorRequest`
|
|
- `LogStreamCursorResponse`
|
|
- `LogStreamEventResponse`
|
|
|
|
Current Run output uses `POST /api/v1/run/logs/relay`. The route validates the active Run session and stream binding, updates only bounded stream metadata such as latest sequence/session identity, and immediately fans entries out to live subscribers. It does not persist log bodies, does not create a resend backlog, does not require platform sequence acknowledgements for progress, and does not block lifecycle/control/job work on delivery success.
|
|
|
|
Server terminal streaming uses `GET /api/v1/server-instances/{id}/logs/events`; SCUM companion streaming uses `POST /api/v1/game-client-bridge/companion/logs/events` with the component session token in the typed JSON body. Both emit only the current supervised process session and do not replay retained platform log bodies. Platform is the live relay only. The game plugin/companion owns game-log storage, semantic analysis, and console-page fan-out behavior.
|
|
|
|
`POST /api/v1/run/logs/batches` and `POST /api/v1/log-streams/query` remain compatibility/internal maintenance contracts for older durable-ingest flows. New Run workers must not use durable local log spool/cache/resend semantics for current supervised stdout/stderr. Log payloads must not carry artifact chunks, host paths, raw credentials, direct sockets, or unbounded inline data.
|
|
|
|
The platform stores log stream metadata through `repo.Store`. Game-specific durable log bodies and derived semantic records belong to the owning game plugin; for SCUM that storage uses plugin-owned SQL tables and stores raw world coordinates without map projection or coordinate conversion.
|
|
|
|
## 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, live log relay, 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 current live log relay. Lightweight routes must reject heavy transfer payloads instead of accepting or storing them.
|
|
|
|
## Server File Manager Transfer
|
|
|
|
Implemented HTTP JSON routes:
|
|
|
|
- `POST /api/v1/run/files/input-chunk`
|
|
|
|
Browser-facing file management uses server-instance scoped routes on Platform for workspace, list, read, write, upload, and download preparation. The browser only sends plugin-declared logical directory keys, logical file keys, relative names, inline text for small edits, or platform-owned `artifact://` input refs. It never receives or sends host paths, direct Run sockets, Run sessions, job lease tokens, storage credentials, or raw machine endpoints.
|
|
|
|
`files.list` jobs return a bounded `file.list` execution result containing logical entries. `files.read` jobs may return a bounded inline `file.read` result for editable text or a `resultRef` pointing to a platform artifact for larger content. Browser downloads are prepared through Platform and then read in bounded chunks using the platform artifact download contract.
|
|
|
|
Browser uploads are first staged as server-instance artifacts. Platform then queues a `files.write` job whose `inputRef` is `artifact://<id>` and whose execution input names the dedicated `run-file-transfer` channel. Run pulls those bytes through `POST /api/v1/run/files/input-chunk` while proving the active endpoint session plus job attempt and lease. The chunk route is fenced to the active file-write job, validates artifact ownership/checksum, and returns bounded byte ranges only.
|
|
|
|
File-manager transfer is a separate, low-priority heavy path. Slow uploads, downloads, retries, or file input chunk pulls must not block control heartbeat, job claim/ack/progress/result/cancel/reconcile, current live log relay, or artifact upload acknowledgements. Control, jobs, logs, artifacts, file transfer, and optional game-client bridge remain independently backpressured channels.
|
|
|
|
## Client Manager lifecycle channel
|
|
|
|
Client Manager lifecycle jobs use the independent capabilities `client-manager.deploy`, `client-manager.control`, `client-manager.update`, `client-manager.rollback`, and `client-manager.uninstall`. Run obtains a fenced logical contract from `POST /api/v1/run/jobs/client-manager-input` and reads resumable artifact chunks from `POST /api/v1/run/jobs/client-manager-chunk`; these routes are separate from artifact upload, Run control, logs, and optional game-client traffic. The contract carries installation/profile, target, version/revision, checksum, deployment/key generations, fixed executable reference, bounded arguments/timeouts, and idempotency. For a plugin-declared companion profile it also carries a generic `companionConfig` materialization contract: safe relative template/schema/output references, the fenced component identity, declared component capabilities, Platform URL source, proof environment-variable name, component-session/TLS policy, and bounded timing values.
|
|
|
|
Run materializes the declared output such as `config.yaml` from the fenced values and its own configured Platform control URL. Source template values are not credentials and must not override the generated component identity or policy. The lifecycle input never contains the component proof itself, a component session, a browser credential, a host path, or a direct socket; proof remains inside the component package and is supplied to the supervised process only through the declared environment-variable name.
|
|
|
|
Run persists staging/active/previous slots and a local journal. It rejects stale lease/attempt/generation/target fences, traversal/link/device-file archives, checksum mismatches, undeclared executables, and arbitrary shell. Terminal results use `client-manager.deployed`, `client-manager.control`, `client-manager.updated`, `client-manager.rolled-back`, `client-manager.rollback.restored`, or `client-manager.uninstalled` with logical process/health state only. A stalled Client Manager download must not delay Run heartbeat, job ack/result/cancel, or current live log relay.
|
|
|
|
## Game Client Bridge
|
|
|
|
The optional game client bridge is separate from run lifecycle, control registration, job handling, compatibility log ingest, and artifact transport. A plugin companion may subscribe to the current live log relay through its component session so it can own game-log storage and analysis without requiring Platform to persist or interpret game log bodies.
|