Stream live server logs over SSE

2026-08-03 22:28:54 +08:00
parent 5d4fca14f9
commit 7eac1926dd
48 changed files with 1526 additions and 263 deletions
@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Browser live logs use a platform push stream
+The Platform SHALL provide a server-scoped browser log event stream that sends safe log stream metadata and log entries over Server-Sent Events.
+
+#### Scenario: Operator opens live logs
+- **WHEN** an authorized operator opens a server log view or management terminal
+- **THEN** platform_web opens `GET /api/v1/server-instances/{id}/logs/events` with `EventSource`
+- **AND** the view does not start a periodic `/api/v1/log-streams/query` polling loop
+
+#### Scenario: Initial history is replayed
+- **WHEN** the browser opens the log event stream with a bounded `historyLimit`
+- **THEN** Platform replays recent stored entries for the server's log streams before sending the ready event
+- **AND** each event contains only safe stream metadata and log entry fields
+
+### Requirement: Durable Run log ingest remains independent
+Run-to-Platform log transfer SHALL remain durable HTTP batch ingest with local spool and sequence acknowledgement. Browser streaming MUST fan out only from platform-ingested log data.
+
+#### Scenario: Run uploads a batch
+- **WHEN** Run uploads a valid contiguous log batch
+- **THEN** Platform stores it, updates the stream latest sequence, acknowledges the batch, and publishes the new entries to matching browser subscribers
+- **AND** duplicate batch acknowledgements do not publish duplicate browser events
+
+### Requirement: Run live logs follow plugin-declared process channels
+Run live terminal output SHALL come from plugin-declared log sources and the supervised process that Run started. Game-specific file logs MUST NOT be used as the default live terminal source unless the plugin declares that file source for explicit history, fallback, or backfill.
+
+#### Scenario: Run starts a supervised process
+- **WHEN** Run executes a plugin lifecycle start action in supervised mode
+- **THEN** Run captures the process stdout and stderr into Run-owned durable capture files
+- **AND** Run tails those capture files into durable log batch ingest using the plugin-declared process stream keys
+- **AND** Run hides the managed Windows process window when the OS supports hidden startup
+
+#### Scenario: Run restarts while the game process remains alive
+- **WHEN** Run restarts and reloads its persisted process journal for an already-running supervised process
+- **THEN** Run resumes tailing the Run-owned stdout/stderr capture files from persisted offsets
+- **AND** Run does not inspect game-specific logs such as `SCUM.log` to synthesize terminal output
+
+### Requirement: Browser log streaming uses platform session authorization
+The log event stream SHALL be authorized by the current platform user session and server access rules. Plugins and browser code MUST NOT receive Run session tokens, component keys, host paths, raw credentials, or direct Run socket information.
+
+#### Scenario: Unauthorized user subscribes
+- **WHEN** a user without access opens a server log event stream
+- **THEN** Platform rejects the request using the existing authorization error behavior
+- **AND** no log entries or stream metadata are sent
+
+### Requirement: Reverse proxies forward log events without buffering
+The deployed platform_web reverse proxy SHALL forward the log event route without response buffering and with a long read timeout so idle log periods do not force browser polling.
+
+#### Scenario: Nginx proxies SSE
+- **WHEN** Nginx forwards `/api/v1/server-instances/{id}/logs/events`
+- **THEN** buffering is disabled for that location
+- **AND** the route does not require WebSocket upgrade headers