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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Introduce a notebook backend with a static implementation (#11473)
Trevor Manz20157db4a61c
diff --git a/frontend/src/core/host/__tests__/static.test.ts b/frontend/src/core/host/__tests__/static.test.tsnew file mode 100644index 0000000000..505869fdc1--- /dev/null+++ b/frontend/src/core/host/__tests__/static.test.ts@@ -0,0 +1,167 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { createNotebookReducer, NotebookEvents } from "@marimo-team/client";+import * as Protocol from "@marimo-team/client/protocol";+import { afterEach, assert, describe, expect, it, vi } from "vitest";+import { document as documentResource } from "../resources/document";+import {+ createStaticNotebookBackend,+ type StaticNotebookSnapshot,+} from "../static";+import { fixtureEvents } from "./fixtures";++function snapshot(): StaticNotebookSnapshot {+ const events = fixtureEvents("notebook-events.sse");+ const notebook = events.find((event) => event.event === "notebook")?.data+ .notebook;+ const document = events.find((event) => event.event === "document")?.data+ .document;+ assert(notebook && document);+ return {+ notebook,+ document,+ cells: events.flatMap((event) =>+ event.event === "cell" ? [event.data.cell] : [],+ ),+ };+}++const streams: NotebookEvents[] = [];+afterEach(async () => {+ const closed = streams.splice(0);+ closed.forEach((stream) => stream.close());+ await Promise.all(closed.map((stream) => stream.closed));+ vi.useRealTimers();+});++async function read(+ backend: ReturnType<typeof createStaticNotebookBackend>,+ cursor?: string,+) {+ const stream = new NotebookEvents(backend.transport, { cursor });+ streams.push(stream);+ const events: Protocol.EventOutput[] = [];+ await new Promise<void>((resolve, reject) => {+ stream.subscribe((event) => {+ events.push(Protocol.Event.parse(event));+ if (event.event === "ready") {+ resolve();+ }+ }, reject);+ });+ return { stream, events };+}++describe("static notebook backend", () => {+ it("supplies a complete document through the normal event reader and reducer", async () => {+ const source = snapshot();+ const { stream, events } = await read(createStaticNotebookBackend(source));+ const reducer = createNotebookReducer({ document: documentResource });+ const state = events.reduce(reducer.reduce, reducer.initial);+ expect(events.map((event) => event.event)).toEqual([+ "notebook",+ "cell",+ "cell",+ "cell",+ "document",+ "ready",+ ]);+ expect(state.notebook).toEqual({ ...source.notebook, operations: [] });+ expect(state.resources.document.current).toEqual({+ revision: source.document,+ cells: new Map(source.cells.map((cell) => [cell.id, cell])),+ });+ expect(stream.status).toBe("connected");+ });++ it("preserves withheld source and its revision metadata", async () => {+ const source = snapshot();+ const cells = source.cells.map((cell) => ({ ...cell, code: null }));+ const { events } = await read(+ createStaticNotebookBackend({ ...source, cells }),+ );+ expect(+ events+ .filter((event) => event.event === "cell")+ .map((event) => event.data.cell),+ ).toEqual(cells);+ expect(+ events.find((event) => event.event === "document")?.data.document,+ ).toEqual(source.document);+ });++ it("serves an empty document as available", async () => {+ const source = snapshot();+ const document = { ...source.document, order: [] };+ const { events } = await read(+ createStaticNotebookBackend({ ...source, document, cells: [] }),+ );+ const reducer = createNotebookReducer({ document: documentResource });+ expect(+ events.reduce(reducer.reduce, reducer.initial).resources.document.current,+ ).toEqual({+ revision: document,+ cells: new Map(),+ });+ });++ it("keeps independent readers open without polling or reconnecting", async () => {+ vi.useFakeTimers();+ const backend = createStaticNotebookBackend(snapshot());+ const first = await read(backend);+ const second = await read(backend);+ first.stream.close();+ await first.stream.closed;+ await vi.advanceTimersByTimeAsync(60_000);+ expect(second.events).toEqual(first.events);+ expect(second.stream.status).toBe("connected");+ expect(vi.getTimerCount()).toBe(0);+ });++ it("resets a resume cursor before replaying its snapshot", async () => {+ const { events } = await read(+ createStaticNotebookBackend(snapshot()),+ "previous-10",+ );+ expect(events[0]).toEqual({ event: "reset", data: {} });+ expect(events.at(-1)).toEqual({ event: "ready", id: "static", data: {} });+ });++ it("advertises no mutations and returns a protocol failure for direct edits", async () => {+ const backend = createStaticNotebookBackend(snapshot());+ expect(await backend.client.edit([])).toEqual({+ ok: false,+ status: 501,+ problem: {+ type: "tag:marimo.io,2026:host/unsupported-operation",+ title: "Unsupported operation",+ status: 501,+ detail: "Static notebooks do not support editing",+ },+ });+ });++ it("respects cancellation before opening, during delivery, and for commands", async () => {+ const backend = createStaticNotebookBackend(snapshot());+ const before = new AbortController();+ before.abort();+ const open = vi.fn();+ const message = vi.fn();+ await backend.transport(+ { cursor: null, signal: before.signal },+ { open, message },+ );+ expect(open).not.toHaveBeenCalled();+ expect(message).not.toHaveBeenCalled();+ await expect(+ backend.client.edit([], { signal: before.signal }),+ ).rejects.toBe(before.signal.reason);+ const during = new AbortController();+ message.mockImplementation(() => during.abort());+ await backend.transport(+ { cursor: null, signal: during.signal },+ { open, message },+ );+ expect(message).toHaveBeenCalledOnce();+ });+});diff --git a/frontend/src/core/host/backend.ts b/frontend/src/core/host/backend.tsnew file mode 100644index 0000000000..e019aac380--- /dev/null+++ b/frontend/src/core/host/backend.ts@@ -0,0 +1,10 @@+/* Copyright 2026 Marimo. All rights reserved. */++import type { NotebookClient, NotebookTransport } from "@marimo-team/client";++/** Events and commands for the same notebook, independent of React or a replica. */+export interface NotebookBackend {+ readonly transport: NotebookTransport;+ /** Method presence is not permission; the notebook advertises its operations. */+ readonly client: Pick<NotebookClient, "edit">;+}diff --git a/frontend/src/core/host/static.ts b/frontend/src/core/host/static.tsnew file mode 100644index 0000000000..5b60921710--- /dev/null+++ b/frontend/src/core/host/static.ts@@ -0,0 +1,70 @@+/* Copyright 2026 Marimo. All rights reserved. */++import type * as Protocol from "@marimo-team/client/protocol";+import type { NotebookBackend } from "./backend";++/** A document snapshot with its own identity and revision metadata. */+export interface StaticNotebookSnapshot {+ readonly notebook: Omit<Protocol.Notebook, "operations">;+ readonly document: Protocol.Document;+ readonly cells: readonly Protocol.Cell[];+}++/**+ * Serve a document without a server, runtime, or mutation operations.+ * Callers and readers must treat the snapshot records as immutable.+ */+export function createStaticNotebookBackend(+ snapshot: StaticNotebookSnapshot,+): NotebookBackend {+ const frames: Protocol.Event[] = [+ {+ event: "notebook",+ data: { notebook: { ...snapshot.notebook, operations: [] } },+ },+ ...snapshot.cells.map((cell): Protocol.CellEvent => ({+ event: "cell",+ data: { cell },+ })),+ { event: "document", data: { document: snapshot.document } },+ { event: "ready", id: "static", data: {} },+ ];++ return {+ transport: ({ cursor, signal }, { open, message }) =>+ new Promise((resolve) => {+ if (signal.aborted) {+ resolve();+ return;+ }+ // Finishing would ask NotebookEvents to reconnect. A snapshot stays open+ // until its reader closes, even though there are no more updates.+ signal.addEventListener("abort", () => resolve(), { once: true });+ open();+ if (cursor !== null && !signal.aborted) {+ message({ event: "reset", data: {} });+ }+ for (const frame of frames) {+ if (signal.aborted) {+ return;+ }+ message(frame);+ }+ }),+ client: {+ edit: async (_changes, options) => {+ options?.signal?.throwIfAborted();+ return {+ ok: false,+ status: 501,+ problem: {+ type: "tag:marimo.io,2026:host/unsupported-operation",+ title: "Unsupported operation",+ status: 501,+ detail: "Static notebooks do not support editing",+ },+ };+ },+ },+ };+}