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.

3.8 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */

/** The backend the editor follows, chosen once for its mode. */

import { NotebookClient, StreamStopped } from "@marimo-team/client";
import type { NotebookId } from "@marimo-team/client/protocol";
import type { NotebookBackend } from "../notebook/replica";
import { PyodideBridge } from "../wasm/bridge";
import { isWasm } from "../wasm/utils";
import { sessionSse, websocket, withHeaders } from "../transports/server";
import {
  createStaticNotebookBackend,
  emptySnapshot,
  type StaticNotebookSnapshot,
  startWithSnapshot,
} from "../transports/static";

/** How the editor follows its notebook. */
export interface EditorBackendOptions {
  static: boolean;
  /** The notebook the page was served with, shown until the host answers. */
  snapshot: StaticNotebookSnapshot | null;
  transportType: "websocket" | "sse";
  /** The session route, read before each connection. */
  url: () => string;
  /** The runtime's headers, read before each request. */
  headers: () => Record<string, string>;
  /** The host URL of a notebook the stream reported. */
  notebookUrl: (notebookId: NotebookId) => URL;
  /** Wait until the host can accept the first connection. */
  waitUntilReady: () => Promise<void>;
  /** Whether the host is reachable before an explicit reconnect. */
  checkHealth: () => Promise<boolean>;
}

/**
 * Read the session route once the host has started.
 *
 * Every connection waits for the same startup. Once it settles, even by
 * giving up, connections read the route directly. An explicit reconnect
 * checks the host's health instead.
 */
function afterStartup({
  url,
  waitUntilReady,
}: Pick<EditorBackendOptions, "url" | "waitUntilReady">) {
  let startup: Promise<void> | undefined;
  let settled = false;
  return async () => {
    if (!settled) {
      startup ??= waitUntilReady().finally(() => {
        settled = true;
      });
      try {
        await startup;
      } catch (error) {
        throw new StreamStopped("Healthy connection never made", {
          cause: error,
        });
      }
    }
    return url();
  };
}

/**
 * Follow the notebook running in the WASM worker.
 *
 * The worker's backend exists once the worker has started, so the first
 * connection creates it. Commands are only for a notebook its stream reported.
 */
function wasm(): NotebookBackend {
  let backend: Promise<NotebookBackend> | undefined;
  let started: NotebookBackend | undefined;
  return {
    transport: async (attempt, handlers) => {
      backend ??= PyodideBridge.INSTANCE.createNotebookBackend();
      try {
        started = await backend;
      } catch (error) {
        throw new StreamStopped("The WASM notebook did not start", {
          cause: error,
        });
      }
      return started.transport(attempt, handlers);
    },
    notebook: (id) => {
      if (started === undefined) {
        throw new Error("The WASM notebook has not started");
      }
      return started.notebook(id);
    },
  };
}

/** Choose the backend for the editor's notebook. */
export function createEditorBackend(
  options: EditorBackendOptions,
): NotebookBackend {
  if (options.static) {
    return createStaticNotebookBackend(
      options.snapshot ?? emptySnapshot("static"),
    );
  }
  const live = isWasm() ? wasm() : server(options);
  return options.snapshot ? startWithSnapshot(options.snapshot, live) : live;
}

/** Follow the notebook on the server, over SSE or a WebSocket. */
function server(options: EditorBackendOptions): NotebookBackend {
  const url = afterStartup(options);
  return {
    transport:
      options.transportType === "sse"
        ? sessionSse(url, options.headers)
        : websocket(url),
    notebook: (id) =>
      new NotebookClient(options.notebookUrl(id), {
        fetch: withHeaders(options.headers),
      }),
    checkHealth: options.checkHealth,
  };
}