SSE streaming API
Server-Sent Events (text/event-stream) for real-time event and operation
progress streaming.
Scope note. There is no
SSEBrokersubsystem and nosse.*config section in the Go daemon; those were Python-era. Streaming is implemented directly in the module routers below. This page documents the routes that actually emittext/event-stream, verified against the chi routers.
Streaming endpoints
Section titled “Streaming endpoints”| Method | Path | Emits | Module / source |
|---|---|---|---|
GET | /api/method/shc.events.stream | event stream (docker/audit/error) | events |
GET | /api/method/shc.events.errors.stream | error events only | events |
GET | /api/method/shc.operation.stream/{operation_id} | operation progress | backup (+ operation) |
GET | /api/method/shc.operation.state/{operation_id} | one-shot operation state (JSON, not SSE) | backup |
GET | /api/method/shc.mount.subscribe/{session_id} | mount-session events (pins the session) | backup/mount |
GET | /api/method/shc.stack.logs.stream | chunked log stream | logs |
GET | /api/method/shc.storage.logs.stream | chunked storage-op log stream | storage |
SSE wire format
Section titled “SSE wire format”All SSE responses set:
Content-Type: text/event-streamCache-Control: no-cacheConnection: keep-aliveX-Accel-Buffering: no
Each frame is:
id: <sequence>event: <event_type>data: <json>id: is emitted only when the sequence is known (locally published events).
A heartbeat frame is sent every 30 seconds during idle periods:
event: heartbeatdata: {"ts": "2026-01-24T12:00:00.123456Z"}Event stream: GET /api/method/shc.events.stream
Section titled “Event stream: GET /api/method/shc.events.stream”Streams system-wide events. Auth: events:read (tenant-scoped); a
non-member is rejected with 403 before any SSE headers are written. The
local UDS caller is implicitly all-tenants.
Query parameters
| Parameter | Description |
|---|---|
type | Comma-separated event types to include: docker, audit, error, event. Omit for all. |
stack_name | Filter to one stack. |
node_id | Filter to events originating on one node. |
all_tenants | 1 = all tenants (platform admin only). |
Event type classification (from the event code prefix): D… → docker,
A… → audit, E… → error; audit/error flags override; anything else →
event. Each data payload is the event’s ToDict() envelope plus an
event_type key.
GET /api/method/shc.events.errors.stream is the same stream restricted to
error events.
Operation progress: GET /api/method/shc.operation.stream/{operation_id}
Section titled “Operation progress: GET /api/method/shc.operation.stream/{operation_id}”Async operations (shc.backup.create_async, restore_async,
recover_async, stack start/stop/restart, install/update, …) return an
operation_id in their response body. Subscribe to this route to receive
progress frames. Event types seen on this channel include step
(progress update), complete, and error; the stream closes after a
complete or error frame.
The backup-module handler serves the canonical URL; it tries the async
operations store first, then falls back to the operation module’s
registry, so operations registered by either land on the same URL.
GET /api/method/shc.operation.state/{operation_id} returns a one-shot JSON
snapshot of operation state (used by the CLI to check whether an operation
still exists before following it).
Reconnection
Section titled “Reconnection”- The client tracks the last
id:received. - On reconnect it sends
Last-Event-Id: <seq>(or?last_event_id=<seq>for clients that can’t set headers, e.g. browserEventSource). - The server replays events after that sequence from
event(up to a 1000-event window) before resuming the live stream. Beyond the window the client resyncs by re-querying current state.
When shcd restarts it ends every open stream with one last frame:
event: reconnectdata: {}The listening sockets stay open across the restart, so a client that
reconnects at once waits in the kernel and the next shcd answers it.
shc events --follow and the CLI’s operation follow reconnect with
Last-Event-Id for up to two minutes. The event stream resumes where it
left off. An operation’s progress lives only in the daemon that ran it,
so after a restart its stream answers 404.
Cross-node ingest: the events.deliver RPC function
Section titled “Cross-node ingest: the events.deliver RPC function”Peer nodes forward events to each other with the events.deliver internal
RPC function (POST /internal/rpc/events.deliver, internal listener only).
The event argument is one event in ToDict() shape as a JSON string; code
is required and source_hostname must be present. Events whose source equals the
receiving node are dropped (loop prevention). Received events are delivered to
local subscribers. They are not persisted again and not re-broadcast
(prevents storms).
| Answer | Meaning |
|---|---|
{"delivered": true} | Delivered to local subscribers. |
{"delivered": false} | Self-broadcast dropped. |
X400000BADREQ | Missing source_hostname / decode error / missing code. |
X500007EVTBUS | Event bus not running. |