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.

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

/** What a backend's stream has confirmed about a notebook, kept in atoms. */

import { Logger } from "@/utils/Logger";
import {
  createNotebookReducer,
  type NotebookEvent,
  NotebookEvents,
  StreamStopped,
} from "@marimo-team/client";
import type { Attachment, NotebookOutput } from "@marimo-team/client/protocol";
import { type Atom, atom, type createStore } from "jotai/vanilla";
import { z } from "zod";
import type { NotebookBackend } from "./backend";
import {
  ConnectionClosedReason,
  ConnectionState,
  type ConnectionStatus,
} from "./connection";
import { attachments } from "./resources/attachments";
import { type Document, document } from "./resources/document";

/** 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 notebook as its backend's stream reports it, kept current while connected. */
export interface NotebookReplica {
  /** Connection status, independent of application session readiness. */
  readonly connectionAtom: Atom<ConnectionStatus>;
  /** Identity and capabilities, available while the stream is connected and ready. */
  readonly notebookAtom: Atom<NotebookOutput | null>;
  /**
   * The most recently confirmed document.
   *
   * Null until a snapshot is complete, after reset or removal, and on
   * connections without host document events. A temporary disconnection
   * retains the last document. Partial updates are not exposed.
   */
  readonly documentAtom: Atom<Document | null>;
  /**
   * The backend this replica follows, or null while not connected.
   *
   * Its commands reach the host that confirmed `documentAtom`. A temporary
   * disconnection keeps it. Connecting again or disconnecting replaces it.
   */
  readonly backendAtom: Atom<NotebookBackend | null>;
  /** Live attachments, empty until the stream is ready or while disconnected. */
  readonly attachmentsAtom: Atom<readonly Attachment[]>;
  /**
   * Follow a backend, replacing any current connection.
   *
   * The returned function ends this connection and clears the replica.
   * It does nothing once another connection has replaced this one.
   */
  connect(
    backend: NotebookBackend,
    options: {
      /** Handle a native marimo notification. Its payload has not been validated. */
      onNotification: (notification: unknown) => void;
    },
  ): () => void;
  /** Restore the current connection after its stream closed, if the host is healthy. */
  reconnect(): Promise<void>;
}

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 replica without connecting it. */
export function createNotebookReplica(
  store: ReturnType<typeof createStore>,
): NotebookReplica {
  // `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,
  });
  // One atom holds the whole stream, which resource atoms derive from.
  const reducer = createNotebookReducer({ document, attachments });
  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(presentAtom) ? get(streamAtom).notebook : null,
  );
  const documentAtom = atom(
    (get) => get(streamAtom).resources.document.current,
  );
  const attachmentsAtom = atom((get) =>
    get(presentAtom)
      ? get(streamAtom).resources.attachments
      : attachments.initial,
  );
  const backendAtom = atom<NotebookBackend | null>(null);
  /** The connection this replica follows. Connecting again ends it. */
  let current: { end(): void; reconnect(): Promise<void> } | undefined;

  function setStatus(status: ConnectionStatus) {
    store.set(readyAtom, false);
    store.set(connectionAtom, status);
  }

  /** Drop what the stream reported and show `status`. */
  function clear(status: ConnectionStatus) {
    store.set(streamAtom, reducer.initial);
    setStatus(status);
  }

  return {
    connectionAtom,
    notebookAtom,
    documentAtom,
    backendAtom,
    attachmentsAtom,
    connect,
    reconnect: async () => current?.reconnect(),
  };

  function connect(
    connected: NotebookBackend,
    { onNotification }: { onNotification: (notification: unknown) => void },
  ) {
    current?.end();
    const lifetime = new AbortController();
    const { signal } = lifetime;
    const checkHealth = connected.checkHealth ?? (async () => true);
    store.set(backendAtom, connected);
    const { transport } = connected;
    let events: NotebookEvents<(typeof TYPES)[number]> | undefined;
    let checkingHealth = false;
    // Whether the replica still holds the state the last cursor describes.
    let resumable = 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 stopMalformed(source: NotebookEvents<string>) {
      source.close();
      // The cursor can already include an event the replica rejected.
      resumable = false;
      clear(malformed);
    }

    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;
      }
      try {
        store.set(streamAtom, reducer.reduce(store.get(streamAtom), event));
      } catch (error) {
        // 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 === "ready" || event.event === "reset") {
        store.set(readyAtom, event.event === "ready");
      }
    }

    const reconnect = async () => {
      if (signal.aborted || checkingHealth || events?.status !== "closed") {
        return;
      }
      checkingHealth = true;
      setStatus({ state: ConnectionState.CONNECTING });
      try {
        const healthy = await checkHealth();
        if (signal.aborted) {
          return;
        }
        if (!healthy) {
          setStatus(disconnected);
          return;
        }
        follow(resumable ? (events.cursor ?? undefined) : undefined);
      } catch (error) {
        if (!signal.aborted) {
          Logger.error("Notebook health check failed", error);
          setStatus(disconnected);
        }
      } finally {
        checkingHealth = false;
      }
    };

    const connection = {
      end: () => {
        if (signal.aborted) {
          return;
        }
        lifetime.abort();
        if (current === connection) {
          current = undefined;
          store.set(backendAtom, null);
        }
        clear({ state: ConnectionState.NOT_STARTED });
      },
      reconnect,
    };
    current = connection;
    setStatus({ state: ConnectionState.CONNECTING });
    follow();
    return connection.end;
  }
}