first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -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.