Skip to content
BoilStream

Consume live events

conceptpreview
TL;DR

SSE delivers preview live output as base64-encoded Arrow IPC events over HTTP. Use a stream-purpose token and preserve event IDs as opaque strings. New subscriptions skip existing baseline rows. Reconnect catch-up is bounded; handle refresh-required by closing the stream and refreshing application state rather than retrying the same cursor.

Message sequenceSchema establishes the baseline; batches carry resumable cursors
Schema establishes the baseline; batches carry resumable cursorsA browser opens the token-scoped SSE endpoint. BoilStream sends a schema baseline and complete Arrow IPC batch events. The consumer retains the opaque cursor after processing a complete batch. Heartbeats carry no data acknowledgement.SSE consumerBoilStreamGET /stream/{token}HTTP 200: stream openedschema: baseline and Arrow schemabatch: Arrow IPC and opaque IDProcess complete batch; retain IDheartbeat: connection activityTime moves downward · dashed arrows are responsesSchema establishes the baseline; batches carry resumable cursorsA browser opens the token-scoped SSE endpoint. BoilStream sends a schema baseline and complete Arrow IPC batch events. The consumer retains the opaque cursor after processing a complete batch. Heartbeats carry no data acknowledgement.SSE consumerBoilStreamGET /stream/{token}HTTP 200: stream openedschema: baseline andArrow schemabatch: Arrow IPC andopaque IDProcess complete batch;retain IDheartbeat: connectionactivityTime moves downward · dashed arrows are responses
Opening the stream is not a durable subscription. A new subscription starts from its captured baseline, not the entire table history.

Authentication

Section titled “Authentication”

Tokens must have the stream purpose. The dashboard does not currently offer this purpose. After CLI authentication, create a token for your topic:

Shell
boilstream-admin --profile work token create --purpose stream --topic-id TOPIC_ID

Replace TOPIC_ID with the target topic’s numeric ID. The token-generation API also accepts purpose: "stream". See CLI authentication.

Tokens must remain valid while a stream is open. Expiry, revocation or a validation failure can close the connection. Data already sent cannot be recalled. Handle disconnection and obtain a fresh authorized token when needed. Keep tokens out of logs and shared URLs, and close the client when the subscription is no longer needed.

Build a consumer

Section titled “Build a consumer”

Use the browser guide for EventSource and Arrow decoding responsibilities. The published SDK is not compatible with the current cursor protocol; see its release status.

Read the contract

Section titled “Read the contract”
  • Events and errors — endpoint, payloads, status codes and terminal failures.
  • Recovery — reconnect, refresh and application responsibility.

A new subscription starts after its captured baseline and does not backfill the entire table. This preview is not a durable, gap-free changefeed.