49 lines
2.5 KiB
Markdown
49 lines
2.5 KiB
Markdown
# Run Live Log Relay Contract
|
|
|
|
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/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 the current supervised process session. A new subscriber
|
|
starts at the live boundary and receives no platform log history.
|
|
|
|
## Payloads
|
|
|
|
- `LogBatchIngestRequest`: run ID, session token, server instance ID, stream ID, source, sequence range, compression metadata, checksum, and opaque entries.
|
|
- `LogEntry`: sequence, timestamp, level, opaque line, and parser metadata.
|
|
- `LogBatchIngestResponse`: accepted sequence range, latest stream metadata sequence, compatibility duplicate/retry fields, and server time.
|
|
- `LogStreamCursorRequest`: stream ID, sequence cursor, and limit.
|
|
- `LogStreamCursorResponse`: compatibility ordered entries, next cursor, and latest stored metadata sequence.
|
|
- `LogStreamEventResponse`: safe browser event containing server ID, stream metadata, latest sequence, and one log entry.
|
|
|
|
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
|
|
|
|
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 relay payloads preserve supervised stdout/stderr and plugin-declared file
|
|
tail text verbatim. Run does not inspect, filter, redact, or content-truncate
|
|
those payloads; the channel still must not carry artifact chunks or direct
|
|
socket APIs.
|
|
|
|
## Browser Channel
|
|
|
|
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.
|