Build a browser consumer

tutorialpreview

TL;DR

Use native EventSource with a valid stream token and an Arrow IPC reader to consume preview events in a browser. Close the connection on refresh-required or decode failure, and own your application’s snapshot strategy. The published boilstream-consumer 0.1.0 package is incompatible with the current opaque-cursor protocol.

Message sequenceSchema establishes the baseline; batches carry resumable cursors

Opening the stream is not a durable subscription. A new subscription starts from its captured baseline, not the entire table history.

Browser usage

Native EventSource requires no BoilStream SDK package. Supply a valid stream token for the topic. The server sends a schema event with an opaque baseline cursor before data, including when the subscription is idle.

const source = new EventSource("https://your-server:8443/stream/YOUR_TOKEN");

source.addEventListener("schema", (event) => {
  const cursor = event.lastEventId; // Preserve as a string.
  const ipcBytes = Uint8Array.from(atob(event.data), c => c.charCodeAt(0));
  // Decode ipcBytes with an Arrow IPC library to obtain the schema.
  console.log(`Schema received: ${ipcBytes.length} IPC bytes`);
});

source.addEventListener("batch", (event) => {
  const cursor = event.lastEventId; // Never convert to a number or compare ordering.
  const ipcBytes = Uint8Array.from(atob(event.data), c => c.charCodeAt(0));
  // Decode the complete IPC stream before processing this logical batch.
  // On decode failure, close source and refresh the application snapshot.
  console.log(`Batch received: ${ipcBytes.length} IPC bytes`);
});

source.addEventListener("refresh-required", () => {
  source.close();
  // Refresh application state through an authorized canonical table query.
  // Establish a new subscription according to the application's snapshot strategy.
});

source.onerror = () => {
  // Ordinary network failures trigger EventSource's automatic reconnect.
  // Renew an expired or revoked token through your application's auth flow.
};

// Call source.close() when the application no longer needs this subscription.

The example exposes Arrow IPC bytes; it does not decode Arrow or implement an application’s snapshot strategy. Use an Arrow IPC reader for both schema and batch payloads. One batch event can contain multiple Arrow record batches. If decoding fails, close the stream before reporting the failure: the browser may already have advanced its transport cursor, and blind reconnect could skip undecoded data.

Recovery

Follow the reconnect and refresh procedure. Close on decode failure: the browser may already have advanced its transport cursor.

SDK release status

The published boilstream-consumer version 0.1.0 is incompatible with the current opaque r1. cursor protocol. A compatible npm release is not available. Use native EventSource and an Arrow IPC reader until a compatible package is published.