admin343/run
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Relay current process output without spool

Browse Source
This commit is contained in:
npc0-hue
2026-08-31 23:35:14 +08:00
parent cde99e19fa
commit c8f5213954
9 changed files with 239 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files
protocol/log-ingest.md
+25 -14
View File
@@ -1,12 +1,18 @@
# Run Log Ingest Contract
# Run Live Log Relay Contract
Logs are durable historical data. They are not transported as best-effort UI messages.
Run log traffic is a best-effort push of output observed now. It is not a
durable log database, delivery queue, or acknowledgement-dependent lifecycle
channel. Game plugins own durable log storage and analysis.
## Implemented Routes
- `POST /api/v1/run/logs/batches`: uploads one bounded log batch and receives an acknowledgement range.
- `POST /api/v1/run/logs/relay`: pushes one bounded current-output batch to the
platform relay. The platform may forward it to live subscribers, but does
not persist the body or require a delivery acknowledgement.
- `POST /api/v1/log-streams/query`: queries stored log entries after a stream sequence cursor.
- `GET /api/v1/server-instances/{id}/logs/events`: browser-facing Server-Sent Events stream for replaying recent stored entries and pushing newly ingested platform log entries.
- `GET /api/v1/server-instances/{id}/logs/events`: browser-facing Server-Sent
Events stream for the current supervised process session. A new subscriber
starts at the live boundary and receives no platform log history.
## Payloads
@@ -17,20 +23,25 @@ Logs are durable historical data. They are not transported as best-effort UI mes
- `LogStreamCursorResponse`: ordered entries, next cursor, and latest acknowledged sequence.
- `LogStreamEventResponse`: safe browser event containing server ID, stream metadata, latest sequence, and one log entry.
Run-assigned Platform jobs use `job.<jobId>.<streamKey>` log stream IDs. Autonomous lifecycle bootstrap is not a Platform job, so it uses `run.<runEndpointId>.<serverInstanceId>.<streamKey>` and Platform creates the server-bound stream from the signed Run batch instead of looking for a job record.
## Local Spool
Run must write unacknowledged logs to a local spool/WAL before upload. Segments may be removed only after platform acknowledgement.
Autonomous lifecycle output uses
`run.<runEndpointId>.<serverInstanceId>.<logSessionId>.<streamKey>` stream IDs.
The platform creates or updates stream metadata from the signed relay batch;
the body remains live-only.
## Priority
Log flush has higher priority than artifact transfer. Artifact work must slow down when log spool pressure rises.
Live relay is asynchronous and lower priority than control and lifecycle
progress. A full in-memory relay queue or a failed relay request drops the
current event and never blocks, retries, or changes lifecycle state. Run does
not create a log spool, resend backlog, or platform delivery watermark.
Log spool retry state is independent from artifact/file retry state. Acknowledged log batches may be removed even when artifact chunks are still pending, and artifact chunk acknowledgement must not alter log sequence state. Log ingest payloads carry bounded entries only and must not include artifact chunks, file bodies, host paths, raw credentials, or direct socket details.
The Run uploader flushes committed spool segments independently with bounded request contexts. A failed or partial acknowledgement leaves the segment pending for restart/retry; control heartbeat and job lifecycle polling do not wait for log or artifact flushes.
Log relay payloads carry bounded redacted entries only and must not include
artifact chunks, file bodies, host paths, raw credentials, or direct socket
details.
## Browser Channel
Browser live tail is a platform-owned SSE fan-out from durable ingest and cursor state. External log storage backends and optional game client bridge traffic remain separate channels. Artifact transfer uses its own lower-priority channel and must not be multiplexed through log ingest.
Browser live tail is a platform SSE fan-out from current relay events and
process-session metadata. Historical log queries and plugin-owned storage are
separate channels. Artifact transfer uses its own lower-priority channel and
must not be multiplexed through live log relay.