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.

Follow the editor's notebook stream with `NotebookEvents` (#11413)

Trevor Manzb0cac46962ac
diff --git a/frontend/src/core/host/__tests__/notebook-client.test.ts b/frontend/src/core/host/__tests__/notebook-client.test.ts
index f76ebe9850..d226ba5cb4 100644
--- a/frontend/src/core/host/__tests__/notebook-client.test.ts
+++ b/frontend/src/core/host/__tests__/notebook-client.test.ts
@@ -1,42 +1,42 @@
/* Copyright 2026 Marimo. All rights reserved. */
// @vitest-environment jsdom
-import { describe, expect, it, vi } from "vitest";
+import { type NotebookTransport, StreamStopped } from "@marimo-team/client";
import { createStore } from "jotai";
-import { ConnectionState } from "../../websocket/types";
+import { afterEach, describe, expect, it, vi } from "vitest";
import { Deferred } from "@/utils/Deferred";
-import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
-import { classifyCloseEvent } from "../../websocket/connection-state";
+import { ConnectionState } from "../../websocket/types";
+import type { ConnectionStatus } from "../connection";
import { createNotebookClient } from "../notebook-client";
import { fixtureEvents, fixtureMessages } from "./fixtures";
-function notebookMessage(id: string) {
- const notebook = {
- id,
- project_id: "p1",
- path: null,
- name: id,
- operations: [],
- updated_at: null,
- };
- return JSON.stringify({ event: "notebook", data: { notebook } });
+/** One connection the fake transport opened. */
+interface Attempt {
+ readonly cursor: string | null;
+ readonly signal: AbortSignal;
+ open(): void;
+ receive(message: unknown): void;
+ /** End the connection so the stream reconnects. */
+ drop(): void;
+ /** End the stream, with the status the editor shows if the transport has one. */
+ stop(status?: ConnectionStatus): void;
}
-function setup(url: () => string = () => "ws://localhost/ws") {
- const events = new EventTarget();
- const healthy = new Deferred<void>();
- let provider = url;
- const urls: URL[] = [];
- const transport = {
- readyState: WebSocket.CLOSED,
- reconnect: vi.fn(() => {
- urls.push(new URL(provider()));
- }),
- close: vi.fn(() => events.dispatchEvent(new CloseEvent("close"))),
- send: vi.fn(),
- addEventListener: events.addEventListener.bind(events),
- removeEventListener: events.removeEventListener.bind(events),
- };
+function setup() {
+ const attempts: Attempt[] = [];
+ const transport: NotebookTransport = ({ cursor, signal }, handlers) =>
+ new Promise((resolve, reject) => {
+ attempts.push({
+ cursor,
+ signal,
+ open: handlers.open,
+ receive: handlers.message,
+ drop: resolve,
+ stop: (status) =>
+ reject(new StreamStopped("stopped", { cause: status })),
+ });
+ signal.addEventListener("abort", () => resolve(), { once: true });
+ });
const onNotification = vi.fn();
const checkHealth = vi.fn(async () => true);
const store = createStore();
@@ -44,51 +44,64 @@ function setup(url: () => string = () => "ws://localhost/ws") {
const client = controller.client;
const connect = (signal: AbortSignal) =>
controller.connect({
- createTransport: (next) => {
- provider = next;
- return transport;
- },
- url,
+ transport,
signal,
- waitUntilReady: () => healthy.promise,
checkHealth,
onNotification: (notification) => onNotification({ data: notification }),
- decodeJson: jsonParseWithSpecialChar,
- classifyClose: classifyCloseEvent,
});
+ let next = 0;
+ /** Wait for the next connection, and open it. */
+ const opened = async () => {
+ await vi.waitFor(() => expect(attempts.length).toBeGreaterThan(next));
+ const attempt = attempts[next++];
+ attempt.open();
+ return attempt;
+ };
return {
- events,
- healthy,
- transport,
+ attempts,
client,
connect,
onNotification,
store,
checkHealth,
- urls,
- receive: (message: unknown) =>
- events.dispatchEvent(
- new MessageEvent("message", { data: JSON.stringify(message) }),
- ),
+ opened,
};
}
+const lifetimes: AbortController[] = [];
+function lifetime() {
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ return controller;
+}
+
+afterEach(() => {
+ lifetimes.splice(0).forEach((controller) => controller.abort());
+ vi.useRealTimers();
+});
+
+/** Wait out the stream's backoff before it reconnects. */
+const backoff = () => vi.advanceTimersByTimeAsync(2000);
+
+const kernelReady = {
+ event: "marimo",
+ data: { marimo: { op: "kernel-ready", resumed: false } },
+};
+
+const notebook = {
+ id: "nb/with space",
+ project_id: "p1",
+ path: null,
+ name: "Notebook",
+ operations: ["notebook.edit"],
+ updated_at: null,
+};
+
describe("NotebookClient lifetime", () => {
it("exposes identity and capabilities only after the notebook is ready", async () => {
- const { connect, healthy, events, receive, client, store } = setup();
- const lifetime = new AbortController();
- connect(lifetime.signal);
- healthy.resolve();
- await healthy.promise;
- events.dispatchEvent(new Event("open"));
- const notebook = {
- id: "nb/with space",
- project_id: "p1",
- path: null,
- name: "Notebook",
- operations: ["notebook.edit"],
- updated_at: null,
- };
+ const { connect, opened, client, store } = setup();
+ connect(lifetime().signal);
+ const { receive } = await opened();
receive({ event: "notebook", data: { notebook } });
expect(store.get(client.notebookAtom)).toBeNull();
receive({ event: "ready", id: "1", data: {} });
@@ -101,396 +114,401 @@ describe("NotebookClient lifetime", () => {
expect(store.get(client.notebookAtom)?.operations).toEqual([]);
receive({ event: "notebook.removed", id: "3", data: { id: notebook.id } });
expect(store.get(client.notebookAtom)).toBeNull();
- lifetime.abort();
});
it("rebuilds the replica after a reconnect reset selects a new notebook", async () => {
- const notebookId = "n2";
- const { connect, events, healthy, urls, receive, client, store } = setup(
- () => "ws://localhost/ws?session_id=visitor",
- );
- const lifetime = new AbortController();
- connect(lifetime.signal);
- healthy.resolve();
- await healthy.promise;
- events.dispatchEvent(new Event("open"));
- fixtureMessages("notebook-events.sse").forEach(receive);
+ vi.useFakeTimers();
+ const { connect, opened, client, store } = setup();
+ connect(lifetime().signal);
+ const first = await opened();
+ fixtureMessages("notebook-events.sse").forEach(first.receive);
expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n1");
- events.dispatchEvent(new CloseEvent("close"));
- expect(urls.at(-1)?.searchParams.get("cursor")).toBe("97");
+ first.drop();
+ await backoff();
expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n1");
expect(store.get(client.notebookAtom)).toBeNull();
- events.dispatchEvent(new Event("open"));
- receive({ event: "reset", data: {} });
+ const second = await opened();
+ expect(second.cursor).toBe("97");
+ second.receive({ event: "reset", data: {} });
expect(store.get(client.documentAtom)).toBeNull();
for (const event of fixtureMessages("notebook-events.sse")) {
- receive(
- JSON.parse(
- JSON.stringify(event).replaceAll('"n1"', JSON.stringify(notebookId)),
- ),
+ second.receive(
+ JSON.parse(JSON.stringify(event).replaceAll('"n1"', '"n2"')),
);
}
- expect(store.get(client.documentAtom)?.revision.notebook_id).toBe(
- notebookId,
- );
+ expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n2");
expect(store.get(client.connectionAtom).state).toBe(ConnectionState.OPEN);
- expect(store.get(client.notebookAtom)?.id).toBe(notebookId);
- lifetime.abort();
+ expect(store.get(client.notebookAtom)?.id).toBe("n2");
});
- it.each(["{broken", JSON.stringify({ event: "ready", data: {} })])(
- "stops consuming a malformed host stream: %s",
- (data) => {
- const { connect, events, client, store, transport, onNotification } =
- setup();
- const lifetime = new AbortController();
- connect(lifetime.signal);
- events.dispatchEvent(new Event("open"));
- events.dispatchEvent(new MessageEvent("message", { data }));
- events.dispatchEvent(
- new MessageEvent("message", {
- data: JSON.stringify({
- event: "marimo",
- data: { marimo: { op: "reconnected" } },
- }),
- }),
- );
- expect(store.get(client.connectionAtom)).toEqual({
- state: ConnectionState.CLOSED,
- code: "KERNEL_DISCONNECTED",
- reason: "Failed to decode notebook message",
+ it.each([
+ ["a message that is not an event", "{broken"],
+ ["an event from another notebook", "identity"],
+ ])("stops consuming a stream on %s", async (_name, message) => {
+ const { connect, opened, client, store, onNotification } = setup();
+ connect(lifetime().signal);
+ const attempt = await opened();
+ if (message === "identity") {
+ attempt.receive({ event: "notebook", data: { notebook } });
+ attempt.receive({
+ event: "notebook",
+ data: { notebook: { ...notebook, id: "n2" } },
});
- expect(transport.close).toHaveBeenCalledOnce();
- expect(onNotification).not.toHaveBeenCalled();
- lifetime.abort();
- },
- );
-
- it("resumes from the last cursor until reset or a new session", async () => {
- const session = { id: "first", token: "a" };
- const { connect, events, healthy, urls, receive } = setup(
- () =>
- `ws://localhost/ws?session_id=${session.id}&access_token=${session.token}&cursor=999`,
- );
- const lifetime = new AbortController();
- connect(lifetime.signal);
- healthy.resolve();
- await healthy.promise;
- expect(urls[0].searchParams.get("cursor")).toBeNull();
-
- const snapshot = fixtureMessages("notebook-events.sse");
- events.dispatchEvent(new Event("open"));
- for (const message of snapshot) {
- receive(message);
+ } else {
+ attempt.receive(message);
}
- session.token = "b";
- events.dispatchEvent(new CloseEvent("close"));
- expect(urls[1].searchParams.get("cursor")).toBe("97");
- expect(urls[1].searchParams.get("access_token")).toBe("b");
-
- events.dispatchEvent(new Event("open"));
- receive({ event: "reset", data: {} });
- events.dispatchEvent(new CloseEvent("close"));
- expect(urls[2].searchParams.get("cursor")).toBeNull();
-
- events.dispatchEvent(new Event("open"));
- for (const message of snapshot) {
- receive(message);
- }
- session.id = "second";
- events.dispatchEvent(new CloseEvent("close"));
- expect(urls[3].searchParams.get("cursor")).toBeNull();
- expect(urls[3].searchParams.get("session_id")).toBe("second");
- lifetime.abort();
+ attempt.receive({
+ event: "marimo",
+ data: { marimo: { op: "reconnected" } },
+ });
+ await vi.waitFor(() =>
+ expect(store.get(client.connectionAtom).state).toBe(
+ ConnectionState.CLOSED,
+ ),
+ );
+ expect(store.get(client.connectionAtom)).toMatchInlineSnapshot(`
+ {
+ "code": "KERNEL_DISCONNECTED",
+ "reason": "Failed to decode notebook message",
+ "state": "CLOSED",
+ }
+ `);
+ expect(attempt.signal.aborted).toBe(true);
+ expect(onNotification).not.toHaveBeenCalled();
});
it("exposes the confirmed document until the lifetime ends", async () => {
- const { connect, events, client, store, healthy, receive } = setup();
- const lifetime = new AbortController();
- connect(lifetime.signal);
- healthy.resolve();
- await healthy.promise;
- events.dispatchEvent(new Event("open"));
+ vi.useFakeTimers();
+ const { connect, opened, client, store } = setup();
+ const current = lifetime();
+ connect(current.signal);
+ const attempt = await opened();
const snapshot = fixtureMessages("notebook-events.sse");
- for (const message of snapshot.slice(0, -3)) {
- receive(message);
- }
+ snapshot.slice(0, -3).forEach(attempt.receive);
expect(store.get(client.documentAtom)).toBeNull();
- for (const message of snapshot.slice(-3)) {
- receive(message);
- }
+ snapshot.slice(-3).forEach(attempt.receive);
expect(store.get(client.documentAtom)?.revision.order).toEqual([
"c1",
"c3",
"k7f2",
]);
- events.dispatchEvent(new CloseEvent("close"));
+ attempt.drop();
+ await backoff();
expect(store.get(client.documentAtom)?.revision.order).toEqual([
"c1",
"c3",
"k7f2",
]);
- lifetime.abort();
+ current.abort();
expect(store.get(client.documentAtom)).toBeNull();
});
- it("stops consuming a stream whose notebook changes", () => {
- const { connect, events, client, store, transport } = setup();
- const lifetime = new AbortController();
- connect(lifetime.signal);
- events.dispatchEvent(new Event("open"));
- for (const id of ["n1", "n2"]) {
- events.dispatchEvent(
- new MessageEvent("message", { data: notebookMessage(id) }),
- );
- }
- expect(store.get(client.connectionAtom)).toEqual({
- state: ConnectionState.CLOSED,
- code: "KERNEL_DISCONNECTED",
- reason: "Failed to decode notebook message",
- });
- expect(transport.close).toHaveBeenCalledOnce();
- lifetime.abort();
- });
+ it.each([
+ ["a malformed native envelope", { event: "marimo", id: "98", data: {} }],
+ ["null native event data", { event: "marimo", id: "98", data: null }],
+ ["an invalid protocol record", { event: "cell", id: "98", data: {} }],
+ ["an undecodable message", "{broken"],
+ ["a changed notebook", { event: "notebook", id: "98", data: { notebook } }],
+ ])(
+ "rebuilds from a fresh snapshot after rejecting %s",
+ async (_name, message) => {
+ const { connect, opened, client, store, onNotification } = setup();
+ connect(lifetime().signal);
+ const first = await opened();
+ const snapshot = fixtureMessages("notebook-events.sse");
+ snapshot.forEach(first.receive);
+ expect(store.get(client.documentAtom)).not.toBeNull();
+ onNotification.mockClear();
- it.each(["MARIMO_UNAUTHORIZED", "MARIMO_TRANSPORT_EXHAUSTED"])(
- "stops automatic recovery after %s but permits an explicit reconnect",
- async (reason) => {
- const {
- connect,
- client,
- store,
- events,
- transport,
- healthy,
- checkHealth,
- } = setup();
- const lifetime = new AbortController();
- connect(lifetime.signal);
- healthy.resolve();
- await healthy.promise;
- events.dispatchEvent(new CloseEvent("close", { reason }));
- events.dispatchEvent(new Event("error"));
- expect(store.get(client.connectionAtom).state).toBe(
- ConnectionState.CLOSED,
+ first.receive(message);
+ first.receive(kernelReady);
+ expect({
+ connection: store.get(client.connectionAtom),
+ document: store.get(client.documentAtom),
+ attachments: store.get(client.attachmentsAtom),
+ aborted: first.signal.aborted,
+ notifications: onNotification.mock.calls,
+ }).toEqual({
+ connection: {
+ state: ConnectionState.CLOSED,
+ code: "KERNEL_DISCONNECTED",
+ reason: "Failed to decode notebook message",
+ },
+ document: null,
+ attachments: [],
+ aborted: true,
+ notifications: [],
+ });
+
+ await client.reconnect();
+ const second = await opened();
+ expect(second.cursor).toBeNull();
+ snapshot.forEach(second.receive);
+ expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n1");
+ expect(store.get(client.connectionAtom)).toEqual({
+ state: ConnectionState.OPEN,
+ });
+ },
+ );
+
+ it.each([
+ [
+ "a final close",
+ {
+ state: ConnectionState.CLOSED,
+ code: "KERNEL_DISCONNECTED",
+ reason: "not authorized",
+ },
+ ],
+ ["the host giving up", undefined],
+ ] as const)(
+ "shows the stop after %s and resumes on an explicit reconnect",
+ async (_name, status) => {
+ const { connect, opened, attempts, client, store, checkHealth } = setup();
+ connect(lifetime().signal);
+ const first = await opened();
+ first.receive({ event: "ready", id: "5", data: {} });
+ first.stop(status);
+ await vi.waitFor(() =>
+ expect(store.get(client.connectionAtom)).toEqual(
+ status ?? {
+ state: ConnectionState.CLOSED,
+ code: "KERNEL_DISCONNECTED",
+ reason: "kernel not found",
+ },
+ ),
);
- expect(transport.reconnect).toHaveBeenCalledOnce();
+ expect(attempts).toHaveLength(1);
await client.reconnect();
expect(checkHealth).toHaveBeenCalledOnce();
- expect(transport.reconnect).toHaveBeenCalledTimes(2);
- lifetime.abort();
+ expect((await opened()).cursor).toBe("5");
},
);
- it("only resets the automatic retry budget after an open event", () => {
- const { connect, events, transport } = setup();
- const lifetime = new AbortController();
- connect(lifetime.signal);
- events.dispatchEvent(new CloseEvent("close"));
- events.dispatchEvent(new Event("error"));
- events.dispatchEvent(new CloseEvent("close"));
- expect(transport.reconnect).toHaveBeenCalledOnce();
- events.dispatchEvent(new Event("open"));
- events.dispatchEvent(new CloseEvent("close"));
- expect(transport.reconnect).toHaveBeenCalledTimes(2);
- lifetime.abort();
- });
-
it("does not revive an aborted lifetime when a manual health check finishes", async () => {
- const { connect, client, transport, checkHealth } = setup();
+ const { connect, opened, attempts, client, checkHealth } = setup();
const health = new Deferred<boolean>();
checkHealth.mockReturnValue(health.promise);
- const lifetime = new AbortController();
- connect(lifetime.signal);
+ const current = lifetime();
+ connect(current.signal);
+ const first = await opened();
+ first.stop({
+ state: ConnectionState.CLOSED,
+ code: "KERNEL_DISCONNECTED",
+ reason: "",
+ });
+ await vi.waitFor(() => expect(checkHealth).not.toHaveBeenCalled());
const attempt = client.reconnect();
- lifetime.abort();
+ current.abort();
health.resolve(true);
await attempt;
- expect(transport.reconnect).not.toHaveBeenCalled();
+ expect(attempts).toHaveLength(1);
});
- it("does not connect after abort, even when the health check finishes", async () => {
- const { client, connect, healthy, transport } = setup();
- const controller = new AbortController();
- connect(controller.signal);
- controller.abort();
- healthy.resolve();
- await healthy.promise;
- client.reconnect();
- expect(transport.reconnect).not.toHaveBeenCalled();
- expect(transport.close).toHaveBeenCalledOnce();
+ it("discards an interrupted snapshot before a manual reconnect", async () => {
+ const { connect, opened, client, store } = setup();
+ connect(lifetime().signal);
+ const first = await opened();
+ const snapshot = fixtureEvents("notebook-events.sse");
+ for (const event of snapshot) {
+ if (event.event === "ready") {
+ break;
+ }
+ first.receive(event);
+ }
+ first.stop();
+ await vi.waitFor(() =>
+ expect(store.get(client.connectionAtom).state).toBe(
+ ConnectionState.CLOSED,
+ ),
+ );
+
+ await client.reconnect();
+ const second = await opened();
+ expect(second.cursor).toBeNull();
+ for (const event of snapshot) {
+ if (event.event === "notebook") {
+ second.receive(event);
+ }
+ if (event.event === "document") {
+ second.receive({
+ ...event,
+ data: { document: { ...event.data.document, order: [] } },
+ });
+ }
+ }
+ second.receive({ event: "ready", id: "100", data: {} });
+ expect({
+ connection: store.get(client.connectionAtom),
+ order: store.get(client.documentAtom)?.revision.order,
+ attachments: store.get(client.attachmentsAtom),
+ }).toEqual({
+ connection: { state: ConnectionState.OPEN },
+ order: [],
+ attachments: [],
+ });
});
- it("detaches listeners before closing so cleanup cannot trigger a session retry", () => {
- const { connect, client, store, events, transport, onNotification } =
- setup();
- const controller = new AbortController();
- connect(controller.signal);
- controller.abort();
- events.dispatchEvent(
- new MessageEvent("message", {
- data: JSON.stringify({ data: { op: "reconnected" } }),
- }),
- );
- expect(transport.reconnect).not.toHaveBeenCalled();
+ it("does not connect after abort", async () => {
+ const { connect, attempts, client, store } = setup();
+ const current = lifetime();
+ connect(current.signal);
+ current.abort();
+ await client.reconnect();
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ expect(attempts).toHaveLength(0);
expect(store.get(client.connectionAtom)).toEqual({
state: ConnectionState.NOT_STARTED,
});
- expect(onNotification).not.toHaveBeenCalled();
});
- it("can reconnect after effect cleanup without reviving the earlier client attempt", async () => {
- const { connect, healthy, transport, events, onNotification } = setup();
- const first = new AbortController();
+ it("forwards notifications for the current lifetime only", async () => {
+ const { connect, opened, onNotification } = setup();
+ const first = lifetime();
connect(first.signal);
+ const earlier = await opened();
first.abort();
- const second = new AbortController();
- connect(second.signal);
- healthy.resolve();
- await healthy.promise;
- expect(transport.reconnect).toHaveBeenCalledOnce();
- events.dispatchEvent(
- new MessageEvent("message", {
- data: JSON.stringify({
- event: "marimo",
- data: { marimo: { op: "reconnected" } },
- }),
- }),
- );
+ connect(lifetime().signal);
+ const current = await opened();
+ earlier.receive(kernelReady);
+ current.receive({
+ event: "marimo",
+ data: { marimo: { op: "reconnected" } },
+ });
expect(onNotification).toHaveBeenCalledExactlyOnceWith({
data: { op: "reconnected" },
});
- second.abort();
});
});
-async function open() {
- const url = vi.fn(() => "ws://localhost/ws?session_id=first&cursor=999");
- const setupResult = setup(url);
- const lifetime = new AbortController();
- setupResult.connect(lifetime.signal);
- setupResult.healthy.resolve();
- await setupResult.healthy.promise;
- setupResult.events.dispatchEvent(new Event("open"));
- return { ...setupResult, lifetime, url };
-}
-
describe("NotebookClient attachments", () => {
const [browser, agent] = fixtureEvents("notebook-events.sse").flatMap(
(event) => (event.event === "attachment" ? [event.data.attachment] : []),
);
+ async function open() {
+ const result = setup();
+ result.connect(lifetime().signal);
+ return { ...result, attempt: await result.opened() };
+ }
+
it("publishes a complete snapshot and applies live changes independently of kernel readiness", async () => {
- const { client, store, receive, lifetime } = await open();
+ const { client, store, attempt } = await open();
const snapshot = fixtureMessages("notebook-events.sse");
const readyIndex = snapshot.findIndex((event) => event.event === "ready");
- snapshot.slice(0, readyIndex).forEach(receive);
+ snapshot.slice(0, readyIndex).forEach(attempt.receive);
expect(store.get(client.attachmentsAtom)).toEqual([]);
- snapshot.slice(readyIndex).forEach(receive);
+ snapshot.slice(readyIndex).forEach(attempt.receive);
expect(store.get(client.attachmentsAtom)).toEqual([browser, agent]);
const renamed = { ...agent, name: "Renamed agent" };
- receive({ event: "attachment", id: "98", data: { attachment: renamed } });
- receive({
+ attempt.receive({
+ event: "attachment",
+ id: "98",
+ data: { attachment: renamed },
+ });
+ attempt.receive({
event: "attachment.removed",
id: "99",
data: { id: browser.id },
});
expect(store.get(client.attachmentsAtom)).toEqual([renamed]);
- receive({ data: { op: "kernel-ready", resumed: false } });
+ attempt.receive(kernelReady);
expect(store.get(client.attachmentsAtom)).toEqual([renamed]);
- receive({ event: "attachment.removed", id: "100", data: { id: agent.id } });
- expect(store.get(client.attachmentsAtom)).toEqual([]);
- lifetime.abort();
- });
-
- it("resumes attachments alongside an incomplete document and waits for replay ready", async () => {
- const { client, store, receive, events, urls, lifetime } = await open();
- expect(urls[0].searchParams.has("cursor")).toBe(false);
- fixtureMessages("notebook-events.sse").forEach(receive);
- const confirmed = store.get(client.documentAtom);
- const edits = fixtureMessages("edits.sse");
- edits.slice(0, 3).forEach(receive);
- const renamed = { ...agent, name: "Renamed agent" };
- receive({ event: "attachment", id: "112a", data: { attachment: renamed } });
- expect(store.get(client.attachmentsAtom)).toEqual([browser, renamed]);
- events.dispatchEvent(new CloseEvent("close"));
- expect(store.get(client.attachmentsAtom)).toEqual([]);
- expect(urls.at(-1)!.searchParams.get("cursor")).toBe("112a");
- events.dispatchEvent(new Event("open"));
- expect(store.get(client.attachmentsAtom)).toEqual([]);
- expect(store.get(client.documentAtom)).toBe(confirmed);
- edits.slice(3).forEach(receive);
- receive({
+ attempt.receive({
event: "attachment.removed",
- id: "115",
- data: { id: browser.id },
+ id: "100",
+ data: { id: agent.id },
});
expect(store.get(client.attachmentsAtom)).toEqual([]);
- receive({ event: "ready", id: "116", data: {} });
- expect(store.get(client.attachmentsAtom)).toEqual([renamed]);
- const revisions = fixtureEvents("edits.sse").flatMap((event) =>
- event.event === "document" ? [event.data.document] : [],
- );
- expect(store.get(client.documentAtom)?.revision).toEqual(revisions.at(-1));
- lifetime.abort();
});
- it("replaces stale attachments with an empty snapshot after reset", async () => {
- const { client, store, receive, lifetime } = await open();
- fixtureMessages("notebook-events.sse").forEach(receive);
- receive({ event: "reset", data: {} });
- expect(store.get(client.attachmentsAtom)).toEqual([]);
- fixtureMessages("notebook-events.sse")
- .filter((event) => event.event !== "attachment")
- .forEach(receive);
- expect(store.get(client.attachmentsAtom)).toEqual([]);
- lifetime.abort();
- });
+ it.each(["automatic", "manual"])(
+ "preserves an incomplete live document across %s reconnect and waits for replay ready",
+ async (recovery) => {
+ vi.useFakeTimers();
+ const { client, store, attempt, opened } = await open();
+ expect(attempt.cursor).toBeNull();
+ fixtureMessages("notebook-events.sse").forEach(attempt.receive);
+ const confirmed = store.get(client.documentAtom);
+ const edits = fixtureMessages("edits.sse");
+ edits.slice(0, 3).forEach(attempt.receive);
+ const renamed = { ...agent, name: "Renamed agent" };
+ attempt.receive({
+ event: "attachment",
+ id: "112a",
+ data: { attachment: renamed },
+ });
+ expect(store.get(client.attachmentsAtom)).toEqual([browser, renamed]);
+ if (recovery === "automatic") {
+ attempt.drop();
+ await backoff();
+ } else {
+ attempt.stop();
+ await vi.advanceTimersByTimeAsync(0);
+ await client.reconnect();
+ }
+ expect(store.get(client.attachmentsAtom)).toEqual([]);
+ const replay = await opened();
+ expect(replay.cursor).toBe("112a");
+ expect(store.get(client.attachmentsAtom)).toEqual([]);
+ expect(store.get(client.documentAtom)).toBe(confirmed);
+ edits.slice(3).forEach(replay.receive);
+ replay.receive({
+ event: "attachment.removed",
+ id: "115",
+ data: { id: browser.id },
+ });
+ expect(store.get(client.attachmentsAtom)).toEqual([]);
+ replay.receive({ event: "ready", id: "116", data: {} });
+ expect(store.get(client.attachmentsAtom)).toEqual([renamed]);
+ const revisions = fixtureEvents("edits.sse").flatMap((event) =>
+ event.event === "document" ? [event.data.document] : [],
+ );
+ expect(store.get(client.documentAtom)?.revision).toEqual(
+ revisions.at(-1),
+ );
+ },
+ );
- it.each(["close", "error", "malformed", "removed", "abort", "identity"])(
+ it.each(["drop", "stop", "removed", "abort"])(
"clears presence on %s and ignores messages after disposal",
async (reason) => {
- const { client, store, receive, events, url, lifetime } = await open();
- fixtureMessages("notebook-events.sse").forEach(receive);
+ vi.useFakeTimers();
+ const current = lifetime();
+ const result = setup();
+ result.connect(current.signal);
+ const { client, store } = result;
+ const attempt = await result.opened();
+ fixtureMessages("notebook-events.sse").forEach(attempt.receive);
expect(store.get(client.attachmentsAtom)).toEqual([browser, agent]);
switch (reason) {
- case "close":
- events.dispatchEvent(
- new CloseEvent("close", { reason: "MARIMO_UNAUTHORIZED" }),
- );
+ case "drop":
+ attempt.drop();
+ await backoff();
break;
- case "error":
- events.dispatchEvent(new Event("error"));
- break;
- case "malformed":
- receive({ event: "attachment", id: "98", data: {} });
+ case "stop":
+ attempt.stop({
+ state: ConnectionState.CLOSED,
+ code: "KERNEL_DISCONNECTED",
+ reason: "not authorized",
+ });
+ await vi.advanceTimersByTimeAsync(0);
break;
case "removed":
- receive({ event: "notebook.removed", id: "98", data: { id: "n1" } });
- break;
- case "identity":
- url.mockReturnValue(
- "ws://localhost/api/marimo/v1/notebooks/n2/events/ws",
- );
- events.dispatchEvent(new CloseEvent("close"));
- receive({ event: "ready", id: "98", data: {} });
+ attempt.receive({
+ event: "notebook.removed",
+ id: "98",
+ data: { id: "n1" },
+ });
break;
default:
- lifetime.abort();
+ current.abort();
}
expect(store.get(client.attachmentsAtom)).toEqual([]);
- lifetime.abort();
- fixtureMessages("notebook-events.sse").forEach(receive);
+ current.abort();
+ fixtureMessages("notebook-events.sse").forEach(attempt.receive);
expect(store.get(client.attachmentsAtom)).toEqual([]);
},
);
-
- it("keeps host resources empty for notification-only WASM connections", async () => {
- const { client, store, receive, lifetime } = await open();
- receive({ data: { op: "kernel-ready" } });
- receive({ data: { op: "reconnected" } });
- expect(store.get(client.attachmentsAtom)).toEqual([]);
- lifetime.abort();
- });
});
diff --git a/frontend/src/core/host/notebook-client.ts b/frontend/src/core/host/notebook-client.ts
index c30a5e5be5..70e63d49de 100644
--- a/frontend/src/core/host/notebook-client.ts
+++ b/frontend/src/core/host/notebook-client.ts
@@ -1,27 +1,31 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { Logger } from "@/utils/Logger";
+import {
+ createNotebookReducer,
+ type NotebookEvent,
+ NotebookEvents,
+ type NotebookTransport,
+ StreamStopped,
+} from "@marimo-team/client";
import type { Attachment, NotebookOutput } from "@marimo-team/client/protocol";
-import { createNotebookReducer } from "@marimo-team/client";
import { type Atom, atom, type createStore } from "jotai/vanilla";
+import { z } from "zod";
import {
- type ConnectionStatus,
- ConnectionState,
ConnectionClosedReason,
- type CloseDecision,
- type NotebookTransport,
- TransportReadyState,
+ ConnectionState,
+ type ConnectionStatus,
} from "./connection";
-import { type NotebookEvent, parseNotebookEvent } from "./events";
import { attachments } from "./resources/attachments";
import { type Document, document } from "./resources/document";
-/** Events that may arrive without a cursor after `ready`. */
-const UNCURSORED = new Set<NotebookEvent["event"]>([
- "reset",
- "marimo",
- "unknown",
-]);
+/** The kinds the editor reads, with marimo's own notifications. */
+const TYPES = ["notebook", "cell", "document", "attachment", "marimo"] as const;
+
+type EditorEvent = NotebookEvent<(typeof TYPES)[number]>;
+
+/** A native marimo notification, passed through without interpretation. */
+const MarimoMessage = z.object({ marimo: z.unknown() });
/** A connection to a notebook on a marimo host. */
export interface NotebookClient {
@@ -43,28 +47,53 @@ export interface NotebookClient {
reconnect(): Promise<void>;
}
-/** The transport and application callbacks needed to connect a notebook. */
+/** The transport and application callbacks needed to follow a notebook. */
export interface NotebookConnection {
- /** Create a transport that reads the URL again on each connection attempt. */
- createTransport: (url: () => string) => NotebookTransport;
- /** The current stream URL, including authentication and subscription options. */
- url: () => string;
- /** Abort to close the transport and clear the client's state. */
+ /** Opens one connection to the notebook's stream. */
+ transport: NotebookTransport;
+ /** Abort to close the stream and clear the client's state. */
signal: AbortSignal;
- /** Wait until the host can accept the initial connection. */
- waitUntilReady: () => Promise<void>;
/** Check whether the host is reachable before an explicit reconnect. */
checkHealth: () => Promise<boolean>;
- /** Decode wire text without interpreting its event type. */
- decodeJson: (message: string) => unknown;
/** Handle a native marimo notification. Its payload has not been validated. */
onNotification: (notification: unknown) => void;
- /** Choose the connection status and retry policy after the transport closes. */
- classifyClose: (event: CloseEvent) => CloseDecision;
+}
+
+const disconnected = {
+ state: ConnectionState.CLOSED,
+ code: ConnectionClosedReason.KERNEL_DISCONNECTED,
+ reason: "kernel not found",
+} satisfies ConnectionStatus;
+
+const malformed = {
+ ...disconnected,
+ reason: "Failed to decode notebook message",
+} satisfies ConnectionStatus;
+
+function isStatus(value: unknown): value is ConnectionStatus {
+ return typeof value === "object" && value !== null && "state" in value;
+}
+
+/**
+ * The status to show after the stream stopped.
+ *
+ * A transport says which status its stop means. An event the protocol
+ * rejects is malformed. Anything else means the host was not reached.
+ */
+function statusAfter(error: unknown): ConnectionStatus {
+ if (error instanceof StreamStopped && isStatus(error.cause)) {
+ return error.cause;
+ }
+ if (error instanceof StreamStopped && error.cause instanceof z.ZodError) {
+ return malformed;
+ }
+ return disconnected;
}
/** Create a client without opening a connection. */
export function createNotebookClient(store: ReturnType<typeof createStore>) {
+ // `useNotebookSession` copies this into the editor's shared `connectionAtom`,
+ // which gates features until MO-8051 derives availability separately.
const connectionAtom = atom<ConnectionStatus>({
state: ConnectionState.NOT_STARTED,
});
@@ -73,16 +102,18 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {
const streamAtom = atom(reducer.initial);
// A resumed stream is live, but presence waits for this connection's ready.
const readyAtom = atom(false);
+ const presentAtom = atom(
+ (get) =>
+ get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN,
+ );
const notebookAtom = atom((get) =>
- get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN
- ? get(streamAtom).notebook
- : null,
+ get(presentAtom) ? get(streamAtom).notebook : null,
);
const documentAtom = atom(
(get) => get(streamAtom).resources.document.current,
);
const attachmentsAtom = atom((get) =>
- get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN
+ get(presentAtom)
? get(streamAtom).resources.attachments
: attachments.initial,
);
@@ -95,156 +126,97 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {
reconnect: async () => reconnect?.(),
};
+ function setStatus(status: ConnectionStatus) {
+ store.set(readyAtom, false);
+ store.set(connectionAtom, status);
+ }
+
function connect({
- createTransport,
- url,
+ transport,
signal,
- waitUntilReady,
checkHealth,
onNotification,
- decodeJson,
- classifyClose,
}: NotebookConnection) {
if (signal.aborted) {
return;
}
- let shouldRetry = true;
- let terminal = false;
+ let events: NotebookEvents<(typeof TYPES)[number]> | undefined;
let checkingHealth = false;
- let streamKey: string | undefined;
- // The id of the last live event. Null before `ready` and after `reset`.
- let cursor: string | null = null;
- const transport = createTransport(() => {
- const next = new URL(url());
- next.searchParams.delete("cursor");
- if (signal.aborted) {
- return next.toString();
- }
- // A cursor is useful with the state that produced it, which a change
- // of session or notebook invalidates. Authentication may change freely.
- const identity = new URL(next);
- identity.searchParams.delete("access_token");
- identity.searchParams.sort();
- const key = identity.toString();
- const current = store.get(streamAtom);
- // A live stream keeps its state and resumes from the cursor. An
- // incomplete snapshot starts over.
- const state =
- key !== streamKey || current.phase === "snapshot"
- ? reducer.initial
- : current;
- if (state.phase === "snapshot") {
- cursor = null;
- }
- streamKey = key;
- store.set(readyAtom, false);
- store.set(streamAtom, state);
- if (cursor !== null) {
- next.searchParams.set("cursor", cursor);
- }
- return next.toString();
- });
- const setStatus = (status: ConnectionStatus) => {
- store.set(readyAtom, false);
- store.set(connectionAtom, status);
- };
- const disconnected = {
- state: ConnectionState.CLOSED,
- code: ConnectionClosedReason.KERNEL_DISCONNECTED,
- reason: "kernel not found",
- } satisfies ConnectionStatus;
+ // Whether the replica still holds the state the last cursor describes.
+ let resumable = true;
- function retry(code?: number, reason?: string) {
- if (!signal.aborted && !terminal && shouldRetry) {
- shouldRetry = false;
- transport.reconnect(code, reason);
- }
- }
-
- function onOpen() {
- if (signal.aborted || terminal) {
- return;
- }
- shouldRetry = true;
- setStatus({ state: ConnectionState.OPEN });
- }
-
- function onClose(event: CloseEvent) {
- if (signal.aborted || terminal) {
- return;
- }
- Logger.warn("Notebook connection closed", event.code, event.reason);
- const decision = classifyClose(event);
- setStatus(decision.status);
- if (decision.kind === "terminal") {
- terminal = true;
- transport.close();
- } else if (decision.kind === "retry") {
- retry(event.code, event.reason);
- } else {
- terminal = true;
+ /** Mirror one stream into the atoms until it closes. */
+ function follow(cursor?: string) {
+ if (cursor === undefined) {
+ store.set(streamAtom, reducer.initial);
}
+ resumable = true;
+ const current = new NotebookEvents(transport, {
+ types: TYPES,
+ cursor,
+ signal,
+ // TODO(MO-8051): Gate editing and running on the notebook's operations
+ // and request results instead. The stream's status would then only
+ // mark the view as stale.
+ onStatus: (status) => {
+ if (status === "connecting") {
+ setStatus({ state: ConnectionState.CONNECTING });
+ } else if (status === "connected") {
+ setStatus({ state: ConnectionState.OPEN });
+ }
+ },
+ });
+ current.subscribe(
+ (event) => apply(current, event),
+ (error) => {
+ if (!signal.aborted && current === events) {
+ Logger.warn("Notebook stream stopped", error);
+ const status = statusAfter(error);
+ if (status === malformed) {
+ stopMalformed(current);
+ } else {
+ setStatus(status);
+ }
+ }
+ },
+ );
+ events = current;
}
- function onError(event: Event) {
- if (signal.aborted || terminal) {
- return;
- }
- Logger.warn("Notebook connection error", event);
- setStatus(disconnected);
- retry();
+ function stopMalformed(source: NotebookEvents<string>) {
+ source.close();
+ // The cursor can already include an event the replica rejected.
+ resumable = false;
+ store.set(streamAtom, reducer.initial);
+ setStatus(malformed);
}
- function onMessage(message: MessageEvent<string>) {
- if (signal.aborted || terminal) {
+ function apply(source: NotebookEvents<string>, event: EditorEvent) {
+ if (event.event === "marimo") {
+ const message = MarimoMessage.safeParse(event.data);
+ if (message.success) {
+ onNotification(message.data.marimo);
+ } else {
+ Logger.error("Failed to decode notebook message", event);
+ stopMalformed(source);
+ }
return;
}
- let event;
try {
- event = parseNotebookEvent(decodeJson(message.data));
- const state = store.get(streamAtom);
- if (
- state.phase === "live" &&
- event.id === undefined &&
- !UNCURSORED.has(event.event)
- ) {
- throw new Error("Live notebook event is missing its cursor");
- }
- if (event.event !== "marimo" && event.event !== "unknown") {
- store.set(streamAtom, reducer.reduce(state, event));
- }
- if (event.event === "reset") {
- cursor = null;
- } else if (event.event === "ready" || state.phase === "live") {
- cursor = event.id ?? cursor;
- }
- if (event.event === "ready" || event.event === "reset") {
- store.set(readyAtom, event.event === "ready");
- }
+ store.set(streamAtom, reducer.reduce(store.get(streamAtom), event));
} catch (error) {
- Logger.error("Failed to decode notebook message", error);
- store.set(streamAtom, reducer.initial);
- cursor = null;
- terminal = true;
- setStatus({
- ...disconnected,
- reason: "Failed to decode notebook message",
- });
- transport.close();
+ // An event the replica cannot apply, such as another notebook's.
+ Logger.error("Failed to apply notebook event", error);
+ stopMalformed(source);
return;
}
- if (event.event === "marimo") {
- onNotification(event.data.marimo);
+ if (event.event === "ready" || event.event === "reset") {
+ store.set(readyAtom, event.event === "ready");
}
}
reconnect = async () => {
- if (
- signal.aborted ||
- checkingHealth ||
- transport.readyState === TransportReadyState.OPEN ||
- transport.readyState === TransportReadyState.CONNECTING
- ) {
+ if (signal.aborted || checkingHealth || events?.status !== "closed") {
return;
}
checkingHealth = true;
@@ -255,17 +227,13 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {
return;
}
if (!healthy) {
- shouldRetry = false;
setStatus(disconnected);
return;
}
- terminal = false;
- shouldRetry = true;
- transport.reconnect();
+ follow(resumable ? (events.cursor ?? undefined) : undefined);
} catch (error) {
if (!signal.aborted) {
Logger.error("Notebook health check failed", error);
- shouldRetry = false;
setStatus(disconnected);
}
} finally {
@@ -276,11 +244,6 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {
signal.addEventListener(
"abort",
() => {
- transport.removeEventListener("open", onOpen);
- transport.removeEventListener("close", onClose);
- transport.removeEventListener("error", onError);
- transport.removeEventListener("message", onMessage);
- transport.close();
reconnect = undefined;
store.set(streamAtom, reducer.initial);
setStatus({ state: ConnectionState.NOT_STARTED });
@@ -288,28 +251,8 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {
{ once: true },
);
- transport.addEventListener("open", onOpen);
- transport.addEventListener("close", onClose);
- transport.addEventListener("error", onError);
- transport.addEventListener("message", onMessage);
-
- if (transport.readyState === TransportReadyState.CLOSED) {
- setStatus({ state: ConnectionState.CONNECTING });
- void waitUntilReady()
- .then(() => {
- if (!signal.aborted) {
- transport.reconnect();
- }
- })
- .catch((error) => {
- if (!signal.aborted) {
- Logger.error("Healthy connection never made", error);
- terminal = true;
- setStatus(disconnected);
- transport.close();
- }
- });
- }
+ setStatus({ state: ConnectionState.CONNECTING });
+ follow();
}
return { client, connect };
diff --git a/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx b/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx
index 316fcf02c9..98ac4d9206 100644
--- a/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx
+++ b/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx
@@ -5,52 +5,48 @@ import { act, renderHook } from "@testing-library/react";
import { createStore, Provider } from "jotai";
import type { PropsWithChildren } from "react";
import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { NotebookTransport } from "@marimo-team/client";
import { ConnectionState } from "../types";
-import { createConnectionTransport } from "../transports/create";
-import type { IConnectionTransport } from "../transports/transport";
+import { Deferred } from "@/utils/Deferred";
+import { createNotebookTransport } from "../transports/notebook";
import { useNotebookClient } from "../useNotebookClient";
import { fixtureMessages } from "../../host/__tests__/fixtures";
import { agentAttachmentsAtom } from "../../attachments/state";
import { notebookClientAtom } from "../state";
-vi.mock("../transports/create", () => ({ createConnectionTransport: vi.fn() }));
+vi.mock("../transports/notebook", () => ({ createNotebookTransport: vi.fn() }));
-function makeTransport(url?: () => string) {
- const events = new EventTarget();
- const transport: IConnectionTransport = {
- readyState: WebSocket.CLOSED,
- reconnect: vi.fn(() => {
- url?.();
- transport.readyState = WebSocket.OPEN;
- events.dispatchEvent(new Event("open"));
- }),
- close: vi.fn(() => {
- transport.readyState = WebSocket.CLOSED;
- events.dispatchEvent(new CloseEvent("close"));
- }),
- send: vi.fn(),
- addEventListener: events.addEventListener.bind(events),
- removeEventListener: events.removeEventListener.bind(events),
- };
+/** A transport whose connections the test drives. */
+function makeTransport() {
+ const opened: {
+ signal: AbortSignal;
+ open(): void;
+ receive(message: unknown): void;
+ }[] = [];
+ const transport: NotebookTransport = ({ signal }, handlers) =>
+ new Promise((resolve) => {
+ opened.push({ signal, open: handlers.open, receive: handlers.message });
+ signal.addEventListener("abort", () => resolve(), { once: true });
+ });
return {
transport,
- receive: (message: unknown) =>
- events.dispatchEvent(
- new MessageEvent("message", { data: JSON.stringify(message) }),
- ),
+ opened,
+ /** Open the latest connection and deliver a host-framed notification. */
notify: () =>
- events.dispatchEvent(
- new MessageEvent("message", {
- data: JSON.stringify({
- event: "marimo",
- data: { marimo: { op: "reconnected" } },
- }),
- }),
- ),
+ opened.at(-1)?.receive({
+ event: "marimo",
+ data: { marimo: { op: "reconnected" } },
+ }),
};
}
-function setup(strict = false) {
+function setup(
+ strict = false,
+ readiness: {
+ waitUntilReady?: () => Promise<void>;
+ checkHealth?: () => Promise<boolean>;
+ } = {},
+) {
const store = createStore();
const options = {
static: false,
@@ -60,6 +56,7 @@ function setup(strict = false) {
waitUntilReady: async () => undefined,
checkHealth: async () => true,
onNotification: vi.fn(),
+ ...readiness,
};
const wrapper = ({ children }: PropsWithChildren) => (
<Provider store={store}>{children}</Provider>
@@ -73,19 +70,97 @@ function setup(strict = false) {
}
beforeEach(() => {
- vi.mocked(createConnectionTransport).mockReset();
+ vi.mocked(createNotebookTransport).mockReset();
});
describe("useNotebookClient", () => {
+ it.each([true, false])(
+ "rechecks health after failed startup (healthy: %s)",
+ async (healthy) => {
+ const fake = makeTransport();
+ vi.mocked(createNotebookTransport).mockImplementation(
+ ({ url }) =>
+ async (attempt, handlers) => {
+ if (typeof url === "function") {
+ await url();
+ }
+ if (!attempt.signal.aborted) {
+ return fake.transport(attempt, handlers);
+ }
+ },
+ );
+ const waitUntilReady = vi
+ .fn()
+ .mockRejectedValue(new Error("Startup gave up"));
+ const checkHealth = vi.fn().mockResolvedValue(healthy);
+ const { result, store, unmount } = setup(false, {
+ waitUntilReady,
+ checkHealth,
+ });
+ await act(async () => Promise.resolve());
+ expect(store.get(result.current.connectionAtom).state).toBe(
+ ConnectionState.CLOSED,
+ );
+
+ await act(async () => result.current.reconnect());
+ expect({
+ healthChecks: checkHealth.mock.calls.length,
+ initialWaits: waitUntilReady.mock.calls.length,
+ connections: fake.opened.length,
+ state: store.get(result.current.connectionAtom).state,
+ }).toEqual({
+ healthChecks: 1,
+ initialWaits: 1,
+ connections: healthy ? 1 : 0,
+ state: healthy ? ConnectionState.CONNECTING : ConnectionState.CLOSED,
+ });
+ act(() => fake.opened.at(-1)?.open());
+ expect(store.get(result.current.connectionAtom).state).toBe(
+ healthy ? ConnectionState.OPEN : ConnectionState.CLOSED,
+ );
+ unmount();
+ },
+ );
+
+ it("waits for initial readiness without reviving an unmounted connection", async () => {
+ const ready = new Deferred<void>();
+ const resolvedUrl = vi.fn();
+ vi.mocked(createNotebookTransport).mockImplementation(
+ ({ url }) =>
+ async () => {
+ if (typeof url === "function") {
+ await url();
+ resolvedUrl();
+ }
+ },
+ );
+ const { result, store, unmount } = setup(false, {
+ waitUntilReady: () => ready.promise,
+ });
+ await act(async () => Promise.resolve());
+ expect(resolvedUrl).not.toHaveBeenCalled();
+ expect(store.get(result.current.connectionAtom)).toEqual({
+ state: ConnectionState.CONNECTING,
+ });
+ unmount();
+ await act(async () => ready.resolve());
+ expect(store.get(result.current.connectionAtom)).toEqual({
+ state: ConnectionState.NOT_STARTED,
+ });
+ expect(store.get(notebookClientAtom)).toBeNull();
+ });
+
it("exposes host presence to the UI without waiting for kernel-ready", async () => {
- const transport = makeTransport();
- vi.mocked(createConnectionTransport).mockReturnValue(transport.transport);
+ const fake = makeTransport();
+ vi.mocked(createNotebookTransport).mockReturnValue(fake.transport);
const { result, store, unmount } = setup();
await act(async () => Promise.resolve());
expect(store.get(notebookClientAtom)).toBe(result.current);
- act(() =>
- fixtureMessages("notebook-events.sse").forEach(transport.receive),
- );
+ const [connection] = fake.opened;
+ act(() => {
+ connection.open();
+ fixtureMessages("notebook-events.sse").forEach(connection.receive);
+ });
expect(store.get(agentAttachmentsAtom)).toEqual([
{
id: "a2",
@@ -101,49 +176,48 @@ describe("useNotebookClient", () => {
});
it("uses current callbacks and URL providers without reconnecting on a rerender", async () => {
- const first = makeTransport();
- vi.mocked(createConnectionTransport).mockReturnValue(first.transport);
+ const fake = makeTransport();
+ vi.mocked(createNotebookTransport).mockReturnValue(fake.transport);
const { rerender, options, unmount } = setup();
await act(async () => Promise.resolve());
const onNotification = vi.fn();
rerender({ ...options, onNotification, url: () => "ws://redirected/ws" });
- act(() => first.notify());
+ act(() => fake.notify());
expect(options.onNotification).not.toHaveBeenCalled();
expect(onNotification).toHaveBeenCalledExactlyOnceWith({
data: { op: "reconnected" },
});
- expect(createConnectionTransport).toHaveBeenCalledOnce();
- expect(vi.mocked(createConnectionTransport).mock.calls[0][0].url()).toBe(
+ expect(createNotebookTransport).toHaveBeenCalledOnce();
+ const [{ url }] = vi.mocked(createNotebookTransport).mock.calls[0];
+ expect(String(await (url as () => Promise<string>)())).toBe(
"ws://redirected/ws",
);
unmount();
});
- it("cleans up every transport under Strict Mode and only connects the active lifetime", async () => {
- const transports: ReturnType<typeof makeTransport>[] = [];
- vi.mocked(createConnectionTransport).mockImplementation(() => {
+ it("closes every stream under Strict Mode and only follows the active lifetime", async () => {
+ const fakes: ReturnType<typeof makeTransport>[] = [];
+ vi.mocked(createNotebookTransport).mockImplementation(() => {
const next = makeTransport();
- transports.push(next);
+ fakes.push(next);
return next.transport;
});
const { result, store, options, unmount } = setup(true);
await act(async () => Promise.resolve());
- expect(transports).toHaveLength(2);
- expect(transports[0].transport.reconnect).not.toHaveBeenCalled();
- expect(transports[0].transport.close).toHaveBeenCalledOnce();
- expect(transports[1].transport.reconnect).toHaveBeenCalledOnce();
+ expect(fakes).toHaveLength(2);
+ expect(fakes[0].opened.every((attempt) => attempt.signal.aborted)).toBe(
+ true,
+ );
+ const [active] = fakes[1].opened;
+ act(() => active.open());
expect(store.get(result.current.connectionAtom)).toEqual({
state: ConnectionState.OPEN,
});
- act(() => {
- for (const transport of transports) {
- transport.notify();
- }
- });
+ act(() => fakes.forEach((fake) => fake.notify()));
expect(options.onNotification).toHaveBeenCalledOnce();
unmount();
- expect(transports[1].transport.close).toHaveBeenCalledOnce();
+ expect(active.signal.aborted).toBe(true);
await result.current.reconnect();
- expect(transports[1].transport.reconnect).toHaveBeenCalledOnce();
+ expect(fakes[1].opened).toHaveLength(1);
});
});
diff --git a/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx b/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx
index bbacfe96a0..08850489ed 100644
--- a/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx
+++ b/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx
@@ -21,8 +21,8 @@ import {
vi,
} from "vitest";
-vi.mock("../transports/create", () => ({
- createConnectionTransport: vi.fn(),
+vi.mock("../transports/notebook", () => ({
+ createNotebookTransport: vi.fn(),
}));
vi.mock("@/core/runtime/config", async () => {
@@ -36,7 +36,6 @@ vi.mock("@/core/runtime/config", async () => {
});
import { MockNotebook } from "@/__mocks__/notebook";
-import { Logger } from "@/utils/Logger";
import { Deferred } from "@/utils/Deferred";
import { cellId } from "@/__tests__/branded";
import { alertAtom, getPackageAlert } from "@/core/alerts/state";
@@ -44,7 +43,6 @@ import { notebookAtom } from "@/core/cells/cells";
import { AppConfigSchema } from "@/core/config/config-schema";
import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
import { kernelStartupErrorAtom } from "@/core/errors/state";
-import type { RunEvent } from "@marimo-team/client/protocol";
import type { NotificationPayload } from "@/core/kernel/messages";
import { useRuntimeManager } from "@/core/runtime/config";
import { initialRunCompletedAtom } from "../../kernel/state";
@@ -52,54 +50,72 @@ import { connectionAtom, startupProgressAtom } from "../../network/connection";
import { generateSessionId } from "../../kernel/session";
import { RuntimeManager } from "../../runtime/runtime";
import { WebSocketClosedReason, ConnectionState } from "../types";
-import type { IConnectionTransport } from "../transports/transport";
+import { classifyCloseEvent } from "../connection-state";
+import { createNotebookTransport } from "../transports/notebook";
import { useNotebookSession } from "../useNotebookSession";
-import { createConnectionTransport } from "../transports/create";
+import { type NotebookTransport, StreamStopped } from "@marimo-team/client";
const SESSION_ID = generateSessionId();
-interface MockTransport {
- readyState: 0 | 1 | 2 | 3;
- reconnect: Mock<IConnectionTransport["reconnect"]>;
- close: Mock<IConnectionTransport["close"]>;
- send: Mock<IConnectionTransport["send"]>;
- addEventListener: Mock<IConnectionTransport["addEventListener"]>;
- removeEventListener: Mock<IConnectionTransport["removeEventListener"]>;
+/** One connection the fake transport opened. */
+interface Attempt {
+ open(): void;
+ receive(message: unknown): void;
+ drop(): void;
+ stop(error: StreamStopped): void;
}
-function makeTransport(
- readyState: 0 | 1 | 2 | 3 = WebSocket.CLOSED,
-): MockTransport {
- return {
- readyState,
- reconnect: vi.fn(),
- close: vi.fn(),
- send: vi.fn(),
- addEventListener: vi.fn(),
- removeEventListener: vi.fn(),
- };
+/** A transport the test drives, one connection at a time. */
+function makeTransport() {
+ const attempts: Attempt[] = [];
+ const transport: NotebookTransport = ({ signal }, handlers) =>
+ new Promise((resolve, reject) => {
+ attempts.push({
+ open: handlers.open,
+ receive: handlers.message,
+ drop: resolve,
+ stop: reject,
+ });
+ signal.addEventListener("abort", () => resolve(), { once: true });
+ });
+ return { transport, attempts };
}
-function getTransportHandlers() {
- const result = vi.mocked(createConnectionTransport).mock.results.at(-1);
- if (!result || result.type !== "return") {
- throw new Error("No connection transport was created");
- }
- const transport = result.value;
- function emit(
- event: "open" | "close" | "error" | "message",
- message: Event | CloseEvent | MessageEvent,
- ) {
- const callback = vi
- .mocked(transport.addEventListener)
- .mock.calls.find(([name]) => name === event)?.[1];
- callback?.(message);
- }
+type FakeTransport = ReturnType<typeof makeTransport>;
+
+/** Use a fake transport for the next session the hook follows. */
+function withTransport(fake: FakeTransport = makeTransport()) {
+ vi.mocked(createNotebookTransport).mockReturnValue(fake.transport);
+ return fake;
+}
+
+/** Let the stream open its first connection. */
+const started = () => act(() => Promise.resolve());
+
+/** Drive the latest connection the fake transport opened. */
+function connection(fake: FakeTransport) {
+ const current = () => {
+ const attempt = fake.attempts.at(-1);
+ if (attempt === undefined) {
+ throw new Error("No connection was opened");
+ }
+ return attempt;
+ };
return {
- onError: (event: Event) => emit("error", event),
- onOpen: (event: Event) => emit("open", event),
- onClose: (event: CloseEvent) => emit("close", event),
- onMessage: (event: MessageEvent) => emit("message", event),
+ open: () => current().open(),
+ receive: (message: unknown) => current().receive(message),
+ /** Deliver a notification as the session routes frame it. */
+ send: (notification: unknown) =>
+ current().receive({ event: "marimo", data: { marimo: notification } }),
+ /** End the connection so the stream reconnects. */
+ drop: () => current().drop(),
+ /** Close the connection with a reason the editor treats as final. */
+ close: (reason: string) =>
+ current().stop(
+ new StreamStopped(reason, {
+ cause: classifyCloseEvent({ reason }).status,
+ }),
+ ),
};
}
@@ -141,12 +157,12 @@ function renderConnectionHook(store: ReturnType<typeof createStore>) {
}
describe("useNotebookSession.reconnect()", () => {
- let transport: MockTransport;
+ let fake: FakeTransport;
let isHealthy: Mock<() => Promise<boolean>>;
let store: ReturnType<typeof createStore>;
beforeEach(() => {
- transport = makeTransport(WebSocket.CLOSED);
+ fake = withTransport();
isHealthy = vi.fn<() => Promise<boolean>>().mockResolvedValue(true);
store = createStore();
store.set(connectionAtom, {
@@ -154,55 +170,53 @@ describe("useNotebookSession.reconnect()", () => {
code: WebSocketClosedReason.KERNEL_DISCONNECTED,
reason: "kernel not found",
});
- vi.mocked(createConnectionTransport).mockReturnValue(transport);
vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager(isHealthy));
});
- function renderUseHook() {
- return renderConnectionHook(store);
+ async function renderStopped() {
+ const hook = renderConnectionHook(store);
+ await started();
+ await act(async () => connection(fake).close("MARIMO_SHUTDOWN"));
+ return hook;
}
- it("is a no-op when the transport is already OPEN", async () => {
- transport.readyState = WebSocket.OPEN;
- const { result } = renderUseHook();
- await act(async () => {
- await result.current.reconnect();
- });
- expect(isHealthy).not.toHaveBeenCalled();
- expect(transport.reconnect).not.toHaveBeenCalled();
- });
-
- it("is a no-op when the transport is already CONNECTING", async () => {
- transport.readyState = WebSocket.CONNECTING;
- const { result } = renderUseHook();
- await act(async () => {
- await result.current.reconnect();
- });
- expect(isHealthy).not.toHaveBeenCalled();
- expect(transport.reconnect).not.toHaveBeenCalled();
- });
+ it.each(["connecting", "connected"])(
+ "is a no-op while the stream is %s",
+ async (state) => {
+ const { result } = renderConnectionHook(store);
+ await started();
+ if (state === "connected") {
+ act(() => connection(fake).open());
+ }
+ await act(async () => {
+ await result.current.reconnect();
+ });
+ expect(isHealthy).not.toHaveBeenCalled();
+ expect(fake.attempts).toHaveLength(1);
+ },
+ );
it("probes /health and reconnects when the runtime is healthy", async () => {
isHealthy.mockResolvedValue(true);
- const { result } = renderUseHook();
+ const { result } = await renderStopped();
await act(async () => {
await result.current.reconnect();
});
expect(isHealthy).toHaveBeenCalledOnce();
- expect(transport.reconnect).toHaveBeenCalledOnce();
+ expect(fake.attempts).toHaveLength(2);
expect(store.get(connectionAtom)).toEqual({
state: ConnectionState.CONNECTING,
});
});
- it("transitions to CLOSED and does not call ws.reconnect when the probe fails", async () => {
+ it("transitions to CLOSED and does not reconnect when the probe fails", async () => {
isHealthy.mockResolvedValue(false);
- const { result } = renderUseHook();
+ const { result } = await renderStopped();
await act(async () => {
await result.current.reconnect();
});
expect(isHealthy).toHaveBeenCalledOnce();
- expect(transport.reconnect).not.toHaveBeenCalled();
+ expect(fake.attempts).toHaveLength(1);
expect(store.get(connectionAtom)).toEqual({
state: ConnectionState.CLOSED,
code: WebSocketClosedReason.KERNEL_DISCONNECTED,
@@ -213,115 +227,30 @@ describe("useNotebookSession.reconnect()", () => {
describe("useNotebookSession messages", () => {
let store: ReturnType<typeof createStore>;
+ let fake: FakeTransport;
- beforeEach(() => {
+ beforeEach(async () => {
store = createStore();
- vi.mocked(createConnectionTransport).mockClear();
- vi.mocked(createConnectionTransport).mockReturnValue(
- makeTransport(WebSocket.OPEN),
- );
+ fake = withTransport();
vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
renderConnectionHook(store);
+ await started();
});
function receive(payload: unknown) {
- const options = getTransportHandlers();
- act(() => {
- options.onMessage(
- new MessageEvent("message", { data: JSON.stringify(payload) }),
- );
- });
+ act(() => connection(fake).receive(payload));
}
- it.each(["{broken", "null"])(
- "closes a malformed stream and ignores subsequent notifications: %s",
- (data) => {
- receive({ event: "marimo", data: { marimo: { op: "reconnected" } } });
- act(() =>
- getTransportHandlers().onMessage(new MessageEvent("message", { data })),
- );
- expect(store.get(connectionAtom)).toEqual({
- state: ConnectionState.CLOSED,
- code: "KERNEL_DISCONNECTED",
- reason: "Failed to decode notebook message",
- });
- receive({
- event: "marimo",
- data: {
- marimo: {
- op: "completed-run",
- run_id: "r1",
- outcome: "succeeded",
- error: null,
- },
- },
- });
- expect(store.get(initialRunCompletedAtom)).toBe(false);
- },
- );
-
- it.each(["session", "host"])(
- "records completion of the initial run from the %s stream",
- (stream) => {
- const notification = {
- op: "completed-run",
- run_id: null,
- outcome: "succeeded",
- error: null,
- } satisfies NotificationPayload["data"];
- expect(store.get(initialRunCompletedAtom)).toBe(false);
- receive(
- stream === "host"
- ? { id: "42", event: "marimo", data: { marimo: notification } }
- : { op: notification.op, data: notification },
- );
- expect(store.get(initialRunCompletedAtom)).toBe(true);
- },
- );
-
- it("ignores other host events before handling the next notification", () => {
- const errors = vi.spyOn(Logger, "error").mockImplementation(vi.fn());
- try {
- receive({ id: "1", event: "ready", data: {} });
- receive({
- id: "2",
- event: "run",
- data: {
- run: {
- id: "r1",
- notebook_id: "n1",
- caused_by: null,
- status: "completed",
- outcome: "succeeded",
- started_at: "2026-10-19T12:00:00Z",
- completed_at: "2026-10-19T12:00:01Z",
- },
- },
- } satisfies RunEvent);
- receive({
- id: "3",
- event: "future-event",
- data: { marimo: { op: "completed-run", run_id: "r1" } },
- });
- receive({ id: "4", event: "another-event", data: null });
- expect(store.get(initialRunCompletedAtom)).toBe(false);
- receive({
- id: "5",
- event: "marimo",
- data: {
- marimo: {
- op: "completed-run",
- run_id: "r1",
- outcome: "succeeded",
- error: null,
- },
- },
- });
- expect(store.get(initialRunCompletedAtom)).toBe(true);
- expect(errors).not.toHaveBeenCalled();
- } finally {
- errors.mockRestore();
- }
+ it("records completion of the initial run", () => {
+ const notification = {
+ op: "completed-run",
+ run_id: null,
+ outcome: "succeeded",
+ error: null,
+ } satisfies NotificationPayload["data"];
+ expect(store.get(initialRunCompletedAtom)).toBe(false);
+ receive({ id: "42", event: "marimo", data: { marimo: notification } });
+ expect(store.get(initialRunCompletedAtom)).toBe(true);
});
});
@@ -330,45 +259,34 @@ it.each(["kernel-ready", "reconnected"])(
async (op) => {
const store = createStore();
store.set(connectionAtom, { state: ConnectionState.CONNECTING });
- vi.mocked(createConnectionTransport).mockClear();
- vi.mocked(createConnectionTransport).mockReturnValue(
- makeTransport(WebSocket.OPEN),
- );
+ const fake = withTransport();
vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
renderConnectionHook(store);
- const options = getTransportHandlers();
+ await started();
+ const conn = connection(fake);
- await act(async () => {
- await options.onOpen(new Event("open"));
- });
+ await act(async () => conn.open());
expect(store.get(connectionAtom).state).toBe(ConnectionState.CONNECTING);
- act(() => {
- options.onMessage(
- new MessageEvent("message", {
- data: JSON.stringify({
- op,
- data: {
- op,
- cell_ids: [],
- codes: [],
- names: [],
- configs: [],
- layout: null,
- resumed: true,
- ui_values: {},
- last_executed_code: {},
- last_execution_time: {},
- app_config: { width: "normal" },
- kiosk: false,
- capabilities: { terminal: false },
- auto_instantiated: false,
- consumer_capabilities: { edit: true, interact: true },
- },
- }),
- }),
- );
- });
+ act(() =>
+ conn.send({
+ op,
+ cell_ids: [],
+ codes: [],
+ names: [],
+ configs: [],
+ layout: null,
+ resumed: true,
+ ui_values: {},
+ last_executed_code: {},
+ last_execution_time: {},
+ app_config: { width: "normal" },
+ kiosk: false,
+ capabilities: { terminal: false },
+ auto_instantiated: false,
+ consumer_capabilities: { edit: true, interact: true },
+ }),
+ );
expect(store.get(connectionAtom).state).toBe(ConnectionState.OPEN);
},
);
@@ -377,11 +295,10 @@ describe("connection notice", () => {
beforeEach(() => vi.useFakeTimers());
afterEach(() => vi.useRealTimers());
- function renderNotice() {
+ async function renderNotice() {
const store = createStore();
store.set(connectionAtom, { state: ConnectionState.CONNECTING });
- const transport = makeTransport(WebSocket.OPEN);
- vi.mocked(createConnectionTransport).mockReturnValue(transport);
+ const fake = withTransport();
vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
const Connection = () => {
const { reconnect } = useNotebookSession({
@@ -403,20 +320,17 @@ describe("connection notice", () => {
</ErrorBoundary>
</JotaiProvider>,
);
- const options = getTransportHandlers();
+ await started();
+ const conn = connection(fake);
+ // Messages arrive on an open connection.
+ act(() => conn.open());
const send = (data: NotificationPayload["data"]) =>
- act(() => {
- options.onMessage(
- new MessageEvent("message", {
- data: JSON.stringify({ op: data.op, data }),
- }),
- );
- });
- return { store, transport, options, send };
+ act(() => conn.send(data));
+ return { store, fake, conn, send };
}
- it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", () => {
- const { store, options, send } = renderNotice();
+ it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", async () => {
+ const { store, conn, send } = await renderNotice();
send({
op: "startup-progress",
phase: "preparing-environment",
@@ -456,7 +370,7 @@ describe("connection notice", () => {
expect(
screen.queryByRole("region", { name: "Notebook startup" }),
).not.toBeInTheDocument();
- act(() => options.onClose(new CloseEvent("close")));
+ await act(async () => conn.drop());
act(() => vi.advanceTimersByTime(500));
expect(store.get(connectionAtom)).toEqual({
state: ConnectionState.CONNECTING,
@@ -467,8 +381,8 @@ describe("connection notice", () => {
).not.toBeInTheDocument();
});
- it("restores startup output before appending live chunks and resets it for a new attempt", () => {
- const { store, send } = renderNotice();
+ it("restores startup output before appending live chunks and resets it for a new attempt", async () => {
+ const { store, send } = await renderNotice();
const snapshot = {
op: "startup-progress",
phase: "starting-kernel",
@@ -494,7 +408,7 @@ describe("connection notice", () => {
});
it("restores completed startup output without putting a connected kernel back into startup", async () => {
- const { store, options, send } = renderNotice();
+ const { store, conn, send } = await renderNotice();
send({ op: "reconnected" });
send({
op: "startup-progress",
@@ -512,13 +426,15 @@ describe("connection notice", () => {
screen.queryByRole("region", { name: "Notebook startup" }),
).not.toBeInTheDocument();
- // A new transport starts from the next session's authoritative snapshot.
- await act(async () => options.onOpen(new Event("open")));
+ // A new connection starts from the next session's authoritative snapshot.
+ await act(async () => conn.drop());
+ await act(async () => vi.advanceTimersByTime(2000));
+ await act(async () => conn.open());
expect(store.get(startupProgressAtom)).toBeNull();
});
- it("does not flash a notice when startup finishes within the delay", () => {
- const { send } = renderNotice();
+ it("does not flash a notice when startup finishes within the delay", async () => {
+ const { send } = await renderNotice();
send({
op: "startup-progress",
phase: "preparing-environment",
@@ -546,16 +462,11 @@ describe("connection notice", () => {
it.each(["preparing-environment", "starting-kernel"] as const)(
"keeps a %s failure available until the user retries",
async (phase) => {
- const { store, transport, options, send } = renderNotice();
+ const { store, fake, conn, send } = await renderNotice();
send({ op: "startup-progress", phase, logs: "", log_mode: "replace" });
const error = "A full diagnostic\nwith <stderr> details";
send({ op: "kernel-startup-error", error });
- transport.readyState = WebSocket.CLOSED;
- act(() =>
- options.onClose(
- new CloseEvent("close", { reason: "MARIMO_KERNEL_STARTUP_ERROR" }),
- ),
- );
+ await act(async () => conn.close("MARIMO_KERNEL_STARTUP_ERROR"));
expect(screen.getByRole("status")).toHaveTextContent(
"Kernel failed to start",
);
@@ -566,11 +477,11 @@ describe("connection notice", () => {
expect(screen.getByLabelText("Error details")).toHaveTextContent(error, {
normalizeWhitespace: false,
});
- expect(transport.reconnect).not.toHaveBeenCalled();
+ expect(fake.attempts).toHaveLength(1);
await act(async () =>
fireEvent.click(screen.getByRole("button", { name: "Try again" })),
);
- expect(transport.reconnect).toHaveBeenCalledOnce();
+ expect(fake.attempts).toHaveLength(2);
expect(store.get(kernelStartupErrorAtom)).toBeNull();
expect(
screen.queryByRole("button", { name: "Try again" }),
@@ -590,23 +501,14 @@ describe("connection notice", () => {
);
});
-it("replaces environment state from snapshots, then continues live progress", () => {
+it("replaces environment state from snapshots, then continues live progress", async () => {
const store = createStore();
- vi.mocked(createConnectionTransport).mockClear();
- vi.mocked(createConnectionTransport).mockReturnValue(
- makeTransport(WebSocket.OPEN),
- );
+ const fake = withTransport();
vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
renderConnectionHook(store);
- const options = getTransportHandlers();
+ await started();
function receive(data: NotificationPayload["data"]) {
- act(() =>
- options?.onMessage(
- new MessageEvent("message", {
- data: JSON.stringify({ op: data.op, data }),
- }),
- ),
- );
+ act(() => connection(fake).send(data));
}
receive({
op: "environment-operation",
diff --git a/frontend/src/core/websocket/transports/__tests__/notebook.test.ts b/frontend/src/core/websocket/transports/__tests__/notebook.test.ts
new file mode 100644
index 0000000000..6f48eb2a9a
--- /dev/null
+++ b/frontend/src/core/websocket/transports/__tests__/notebook.test.ts
@@ -0,0 +1,502 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import {
+ NotebookEvents,
+ StreamStopped,
+ type StreamUrl,
+} from "@marimo-team/client";
+import { createStore } from "jotai/vanilla";
+import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
+import { createNotebookClient } from "../../../host/notebook-client";
+import { fixtureMessages } from "../../../host/__tests__/fixtures";
+import { ConnectionState } from "../../../host/connection";
+import { Deferred } from "@/utils/Deferred";
+import {
+ createNotebookTransport,
+ pyodide,
+ sessionSse,
+ websocket,
+} from "../notebook";
+
+const wasm = vi.hoisted(() => ({ enabled: false, consumer: vi.fn() }));
+vi.mock("../../../wasm/utils", () => ({ isWasm: () => wasm.enabled }));
+vi.mock("../../../wasm/bridge", () => ({
+ PyodideBridge: { INSTANCE: { attachMessageConsumer: wasm.consumer } },
+}));
+
+const encoder = new TextEncoder();
+
+/** A WebSocket the test drives. */
+class FakeSocket extends EventTarget {
+ public static readonly opened: FakeSocket[] = [];
+ public readonly url: string;
+ public constructor(url: URL) {
+ super();
+ this.url = String(url);
+ FakeSocket.opened.push(this);
+ }
+ public open() {
+ this.dispatchEvent(new Event("open"));
+ }
+ public receive(text: string) {
+ this.dispatchEvent(new MessageEvent("message", { data: text }));
+ }
+ public close(code = 1006, reason = "") {
+ this.dispatchEvent(Object.assign(new Event("close"), { code, reason }));
+ }
+}
+
+/** An SSE response body the test writes to. */
+function body() {
+ let controller!: ReadableStreamDefaultController<Uint8Array>;
+ const stream = new ReadableStream<Uint8Array>({
+ start(c) {
+ controller = c;
+ },
+ });
+ return {
+ response: new Response(stream, {
+ headers: { "Content-Type": "text/event-stream" },
+ }),
+ push: (text: string) => controller.enqueue(encoder.encode(text)),
+ end: () => controller.close(),
+ };
+}
+
+function collect(events: NotebookEvents<string>) {
+ const received: unknown[] = [];
+ events.subscribe((event) => received.push(event));
+ return received;
+}
+
+/** Drive the real session adapter through either network protocol. */
+function network(transportType: "websocket" | "sse", url: StreamUrl) {
+ const requests: { request: Request; stream: ReturnType<typeof body> }[] = [];
+ vi.stubGlobal("WebSocket", FakeSocket);
+ vi.stubGlobal(
+ "fetch",
+ async (input: RequestInfo | URL, init?: RequestInit) => {
+ const stream = body();
+ requests.push({ request: new Request(input, init), stream });
+ return stream.response;
+ },
+ );
+ const count = () =>
+ transportType === "websocket" ? FakeSocket.opened.length : requests.length;
+ const transport = createNotebookTransport({
+ static: false,
+ transportType,
+ url,
+ headers: () => ({}),
+ });
+ let index = 0;
+ return {
+ transport,
+ count,
+ opened: async () => {
+ await vi.waitFor(() => expect(count()).toBeGreaterThan(index));
+ const next = index++;
+ if (transportType === "websocket") {
+ const socket = FakeSocket.opened[next];
+ socket.open();
+ return {
+ cursor: new URL(socket.url).searchParams.get("cursor"),
+ receive: (frame: { event: string; data: unknown; id?: string }) =>
+ socket.receive(JSON.stringify(frame)),
+ drop: () => socket.close(),
+ stop: () => socket.close(1000, "MARIMO_SHUTDOWN"),
+ };
+ }
+ const { request, stream } = requests[next];
+ return {
+ cursor: request.headers.get("Last-Event-ID"),
+ receive: (frame: { event: string; data: unknown; id?: string }) =>
+ stream.push(
+ `${frame.id === undefined ? "" : `id: ${frame.id}\n`}event: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`,
+ ),
+ drop: stream.end,
+ stop: () =>
+ stream.push(
+ 'event: close\ndata: {"code":1000,"reason":"MARIMO_SHUTDOWN"}\n\n',
+ ),
+ };
+ },
+ };
+}
+
+afterEach(() => {
+ FakeSocket.opened.length = 0;
+ wasm.enabled = false;
+ wasm.consumer.mockReset();
+ vi.unstubAllGlobals();
+ vi.useRealTimers();
+});
+
+describe("websocket", () => {
+ it("resumes with the cursor and reads data with marimo's parser", async () => {
+ vi.useFakeTimers();
+ vi.stubGlobal("WebSocket", FakeSocket);
+ const events = new NotebookEvents(
+ websocket(() => "ws://localhost/ws?session_id=s1&cursor=stale"),
+ { types: ["marimo"] },
+ );
+ const received = collect(events);
+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));
+ const [first] = FakeSocket.opened;
+ first.open();
+ first.receive(
+ '{"event":"marimo","id":"7","data":{"marimo":{"value":NaN}}}',
+ );
+ first.close();
+ await vi.advanceTimersByTimeAsync(2000);
+ expect(FakeSocket.opened.map((socket) => socket.url))
+ .toMatchInlineSnapshot(`
+ [
+ "ws://localhost/ws?session_id=s1",
+ "ws://localhost/ws?session_id=s1&cursor=7",
+ ]
+ `);
+ expect(received).toEqual([
+ { event: "marimo", id: "7", data: { marimo: { value: Number.NaN } } },
+ ]);
+ events.close();
+ });
+
+ it("stops on a close the editor treats as final, with its status", async () => {
+ vi.stubGlobal("WebSocket", FakeSocket);
+ const events = new NotebookEvents(websocket(() => "ws://localhost/ws"));
+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));
+ FakeSocket.opened[0].open();
+ FakeSocket.opened[0].close(3000, "MARIMO_UNAUTHORIZED");
+ const error = await events.closed.catch((error: unknown) => error);
+ expect(error).toBeInstanceOf(StreamStopped);
+ expect((error as StreamStopped).cause).toMatchInlineSnapshot(`
+ {
+ "code": "KERNEL_DISCONNECTED",
+ "reason": "not authorized",
+ "state": "CLOSED",
+ }
+ `);
+ });
+
+ it("passes on a message it cannot read for the stream to reject", async () => {
+ vi.stubGlobal("WebSocket", FakeSocket);
+ const events = new NotebookEvents(websocket(() => "ws://localhost/ws"));
+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));
+ FakeSocket.opened[0].open();
+ FakeSocket.opened[0].receive("{broken");
+ await expect(events.closed).rejects.toThrow("not an event");
+ });
+
+ it("retries a socket that never opens", async () => {
+ vi.useFakeTimers();
+ vi.stubGlobal("WebSocket", FakeSocket);
+ const events = new NotebookEvents(websocket(() => "ws://localhost/ws"));
+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));
+ await vi.advanceTimersByTimeAsync(10_000 + 2000);
+ expect(FakeSocket.opened).toHaveLength(2);
+ events.close();
+ });
+});
+
+describe("sessionSse", () => {
+ it("sends the runtime's headers and the cursor with each request", async () => {
+ vi.useFakeTimers();
+ const first = body();
+ const fetch = vi.fn(
+ async (_input: RequestInfo | URL, _init?: RequestInit) => first.response,
+ );
+ vi.stubGlobal("fetch", fetch);
+ let token = "a";
+ const events = new NotebookEvents(
+ sessionSse(
+ () => "http://localhost/sse?session_id=s1",
+ () => ({ "Marimo-Server-Token": token }),
+ ),
+ );
+ first.push("id: 9\nevent: ready\ndata: {}\n\n");
+ await vi.waitFor(() => expect(events.cursor).toBe("9"));
+ token = "b";
+ first.end();
+ fetch.mockImplementation(async () => body().response);
+ await vi.advanceTimersByTimeAsync(2000);
+ const requests = fetch.mock.calls.map(
+ ([input, init]) => new Request(input, init),
+ );
+ expect(
+ requests.map((request) => ({
+ url: request.url,
+ token: request.headers.get("Marimo-Server-Token"),
+ cursor: request.headers.get("Last-Event-ID"),
+ })),
+ ).toMatchInlineSnapshot(`
+ [
+ {
+ "cursor": null,
+ "token": "a",
+ "url": "http://localhost/sse?session_id=s1",
+ },
+ {
+ "cursor": "9",
+ "token": "b",
+ "url": "http://localhost/sse?session_id=s1",
+ },
+ ]
+ `);
+ events.close();
+ });
+
+ it("stops on a session close frame the editor treats as final", async () => {
+ const stream = body();
+ vi.stubGlobal("fetch", async () => stream.response);
+ const events = new NotebookEvents(
+ sessionSse(
+ () => "http://localhost/sse",
+ () => ({}),
+ ),
+ );
+ stream.push(
+ 'event: close\ndata: {"code":1000,"reason":"MARIMO_SHUTDOWN"}\n\n',
+ );
+ const error = await events.closed.catch((error: unknown) => error);
+ expect((error as StreamStopped).cause).toMatchInlineSnapshot(`
+ {
+ "code": "KERNEL_DISCONNECTED",
+ "reason": "kernel not found",
+ "state": "CLOSED",
+ }
+ `);
+ });
+
+ it.each([
+ ["NaN", Number.NaN],
+ ["Infinity", Number.POSITIVE_INFINITY],
+ ["-Infinity", Number.NEGATIVE_INFINITY],
+ ['{"$bigint":"9007199254740993"}', BigInt("9007199254740993")],
+ ])("reads %s with marimo's parser", async (encoded, value) => {
+ const stream = body();
+ vi.stubGlobal("fetch", async () => stream.response);
+ const events = new NotebookEvents(
+ sessionSse(
+ () => "http://localhost/sse",
+ () => ({}),
+ ),
+ { types: ["marimo"] },
+ );
+ const received = collect(events);
+ onTestFinished(() => events.close());
+ stream.push(`event: marimo\ndata: {"marimo":{"value":${encoded}}}\n\n`);
+ await vi.waitFor(() => expect(received).toHaveLength(1));
+ expect(received).toEqual([
+ { event: "marimo", data: { marimo: { value } } },
+ ]);
+ });
+});
+
+describe.each(["websocket", "sse"] as const)(
+ "%s session identity",
+ (transportType) => {
+ const base =
+ transportType === "websocket"
+ ? "ws://localhost/ws"
+ : "http://localhost/sse";
+
+ it.each(["automatic", "manual"])(
+ "discards the cursor and replica when the session changes on %s reconnect",
+ async (recovery) => {
+ vi.useFakeTimers();
+ let target = `${base}?session_id=s1`;
+ const url = vi.fn(() => target);
+ const connection = network(transportType, url);
+ const store = createStore();
+ const { client, connect } = createNotebookClient(store);
+ const lifetime = new AbortController();
+ onTestFinished(() => lifetime.abort());
+ connect({
+ transport: connection.transport,
+ signal: lifetime.signal,
+ checkHealth: async () => true,
+ onNotification: vi.fn(),
+ });
+ const first = await connection.opened();
+ const snapshot = fixtureMessages("notebook-events.sse");
+ snapshot.forEach(first.receive);
+ await vi.waitFor(() =>
+ expect(store.get(client.notebookAtom)?.id).toBe("n1"),
+ );
+
+ target = `${base}?session_id=s2`;
+ if (recovery === "automatic") {
+ first.drop();
+ await vi.advanceTimersByTimeAsync(2000);
+ } else {
+ first.stop();
+ await vi.waitUntil(
+ () =>
+ store.get(client.connectionAtom).state === ConnectionState.CLOSED,
+ );
+ await client.reconnect();
+ }
+ const second = await connection.opened();
+ expect({
+ cursor: second.cursor,
+ notebook: store.get(client.notebookAtom),
+ document: store.get(client.documentAtom),
+ attachments: store.get(client.attachmentsAtom),
+ }).toEqual({
+ cursor: null,
+ notebook: null,
+ document: null,
+ attachments: [],
+ });
+
+ // A second drop before any records must not resurrect the library's old cursor.
+ second.drop();
+ await vi.advanceTimersByTimeAsync(2000);
+ const third = await connection.opened();
+ expect(third.cursor).toBeNull();
+ for (const frame of snapshot) {
+ third.receive({
+ ...frame,
+ data: JSON.parse(
+ JSON.stringify(frame.data).replaceAll('"n1"', '"n2"'),
+ ),
+ });
+ }
+ await vi.waitFor(() =>
+ expect(store.get(client.notebookAtom)?.id).toBe("n2"),
+ );
+ expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n2");
+ expect(url).toHaveBeenCalledTimes(3);
+ },
+ );
+
+ it("keeps the replica and cursor when only authentication and query ordering change", async () => {
+ vi.useFakeTimers();
+ let target = `${base}?session_id=s1&file=a.py&access_token=a`;
+ const connection = network(transportType, () => target);
+ const store = createStore();
+ const { client, connect } = createNotebookClient(store);
+ const lifetime = new AbortController();
+ onTestFinished(() => lifetime.abort());
+ connect({
+ transport: connection.transport,
+ signal: lifetime.signal,
+ checkHealth: async () => true,
+ onNotification: vi.fn(),
+ });
+ const first = await connection.opened();
+ fixtureMessages("notebook-events.sse").forEach(first.receive);
+ await vi.waitFor(() =>
+ expect(store.get(client.notebookAtom)?.id).toBe("n1"),
+ );
+ const document = store.get(client.documentAtom);
+ const attachments = store.get(client.attachmentsAtom);
+
+ target = `${base}?access_token=b&file=a.py&session_id=s1`;
+ first.drop();
+ await vi.advanceTimersByTimeAsync(2000);
+ const second = await connection.opened();
+ expect(second.cursor).toBe("97");
+ expect(store.get(client.documentAtom)).toBe(document);
+ second.receive({ event: "ready", id: "100", data: {} });
+ await vi.waitFor(() =>
+ expect(store.get(client.notebookAtom)?.id).toBe("n1"),
+ );
+ expect(store.get(client.attachmentsAtom)).toEqual(attachments);
+ });
+
+ it("does not open a connection after cancellation during URL resolution", async () => {
+ vi.useFakeTimers();
+ const target = new Deferred<string>();
+ const url = vi.fn(() => target.promise);
+ const connection = network(transportType, url);
+ const events = new NotebookEvents(connection.transport);
+ onTestFinished(() => events.close());
+ const received = collect(events);
+ await vi.waitFor(() => expect(url).toHaveBeenCalledOnce());
+ events.close();
+ target.resolve(base);
+ await vi.advanceTimersByTimeAsync(0);
+ expect({
+ opened: connection.count(),
+ events: received,
+ status: events.status,
+ }).toEqual({ opened: 0, events: [], status: "closed" });
+ });
+ },
+);
+
+describe("pyodide", () => {
+ it("delivers worker notifications as marimo events and host events as they are", async () => {
+ let consumer: ((message: MessageEvent<string>) => void) | undefined;
+ const events = new NotebookEvents(
+ pyodide((next) => {
+ consumer = next;
+ }),
+ { types: ["notebook", "marimo"] },
+ );
+ const received = collect(events);
+ await vi.waitFor(() => expect(consumer).toBeDefined());
+ const send = (data: string) =>
+ consumer?.(new MessageEvent("message", { data }));
+ send('{"data":{"op":"kernel-ready"}}');
+ send('{"event":"marimo","id":"3","data":{"marimo":{"op":"reconnected"}}}');
+ expect(received).toMatchInlineSnapshot(`
+ [
+ {
+ "data": {
+ "marimo": {
+ "op": "kernel-ready",
+ },
+ },
+ "event": "marimo",
+ },
+ {
+ "data": {
+ "marimo": {
+ "op": "reconnected",
+ },
+ },
+ "event": "marimo",
+ "id": "3",
+ },
+ ]
+ `);
+ events.close();
+ });
+});
+
+describe("createNotebookTransport", () => {
+ const options = {
+ static: false,
+ transportType: "websocket" as const,
+ url: () => "ws://localhost/ws",
+ headers: () => ({}),
+ };
+
+ it.each([
+ ["a static notebook", { ...options, static: true }, "idle"],
+ ["WASM", options, "wasm"],
+ ["SSE", { ...options, transportType: "sse" as const }, "fetch"],
+ ["the default", options, "socket"],
+ ] as const)("follows %s", async (_name, chosen, expected) => {
+ wasm.enabled = expected === "wasm";
+ const fetch = vi.fn(() => new Promise<Response>(() => undefined));
+ vi.stubGlobal("fetch", fetch);
+ vi.stubGlobal("WebSocket", FakeSocket);
+ const events = new NotebookEvents(createNotebookTransport(chosen));
+ await vi.waitFor(() =>
+ expect(
+ {
+ idle:
+ events.status === "connected" && !wasm.consumer.mock.calls.length,
+ wasm: wasm.consumer.mock.calls.length === 1,
+ fetch: fetch.mock.calls.length === 1,
+ socket: FakeSocket.opened.length === 1,
+ }[expected],
+ ).toBe(true),
+ );
+ events.close();
+ });
+});
diff --git a/frontend/src/core/websocket/transports/notebook.ts b/frontend/src/core/websocket/transports/notebook.ts
new file mode 100644
index 0000000000..aa5ce9c85d
--- /dev/null
+++ b/frontend/src/core/websocket/transports/notebook.ts
@@ -0,0 +1,213 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import {
+ type NotebookTransport,
+ sse,
+ StreamStopped,
+ type StreamUrl,
+} from "@marimo-team/client";
+import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
+import { PyodideBridge } from "../../wasm/bridge";
+import { isWasm } from "../../wasm/utils";
+import { classifyCloseEvent } from "../connection-state";
+
+/** The server can be slow to accept when many notebooks are open. */
+const CONNECT_MS = 10_000;
+
+/**
+ * The error that ends a stream on this close, or none to retry.
+ *
+ * `cause` is the connection status the editor shows.
+ */
+function stopOn(close: { code?: number; reason?: string }) {
+ const decision = classifyCloseEvent(close);
+ if (decision.kind === "retry") {
+ return undefined;
+ }
+ const reason = "reason" in decision.status ? decision.status.reason : "";
+ return new StreamStopped(reason, { cause: decision.status });
+}
+
+/** Read a URL provider, stopping the stream when it gives up. */
+async function resolve(url: StreamUrl): Promise<URL | undefined> {
+ try {
+ return new URL(typeof url === "function" ? await url() : url);
+ } catch (error) {
+ if (error instanceof StreamStopped) {
+ throw error;
+ }
+ return undefined;
+ }
+}
+
+/** A resume cursor and replica belong to the session that produced them. */
+function withSessionIdentity(
+ url: StreamUrl,
+ connect: (target: URL) => NotebookTransport,
+): NotebookTransport {
+ let previous: string | undefined;
+ return async (attempt, handlers) => {
+ const target = await resolve(url);
+ if (target === undefined || attempt.signal.aborted) {
+ return;
+ }
+ target.searchParams.delete("cursor");
+ const identity = new URL(target);
+ identity.searchParams.delete("access_token");
+ identity.searchParams.sort();
+ identity.hash = "";
+ const key = identity.toString();
+ let { cursor } = attempt;
+ if (previous !== undefined && previous !== key) {
+ // Reset both the stream's cursor and its subscribers' state.
+ handlers.message({ event: "reset", data: {} });
+ cursor = null;
+ }
+ previous = key;
+ if (!attempt.signal.aborted) {
+ return connect(target)({ ...attempt, cursor }, handlers);
+ }
+ };
+}
+
+/**
+ * Follow a marimo session over its WebSocket route.
+ *
+ * Each attempt opens one socket with the cursor as a query parameter. The
+ * editor's close policy decides which closes end the stream.
+ *
+ * TODO: Notice a connection that died without closing, such as after a laptop
+ * sleeps. `/sse` sends a heartbeat that its silence limit relies on, and
+ * `/ws` drops it. Sending it on `/ws` would let this transport close a
+ * silent socket.
+ */
+export function websocket(url: StreamUrl): NotebookTransport {
+ return withSessionIdentity(
+ url,
+ (target) =>
+ async ({ cursor, signal }, { open, message }) => {
+ if (cursor !== null) {
+ target.searchParams.set("cursor", cursor);
+ }
+ await new Promise<void>((settle, reject) => {
+ const socket = new WebSocket(target);
+ const timeout = setTimeout(() => socket.close(), CONNECT_MS);
+ const abort = () => socket.close();
+ signal.addEventListener("abort", abort, { once: true });
+ socket.addEventListener("open", () => {
+ clearTimeout(timeout);
+ open();
+ });
+ socket.addEventListener("message", ({ data }) =>
+ // marimo's parser reads `NaN`. A message it cannot read arrives as an
+ // empty object, which `NotebookEvents` rejects as not an event.
+ message(jsonParseWithSpecialChar(String(data))),
+ );
+ socket.addEventListener("close", (event) => {
+ clearTimeout(timeout);
+ signal.removeEventListener("abort", abort);
+ const stopped = signal.aborted ? undefined : stopOn(event);
+ if (stopped === undefined) {
+ settle();
+ } else {
+ reject(stopped);
+ }
+ });
+ });
+ },
+ );
+}
+
+/**
+ * Follow a marimo session over its server-sent events route.
+ *
+ * The session's `close` frames carry the same reasons as WebSocket closes.
+ * marimo's parser decodes tagged bigints and non-finite numbers in every frame.
+ */
+export function sessionSse(
+ url: StreamUrl,
+ headers: () => Record<string, string>,
+): NotebookTransport {
+ return withSessionIdentity(url, (target) =>
+ sse(target, {
+ parseData: jsonParseWithSpecialChar,
+ fetch: (input, init) => {
+ const sent = new Headers(init?.headers);
+ for (const [name, value] of Object.entries(headers())) {
+ sent.set(name, value);
+ }
+ return globalThis.fetch(input, { ...init, headers: sent });
+ },
+ stop: (frame) =>
+ frame.event === "close"
+ ? stopOn(frame.data as { code?: number; reason?: string })
+ : undefined,
+ }),
+ );
+}
+
+/** A connection that opens and delivers nothing, for static notebooks. */
+const idle: NotebookTransport = ({ signal }, { open }) =>
+ new Promise((settle) => {
+ open();
+ signal.addEventListener("abort", () => settle(), { once: true });
+ });
+
+/**
+ * Follow the notebook running in the WASM worker.
+ *
+ * The worker sends marimo notifications as `{ data: notification }`, which
+ * arrive as `marimo` events.
+ */
+export function pyodide(
+ attach: (consumer: (message: MessageEvent<string>) => void) => void,
+): NotebookTransport {
+ return ({ signal }, { open, message }) =>
+ new Promise((settle) => {
+ open();
+ attach(({ data }) => {
+ if (signal.aborted) {
+ return;
+ }
+ const value = jsonParseWithSpecialChar(data);
+ // The worker sends notifications without the host's event envelope.
+ message(
+ typeof value === "object" &&
+ value !== null &&
+ !("event" in value) &&
+ "data" in value
+ ? { event: "marimo", data: { marimo: value.data } }
+ : value,
+ );
+ });
+ signal.addEventListener("abort", () => settle(), { once: true });
+ });
+}
+
+/** How the editor follows its notebook. */
+export interface NotebookTransportOptions {
+ static: boolean;
+ transportType: "websocket" | "sse";
+ /** The session route, read before each connection. */
+ url: StreamUrl;
+ /** The runtime's headers, read before each request. */
+ headers: () => Record<string, string>;
+}
+
+/** Choose the transport for the editor's notebook. */
+export function createNotebookTransport(
+ options: NotebookTransportOptions,
+): NotebookTransport {
+ if (options.static) {
+ return idle;
+ }
+ if (isWasm()) {
+ return pyodide((consumer) =>
+ PyodideBridge.INSTANCE.attachMessageConsumer(consumer),
+ );
+ }
+ if (options.transportType === "sse") {
+ return sessionSse(options.url, options.headers);
+ }
+ return websocket(options.url);
+}
diff --git a/frontend/src/core/websocket/useNotebookClient.ts b/frontend/src/core/websocket/useNotebookClient.ts
index c242df7f91..0d894f2a64 100644
--- a/frontend/src/core/websocket/useNotebookClient.ts
+++ b/frontend/src/core/websocket/useNotebookClient.ts
@@ -1,9 +1,9 @@
/* Copyright 2026 Marimo. All rights reserved. */
+import { StreamStopped } from "@marimo-team/client";
import { useStore } from "jotai";
import { useEffect, useMemo } from "react";
import useEvent from "react-use-event-hook";
-import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
import type {
NotificationMessage,
NotificationPayload,
@@ -12,14 +12,16 @@ import {
createNotebookClient,
type NotebookClient,
} from "../host/notebook-client";
-import { classifyCloseEvent } from "./connection-state";
import { notebookClientAtom } from "./state";
import {
- createConnectionTransport,
- type ConnectionTransportOptions,
-} from "./transports/create";
+ createNotebookTransport,
+ type NotebookTransportOptions,
+} from "./transports/notebook";
-type Options = ConnectionTransportOptions & {
+type Options = Omit<NotebookTransportOptions, "url"> & {
+ /** The session route, read before each connection. */
+ url: () => string;
+ /** Wait until the host can accept a connection. */
waitUntilReady: () => Promise<void>;
checkHealth: () => Promise<boolean>;
onNotification: (notification: NotificationPayload) => void;
@@ -37,24 +39,33 @@ export function useNotebookClient(options: Options): NotebookClient {
useEffect(() => {
const lifetime = new AbortController();
+ let needsInitialReadiness = true;
store.set(notebookClientAtom, controller.client);
controller.connect({
- createTransport: (url) =>
- createConnectionTransport({
- url,
- headers,
- static: isStatic,
- transportType,
- }),
- url,
+ transport: createNotebookTransport({
+ static: isStatic,
+ transportType,
+ url: async () => {
+ if (needsInitialReadiness) {
+ // Explicit retries check current health, even if startup failed.
+ needsInitialReadiness = false;
+ try {
+ await waitUntilReady();
+ } catch (error) {
+ throw new StreamStopped("Healthy connection never made", {
+ cause: error,
+ });
+ }
+ }
+ return url();
+ },
+ headers,
+ }),
signal: lifetime.signal,
- waitUntilReady,
checkHealth,
// The host validates the envelope, not the native notification contents.
onNotification: (notification) =>
onNotification({ data: notification as NotificationMessage }),
- decodeJson: jsonParseWithSpecialChar,
- classifyClose: classifyCloseEvent,
});
return () => {
lifetime.abort();
diff --git a/packages/client/TRANSPORTS.md b/packages/client/TRANSPORTS.md
index 3d1ad49e78..d4bac3fa7b 100644
--- a/packages/client/TRANSPORTS.md
+++ b/packages/client/TRANSPORTS.md
@@ -15,7 +15,8 @@ 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.
+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
@@ -49,5 +50,9 @@ const events = new NotebookEvents(
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](src/transport/frame.ts) for the function and
event types.
diff --git a/packages/client/src/__tests__/notebook-events.test.ts b/packages/client/src/__tests__/notebook-events.test.ts
index baa43c4d32..0b6c96f0e4 100644
--- a/packages/client/src/__tests__/notebook-events.test.ts
+++ b/packages/client/src/__tests__/notebook-events.test.ts
@@ -55,6 +55,18 @@ function answering(...responses: Response[]) {
return { fetch, sent };
}
+/** A transport whose connections deliver an event and drop after `uptime`. */
+function dropsAfter(uptime: number) {
+ let opened = 0;
+ const transport: NotebookTransport = (_attempt, { open, message }) => {
+ opened += 1;
+ open();
+ message({ event: "marimo", data: {}, id: String(opened) });
+ return new Promise((resolve) => setTimeout(resolve, uptime));
+ };
+ return { transport, opened: () => opened };
+}
+
function collect<K extends string>(events: NotebookEvents<K>) {
const received: NotebookEvent<K>[] = [];
events.subscribe((event) => received.push(event));
@@ -253,6 +265,47 @@ describe("NotebookEvents", () => {
events.close();
});
+ it("gives up on a host that drops each connection soon after opening", async () => {
+ vi.useFakeTimers();
+ const { transport, opened } = dropsAfter(1000);
+ const events = new NotebookEvents(transport, { types: ["marimo"] });
+ await vi.advanceTimersByTimeAsync(200_000);
+ expect(events.status).toBe("closed");
+ expect(opened()).toBe(11);
+ });
+
+ it("keeps following a host whose connections stay up", async () => {
+ vi.useFakeTimers();
+ const { transport, opened } = dropsAfter(5000);
+ const events = new NotebookEvents(transport, { types: ["marimo"] });
+ await vi.advanceTimersByTimeAsync(200_000);
+ expect(events.status).not.toBe("closed");
+ expect(opened()).toBeGreaterThan(11);
+ events.close();
+ });
+
+ it("ignores a connection that reports after its attempt ended", async () => {
+ let late: Parameters<NotebookTransport>[1] | undefined;
+ const transport: NotebookTransport = async (_attempt, handlers) => {
+ late ??= handlers;
+ };
+ const statuses: string[] = [];
+ const events = new NotebookEvents(transport, {
+ types: ["marimo"],
+ onStatus: (status) => statuses.push(status),
+ });
+ const received = collect(events);
+ await vi.waitFor(() => expect(late).toBeDefined());
+ // Let the attempt end. The stream is then waiting to reconnect.
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ late?.open();
+ late?.message({ event: "marimo", data: {}, id: "9" });
+ expect(statuses).toEqual([]);
+ expect(received).toEqual([]);
+ expect(events.cursor).toBeNull();
+ events.close();
+ });
+
it("delivers reset before replacing an interrupted snapshot", async () => {
vi.useFakeTimers();
const first = body();
@@ -605,6 +658,33 @@ describe("NotebookEvents", () => {
});
describe("sse", () => {
+ it("decodes raw data before stop and delivery, retaining text on parse errors", async () => {
+ const stream = body();
+ const message = vi.fn();
+ const stop = vi.fn(() => undefined);
+ const transport = sse(url, {
+ fetch: answering(stream.response).fetch,
+ parseData: (text) =>
+ JSON.parse(text, (_key, value) =>
+ typeof value === "number" ? BigInt(value) : value,
+ ),
+ stop,
+ });
+ stream.push('event: marimo\ndata: {"marimo":\ndata: {"value":42}}\n\n');
+ stream.push("event: custom\ndata: plain text\n\n");
+ stream.end();
+ await transport(
+ { cursor: null, signal: new AbortController().signal },
+ { open: vi.fn(), message },
+ );
+ const frames = [
+ { event: "marimo", data: { marimo: { value: 42n } } },
+ { event: "custom", data: "plain text" },
+ ];
+ expect(stop.mock.calls).toEqual(frames.map((frame) => [frame]));
+ expect(message.mock.calls).toEqual(frames.map((frame) => [frame]));
+ });
+
it("reads a URL given as a function before each connection", async () => {
vi.useFakeTimers();
const first = body();
diff --git a/packages/client/src/transport/events.ts b/packages/client/src/transport/events.ts
index f98e428e46..892cd926fc 100644
--- a/packages/client/src/transport/events.ts
+++ b/packages/client/src/transport/events.ts
@@ -11,12 +11,21 @@ import {
report,
} from "./stream.ts";
-/** Attempts in a row without an event before the stream gives up. */
+/** Failed attempts in a row before the stream gives up. */
const ATTEMPTS = 10;
-/** The delay before reconnecting, which grows with each attempt in a row. */
+/** How long a connection stays open after its first event to count as healthy. */
+const HEALTHY_MS = 5000;
+
+/**
+ * The delay before reconnecting, which grows with each failed attempt in a row.
+ *
+ * Ten attempts wait about 77 seconds in all. Each delay varies by a quarter
+ * either way, so clients that lost the same host do not reconnect in step.
+ */
function delay(attempt: number): number {
- return Math.min(1000 * 1.3 ** attempt, 10_000);
+ const backoff = Math.min(1000 * 1.5 ** (attempt - 1), 15_000);
+ return backoff * (0.75 + Math.random() / 2);
}
/** Whether a stream is receiving events. */
@@ -56,7 +65,8 @@ function sleep(ms: number, signal: AbortSignal): Promise<void> {
*
* - It starts with a snapshot that ends in `ready`, then delivers changes.
* - After a dropped connection it resumes from its cursor, backing off between
- * attempts. It stops after ten attempts in a row without a message.
+ * attempts. It stops after ten failed attempts in a row. An attempt fails
+ * unless its connection stayed open for five seconds after its first event.
* - When it cannot resume, it delivers `reset` and a fresh snapshot follows.
* The caller discards what it built on `reset`.
*/
@@ -229,21 +239,27 @@ export class Events<
const { signal } = this.#controller;
let attempt = 0;
while (!signal.aborted) {
+ // Callbacks from an attempt that ended are ignored.
+ let current = true;
+ let healthy = false;
+ let uptime: ReturnType<typeof setTimeout> | undefined;
try {
const cursor = this.#stream.resume();
await transport(
{ cursor, signal },
{
open: () => {
- if (this.#settle !== undefined) {
+ if (current && this.#settle !== undefined) {
this.#setStatus("connected");
}
},
message: (message) => {
- if (this.#settle === undefined) {
+ if (!current || this.#settle === undefined) {
return;
}
- attempt = 0;
+ uptime ??= setTimeout(() => {
+ healthy = true;
+ }, HEALTHY_MS);
try {
this.#stream.receive(message);
} catch (error) {
@@ -257,12 +273,17 @@ export class Events<
} catch (error) {
this.#finish()?.reject(error);
return;
+ } finally {
+ current = false;
+ clearTimeout(uptime);
}
if (signal.aborted) {
return;
}
this.#setStatus("connecting");
- attempt += 1;
+ // A host that drops each connection soon after opening it still runs
+ // out of attempts.
+ attempt = healthy ? 1 : attempt + 1;
if (attempt > ATTEMPTS) {
this.#finish()?.reject(
new StreamStopped("The host could not be reached"),
diff --git a/packages/client/src/transport/frame.ts b/packages/client/src/transport/frame.ts
index e0a376b37c..a1ab30a5ba 100644
--- a/packages/client/src/transport/frame.ts
+++ b/packages/client/src/transport/frame.ts
@@ -45,9 +45,9 @@ export interface Handlers {
* The event stream calls it again for each attempt. It resolves when the
* connection ended and another attempt makes sense. It rejects when the
* stream should stop, preferably with a `StreamStopped` that says why, and
- * `closed` rejects with the same error. It sends the cursor however its host
- * expects, and leaves reconnecting, validation, and the cursor's value to
- * the event stream.
+ * `closed` rejects with the same error. Calls to the handlers after it
+ * settles are ignored. It sends the cursor however its host expects, and
+ * leaves reconnecting, validation, and the cursor's value to the event stream.
*/
export type Transport = (attempt: Attempt, handlers: Handlers) => Promise<void>;
diff --git a/packages/client/src/transport/sse.ts b/packages/client/src/transport/sse.ts
index e8be036df8..1cc4eb76ab 100644
--- a/packages/client/src/transport/sse.ts
+++ b/packages/client/src/transport/sse.ts
@@ -9,7 +9,7 @@ const SILENCE_MS = 45_000;
/** Parse server-sent events from decoded text. */
export class ServerSentEventStream extends TransformStream<string, Frame> {
- public constructor() {
+ public constructor(parseData: (text: string) => unknown = JSON.parse) {
let buffer = "";
let event = "";
let data: string[] = [];
@@ -19,7 +19,7 @@ export class ServerSentEventStream extends TransformStream<string, Frame> {
const text = data.join("\n");
let value: unknown = text;
try {
- value = JSON.parse(text);
+ value = parseData(text);
} catch {
// Unknown events need not carry JSON.
}
@@ -80,8 +80,10 @@ export type StreamUrl =
| URL
| (() => string | URL | Promise<string | URL>);
-/** How `sse` reaches its host and which frames end the stream. */
+/** How `sse` reaches its host, decodes data, and ends the stream. */
export interface SseOptions extends ClientOptions {
+ /** Decode each frame's data. Defaults to JSON.parse; on error, keep the text. */
+ readonly parseData?: (text: string) => unknown;
/**
* Decide whether a frame outside the protocol ends the stream.
*
@@ -157,7 +159,7 @@ export function sse(url: StreamUrl, options: SseOptions = {}): Transport {
const reader = response.body
.pipeThrough(heard)
.pipeThrough(new TextDecoderStream())
- .pipeThrough(new ServerSentEventStream())
+ .pipeThrough(new ServerSentEventStream(options.parseData))
.getReader();
controller.signal.addEventListener("abort", () => void reader.cancel(), {
once: true,