Skip to content
SHC Docs

SSE streaming API

Server-Sent Events (text/event-stream) for real-time event and operation progress streaming.

Scope note. There is no SSEBroker subsystem and no sse.* 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 emit text/event-stream, verified against the chi routers.

MethodPathEmitsModule / source
GET/api/method/shc.events.streamevent stream (docker/audit/error)events
GET/api/method/shc.events.errors.streamerror events onlyevents
GET/api/method/shc.operation.stream/{operation_id}operation progressbackup (+ 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.streamchunked log streamlogs
GET/api/method/shc.storage.logs.streamchunked storage-op log streamstorage

All SSE responses set:

  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • Connection: keep-alive
  • X-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: heartbeat
data: {"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

ParameterDescription
typeComma-separated event types to include: docker, audit, error, event. Omit for all.
stack_nameFilter to one stack.
node_idFilter to events originating on one node.
all_tenants1 = 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).

  1. The client tracks the last id: received.
  2. On reconnect it sends Last-Event-Id: <seq> (or ?last_event_id=<seq> for clients that can’t set headers, e.g. browser EventSource).
  3. 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: reconnect
data: {}

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).

AnswerMeaning
{"delivered": true}Delivered to local subscribers.
{"delivered": false}Self-broadcast dropped.
X400000BADREQMissing source_hostname / decode error / missing code.
X500007EVTBUSEvent bus not running.