Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

2.3 KB
Raw Blame

Custom transports

Client and NotebookClient send HTTP requests and read server-sent events. To follow events from an existing WebSocket, message channel, or another source, pass a Transport function to NotebookEvents or CatalogEvents.

The stream calls the transport once for each connection attempt. The transport receives a cursor and an abort signal. A null cursor requests a snapshot. Otherwise, the transport sends the cursor to the host to resume after that position.

Call open() when the connection is established. Call message(event) for each decoded protocol event, in order. Close the connection when the signal is aborted.

Resolve when the connection ends and another attempt makes sense. Reject when the stream should stop. The stream's closed promise rejects with the same error. Use StreamStopped to describe the failure. Calls to open() or message(event) after the promise settles are ignored.

The stream validates events, tracks the cursor, delivers events to subscribers, and reconnects. It delivers reset when an interrupted snapshot must be discarded. The host must also send reset when it cannot resume from the supplied cursor.

The transport sends any filters the host needs. The stream's types option filters delivered events locally. A notebook transport must apply runId itself. Each reconnect must use the same filters.

Build on server-sent events

sse is the transport a stream uses for a URL. Use it directly when a host serves the protocol's events with a URL that changes between connections or with frames of its own that end the stream.

import { NotebookEvents, StreamStopped, sse } from "@marimo-team/client";

const events = new NotebookEvents(
  sse(() => `${base}/events?session_id=${session()}`, {
    token,
    stop: (frame) =>
      frame.event === "close"
        ? new StreamStopped("The session closed")
        : undefined,
  }),
);

The URL function runs before each connection. A StreamStopped it throws stops the stream.

Set parseData to decode each frame's raw data with a custom parser. It runs before stop and event delivery. The default is JSON.parse; if the parser throws, the frame keeps its original text.

See the transport contract for the function and event types.