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.

22.4 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */
/* oxlint-disable typescript/no-explicit-any */

import { createRPCRequestHandler } from "rpc-anywhere";
import { toast } from "@/components/ui/use-toast";
import { userConfigAtom } from "@/core/config/config";
import { serializeBlob } from "@/utils/blob";
import { Deferred } from "@/utils/Deferred";
import { throwNotImplemented } from "@/utils/functions";
import { Logger } from "@/utils/Logger";
import { reloadSafe } from "@/utils/reload-safe";
import { once } from "@/utils/once";
import { generateUUID } from "@/utils/uuid";
import { createModuleWorker } from "@/utils/worker";
import { notebookIsRunningAtom } from "../cells/cells";
import { flushDocument } from "../cells/document";
import { createWasmNotebookBackend } from "../transports/wasm";
import type { ClientCommand } from "../kernel/messages";
import { getInitialAppMode } from "../mode";
import { API } from "../network/api";
import { withDevAssetUrl } from "../network/export-asset-url";
import type {
  EditRequests,
  EnvironmentInfo,
  ExportAsHTMLRequest,
  ExportAsMarkdownRequest,
  ExportAsScriptRequest,
  ExportedFile,
  FileCopyResponse,
  FileCreateResponse,
  FileDeleteResponse,
  FileDetailsResponse,
  FileListResponse,
  FileRootsResponse,
  FileMoveResponse,
  FileSearchResponse,
  FileUpdateResponse,
  FormatResponse,
  RunRequests,
  SaveUserConfigurationRequest,
  Snippets,
} from "../network/types";
import { filenameAtom } from "../saving/file-state";
import { store } from "../state/jotai";
import { PyodideRouter } from "./router";
import { getWorkerRPC, type PersistNotebookRequest } from "./rpc";
import { getWasmRuntimeConfig } from "./runtime-config";
import { createShareableLink } from "./share";
import { wasmInitStateAtom } from "./state";
import { fallbackFileStore, notebookFileStore } from "./store";
import { isWasm } from "./utils";
import saveWorkerUrl from "./worker/save-worker.ts?worker&url";
import workerUrl from "./worker/worker.ts?worker&url";
import { CUSTOM_CONTROLLER_SUFFIX } from "./worker/constants";
import type { SaveWorkerSchema } from "./worker/save-worker";
import type { WorkerSchema } from "./worker/worker";

type SaveWorker = ReturnType<
  typeof getWorkerRPC<SaveWorkerSchema>
>["proxy"]["request"];

export class PyodideBridge implements RunRequests, EditRequests {
  public static get INSTANCE(): PyodideBridge {
    const KEY = "_marimo_private_PyodideBridge";
    if (!window[KEY]) {
      window[KEY] = new PyodideBridge();
    }
    return window[KEY] as PyodideBridge;
  }

  private rpc!: ReturnType<typeof getWorkerRPC<WorkerSchema>>;
  private saveRpc: SaveWorker | undefined;
  private notebookConsumers = new Map<string, (event: unknown) => void>();
  private interruptBuffer?: Uint8Array;

  public initialized = new Deferred<void>();

  private getSaveWorker(): SaveWorker {
    if (getInitialAppMode() === "read") {
      Logger.debug("Using partially disabled SaveWorker in read-mode");
      return {
        readFile: throwNotImplemented,
        readNotebook: async () => (await notebookFileStore.readFile()) ?? "",
        writeNotebook: throwNotImplemented,
      };
    }

    const runtimeConfig = getWasmRuntimeConfig();

    // Create save worker
    const saveWorker = createModuleWorker(
      new URL(saveWorkerUrl, import.meta.url),
      {
        // Pass the optional custom-controller capability to the worker.
        name: getWasmWorkerName(),
      },
    );

    const rpc = getWorkerRPC<SaveWorkerSchema>(saveWorker, undefined, Infinity);
    rpc.send.bootstrap(runtimeConfig);
    return rpc.proxy.request;
  }

  private constructor() {
    if (!isWasm()) {
      return;
    }

    const runtimeConfig = getWasmRuntimeConfig();

    // Create a worker
    const worker = createModuleWorker(new URL(workerUrl, import.meta.url), {
      // Pass the optional custom-controller capability to the worker.
      name: getWasmWorkerName(),
    });

    // Create the RPC
    this.rpc = getWorkerRPC<WorkerSchema>(
      worker,
      createRPCRequestHandler({
        persistNotebook: async (snapshot: PersistNotebookRequest) => {
          if (!this.saveRpc) {
            throw new Error("Notebook storage is not initialized");
          }
          await this.saveRpc.writeNotebook(snapshot);
          notebookFileStore.saveFile(snapshot.contents);
          fallbackFileStore.saveFile(snapshot.contents);
          return null;
        },
      }),
      // Synchronous Python execution can block worker requests indefinitely.
      Infinity,
    );
    this.rpc.send.bootstrap(runtimeConfig);

    this.rpc.addMessageListener("notebookEvent", ({ id, event }) => {
      this.notebookConsumers.get(id)?.(JSON.parse(event));
    });

    // Listeners
    this.rpc.addMessageListener("ready", () => {
      this.startSession();
    });
    this.rpc.addMessageListener("initialized", () => {
      // Wait until the worker is ready to create the save worker
      // By initializing after, we get hits on cached network requests
      this.saveRpc = this.getSaveWorker();
      this.setInterruptBuffer();
      store.set(wasmInitStateAtom, { kind: "ready" });
      this.initialized.resolve();
    });
    this.rpc.addMessageListener("initializingMessage", ({ message }) => {
      // Only bump the progress label while still loading — if we've already
      // reached "ready" or "error", a late message shouldn't roll us back.
      const current = store.get(wasmInitStateAtom);
      if (current.kind === "loading") {
        store.set(wasmInitStateAtom, { kind: "loading", message });
      }
    });
    this.rpc.addMessageListener("initializedError", ({ error }) => {
      // If already initialized, surface as a toast and leave the deferred /
      // init status alone — the worker is healthy, this is a runtime error.
      if (this.initialized.status === "resolved") {
        Logger.error(error);
        toast({
          title: "Error initializing",
          description: error,
          variant: "danger",
        });
        return;
      }
      store.set(wasmInitStateAtom, { kind: "error", message: error });
      this.initialized.reject(new Error(error));
    });
  }

  private async startSession() {
    // Pass the code to the worker
    // If a filename is provided, it will be used to save the file
    // If no filename is provided, the file will not be saved

    const code = await notebookFileStore.readFile();
    const fallbackCode = await fallbackFileStore.readFile();
    const filename = store.get(filenameAtom) ?? PyodideRouter.getFilename();
    const userConfig = store.get(userConfigAtom);

    const queryParameters: Record<string, string | string[]> = {};
    const searchParams = new URLSearchParams(window.location.search);
    for (const key of searchParams.keys()) {
      const value = searchParams.getAll(key);
      queryParameters[key] = value.length === 1 ? value[0] : value;
    }

    await this.rpc.proxy.request.startSession({
      queryParameters: queryParameters,
      code: code || fallbackCode || "",
      filename,
      userConfig: {
        ...userConfig,
        runtime: {
          ...userConfig.runtime,
          // Force auto_instantiate to true if the initial mode is read
          auto_instantiate:
            getInitialAppMode() === "read"
              ? true
              : userConfig.runtime.auto_instantiate,
        },
      },
    });
  }

  private setInterruptBuffer() {
    // Set up the interrupt buffer
    if (crossOriginIsolated) {
      // Pyodide handles interrupts through SharedArrayBuffers, which
      // only work in secure (crossOriginIsolated) contexts
      this.interruptBuffer = new Uint8Array(new SharedArrayBuffer(1));
      this.rpc.proxy.request.setInterruptBuffer(this.interruptBuffer);
    } else {
      Logger.warn(
        "Not running in a secure context; interrupts are not available.",
      );
    }
  }

  public async createNotebookBackend() {
    await this.initialized.promise;
    return createWasmNotebookBackend({
      subscribe: async (cursor, emit, signal) => {
        signal.throwIfAborted();
        const id = generateUUID();
        this.notebookConsumers.set(id, emit);
        const close = once(() => {
          signal.removeEventListener("abort", close);
          this.notebookConsumers.delete(id);
          void this.rpc.proxy.request
            .notebookUnsubscribe(id)
            .catch(Logger.error);
        });
        signal.addEventListener("abort", close, { once: true });
        try {
          await this.rpc.proxy.request.notebookSubscribe({ id, cursor });
          return close;
        } catch (error) {
          close();
          throw error;
        }
      },
      call: (call) => this.rpc.proxy.request.notebookCall(call),
    });
  }

  public sendRename: EditRequests["sendRename"] = async ({ filename }) => {
    if (filename === null) {
      return null;
    }
    // Set filename in the URL params,
    // so refreshing the page will keep the filename
    PyodideRouter.setFilename(filename);

    await this.rpc.proxy.request.bridge({
      functionName: "rename_file",
      payload: filename,
    });
    return null;
  };

  public saveLayout: EditRequests["saveLayout"] = async ({ layout }) => {
    await this.rpc.proxy.request.setNotebookLayout(layout ?? null);
    return null;
  };

  public sendCopy: EditRequests["sendCopy"] = async () => {
    throwNotImplemented();
  };

  public sendStdin: EditRequests["sendStdin"] = async (request) => {
    await this.rpc.proxy.request.bridge({
      functionName: "put_input",
      payload: request.text,
    });
    return null;
  };

  public sendPdb: EditRequests["sendPdb"] = async () => {
    throwNotImplemented();
  };

  public sendSetBreakpoints: EditRequests["sendSetBreakpoints"] = async () => {
    throwNotImplemented();
  };

  public sendRun: EditRequests["sendRun"] = async (request) => {
    await this.rpc.proxy.request.loadPackages(request.codes.join("\n"));

    await this.putControlRequest({
      type: "execute-cells",
      ...request,
    });
    return null;
  };
  public sendRunScratchpad: EditRequests["sendRunScratchpad"] = async (
    request,
  ) => {
    await this.rpc.proxy.request.loadPackages(request.code);

    await this.putControlRequest({
      type: "execute-scratchpad",
      ...request,
    });
    return null;
  };
  public sendInterrupt: EditRequests["sendInterrupt"] = async () => {
    if (this.interruptBuffer !== undefined) {
      // 2 sends a SIGINT
      this.interruptBuffer[0] = 2;
    }
    return null;
  };
  public sendShutdown: EditRequests["sendShutdown"] = async () => {
    window.close();
    return null;
  };
  public sendFormat: EditRequests["sendFormat"] = async (request) => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "format",
      payload: request,
    });
    return response as FormatResponse;
  };

  public sendInstallMissingPackages: EditRequests["sendInstallMissingPackages"] =
    async (request) => {
      this.putControlRequest({
        type: "install-packages",
        ...request,
      });
      return null;
    };
  public sendCodeCompletionRequest: EditRequests["sendCodeCompletionRequest"] =
    async (request) => {
      // Because the Pyodide worker is single-threaded, sending
      // code completion requests while the kernel is running is useless
      // and runs the risk of choking the kernel
      const isRunning = store.get(notebookIsRunningAtom);
      if (!isRunning) {
        await this.rpc.proxy.request.bridge({
          functionName: "code_complete",
          payload: request,
        });
      }
      return null;
    };

  public saveUserConfig: EditRequests["saveUserConfig"] = async (request) => {
    await this.rpc.proxy.request.bridge({
      functionName: "save_user_config",
      payload: request,
    });

    return API.post<SaveUserConfigurationRequest>(
      "/kernel/save_user_config",
      request,
      { baseUrl: "/" },
    ).catch((error) => {
      // Just log to the console. It is likely a user who hosts their own web-assembly
      // won't use this.
      Logger.error(error);
      return null;
    });
  };

  public saveAppConfig: EditRequests["saveAppConfig"] = async (request) => {
    await this.rpc.proxy.request.bridge({
      functionName: "save_app_config",
      payload: request,
    });
    return null;
  };

  public sendRestart = async (): Promise<null> => {
    // Save first
    const code = await this.readCode();
    if (code.contents) {
      notebookFileStore.saveFile(code.contents);
      fallbackFileStore.saveFile(code.contents);
    }
    reloadSafe();
    return null;
  };

  public readCode: EditRequests["readCode"] = async () => {
    if (!this.saveRpc) {
      Logger.warn("Save RPC not initialized");
      return { contents: "" };
    }
    const contents = await this.saveRpc.readNotebook();
    return { contents };
  };

  public readSnippets: EditRequests["readSnippets"] = async () => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "read_snippets",
      payload: undefined,
    });
    return response as Snippets;
  };

  public openFile: EditRequests["openFile"] = async () => {
    const url = createShareableLink({
      code: null,
      baseUrl: window.location.origin,
    });
    window.open(url, "_blank");
    return null;
  };

  public sendListFiles: EditRequests["sendListFiles"] = async (request) => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "list_files",
      payload: request,
    });
    return response as FileListResponse;
  };

  public getFileRoots: EditRequests["getFileRoots"] = async () => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "file_roots",
      payload: undefined,
    });
    return response as FileRootsResponse;
  };

  public sendSearchFiles: EditRequests["sendSearchFiles"] = async (request) => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "search_files",
      payload: request,
    });
    return response as FileSearchResponse;
  };

  public sendComponentValues: RunRequests["sendComponentValues"] = async (
    request,
  ) => {
    await this.putControlRequest({
      type: "update-ui-element",
      ...request,
      token: generateUUID(),
    });
    return null;
  };

  public sendInstantiate: RunRequests["sendInstantiate"] = async () => {
    return null;
  };

  public sendFunctionRequest: RunRequests["sendFunctionRequest"] = async (
    request,
  ) => {
    await this.putControlRequest({
      type: "invoke-function",
      ...request,
    });
    return null;
  };

  public sendCreateFileOrFolder: EditRequests["sendCreateFileOrFolder"] =
    async (request) => {
      // The WASM RPC boundary can only carry JSON, so we base64-encode the
      // file bytes here. The HTTP transport uses multipart/form-data instead.
      let contents: string | null = null;
      if (request.file) {
        const dataUrl = await serializeBlob(request.file);
        contents = dataUrl.split(",")[1] ?? "";
      }
      const response = await this.rpc.proxy.request.bridge({
        functionName: "create_file_or_directory",
        payload: {
          path: request.path,
          type: request.type,
          name: request.name,
          contents,
        },
      });
      return response as FileCreateResponse;
    };

  public sendDeleteFileOrFolder: EditRequests["sendDeleteFileOrFolder"] =
    async (request) => {
      const response = await this.rpc.proxy.request.bridge({
        functionName: "delete_file_or_directory",
        payload: request,
      });
      return response as FileDeleteResponse;
    };

  public sendCopyFileOrFolder: EditRequests["sendCopyFileOrFolder"] = async (
    request,
  ) => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "copy_file_or_directory",
      payload: request,
    });
    return response as FileCopyResponse;
  };

  public sendRenameFileOrFolder: EditRequests["sendRenameFileOrFolder"] =
    async (request) => {
      const response = await this.rpc.proxy.request.bridge({
        functionName: "move_file_or_directory",
        payload: request,
      });
      return response as FileMoveResponse;
    };

  public sendUpdateFile: EditRequests["sendUpdateFile"] = async (request) => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "update_file",
      payload: request,
    });
    return response as FileUpdateResponse;
  };

  public sendFileDetails: EditRequests["sendFileDetails"] = async (request) => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "file_details",
      payload: request,
    });
    return response as FileDetailsResponse;
  };

  public exportAsHTML: EditRequests["exportAsHTML"] = async (
    request: ExportAsHTMLRequest,
  ) => {
    await flushDocument();
    const response = await this.rpc.proxy.request.bridge({
      functionName: "export_html",
      payload: withDevAssetUrl(request),
    });
    return response as ExportedFile<string>;
  };

  public exportAsMarkdown: EditRequests["exportAsMarkdown"] = async (
    request: ExportAsMarkdownRequest,
  ) => {
    await flushDocument();
    const response = await this.rpc.proxy.request.bridge({
      functionName: "export_markdown",
      payload: request,
    });
    return response as ExportedFile<string>;
  };

  public exportAsScript: EditRequests["exportAsScript"] = async (
    request: ExportAsScriptRequest,
  ) => {
    await flushDocument();
    const response = await this.rpc.proxy.request.bridge({
      functionName: "export_script",
      payload: request,
    });
    return response as ExportedFile<string>;
  };

  public previewDatasetColumn: EditRequests["previewDatasetColumn"] = async (
    request,
  ) => {
    await this.putControlRequest({
      type: "preview-dataset-column",
      ...request,
    });
    return null;
  };

  public previewSQLTable: EditRequests["previewSQLTable"] = async (request) => {
    await this.putControlRequest({
      type: "preview-sql-table",
      ...request,
    });
    return null;
  };

  public previewSQLTableList: EditRequests["previewSQLTableList"] = async (
    request,
  ) => {
    await this.putControlRequest({
      type: "list-sql-tables",
      ...request,
    });
    return null;
  };

  public previewSQLSchemaList: EditRequests["previewSQLSchemaList"] = async (
    request,
  ) => {
    await this.putControlRequest({
      type: "list-sql-schemas",
      ...request,
    });
    return null;
  };

  public previewDataSourceConnection: EditRequests["previewDataSourceConnection"] =
    async (request) => {
      await this.putControlRequest({
        type: "list-data-source-connection",
        ...request,
      });
      return null;
    };

  public validateSQL: EditRequests["validateSQL"] = async (request) => {
    await this.putControlRequest({
      type: "validate-sql",
      ...request,
    });
    return null;
  };

  public sendModelValue: RunRequests["sendModelValue"] = async (request) => {
    await this.putControlRequest({
      type: "model",
      ...request,
    });
    return null;
  };

  public addPackage: EditRequests["addPackage"] = async (request) => {
    return this.rpc.proxy.request.addPackage(request);
  };
  public removePackage: EditRequests["removePackage"] = async (request) => {
    return this.rpc.proxy.request.removePackage(request);
  };
  public getPackageList = async () => {
    const response = await this.rpc.proxy.request.listPackages();
    return response;
  };

  public getSandbox: EditRequests["getSandbox"] = async () => ({
    backend: null,
    manifest: null,
    filename: null,
  });
  public updateManifest: EditRequests["updateManifest"] = async () => {
    throw new Error("Sandboxes are not supported in WebAssembly");
  };
  public syncSandbox: EditRequests["syncSandbox"] = async () => {
    throw new Error("Sandboxes are not supported in WebAssembly");
  };
  public getDependencyTree: EditRequests["getDependencyTree"] = async () => {
    // WASM doesn't support dependency trees yet
    return {
      tree: {
        dependencies: [],
        name: "",
        tags: [],
        version: null,
      },
      context: { kind: "package-manager", name: "micropip" },
    };
  };

  public listSecretKeys: EditRequests["listSecretKeys"] = async (request) => {
    await this.putControlRequest({
      type: "list-secret-keys",
      ...request,
    });
    return null;
  };

  public discoverDataSources: EditRequests["discoverDataSources"] = async (
    request,
  ) => {
    await this.putControlRequest({
      type: "discover-data-sources",
      ...request,
    });
    return null;
  };

  public getUsageStats = throwNotImplemented;
  public getEnvironmentInfo: EditRequests["getEnvironmentInfo"] = async () => {
    const response = await this.rpc.proxy.request.bridge({
      functionName: "get_environment_info",
      payload: undefined,
    });
    return response as EnvironmentInfo;
  };
  public openTutorial = throwNotImplemented;
  public getRecentFiles = throwNotImplemented;
  public getWorkspaceFiles = throwNotImplemented;
  public getRunningNotebooks = throwNotImplemented;
  public shutdownSession = throwNotImplemented;
  public getExportAvailability = throwNotImplemented;
  public installExportRequirements = throwNotImplemented;
  public exportAsIPYNB = throwNotImplemented;
  public exportAsPDF = throwNotImplemented;
  public autoExportAsHTML = throwNotImplemented;
  public autoExportAsMarkdown = throwNotImplemented;
  public autoExportAsIPYNB = throwNotImplemented;
  public updateCellOutputs = throwNotImplemented;
  public writeSecret = throwNotImplemented;
  public invokeAiTool = throwNotImplemented;
  public clearCache = throwNotImplemented;
  public getCacheInfo = throwNotImplemented;
  public listStorageEntries = throwNotImplemented;
  public downloadStorage = throwNotImplemented;

  private async putControlRequest(operation: ClientCommand) {
    await this.rpc.proxy.request.bridge({
      functionName: "put_control_request",
      payload: operation,
    });
  }
}

// Compose the worker name. The optional "::controller" suffix tells
// getController.ts that the host page provides a custom /wasm/controller.js
// and that the dynamic import should be attempted. Hosts opt in by setting
// `window.__MARIMO_HAS_WASM_CONTROLLER__ = true` before
// PyodideBridge/worker initialization.
export function getWasmWorkerName(): string {
  const hasCustomController =
    typeof window !== "undefined" &&
    (window as unknown as { __MARIMO_HAS_WASM_CONTROLLER__?: boolean })
      .__MARIMO_HAS_WASM_CONTROLLER__ === true;
  return `marimo${hasCustomController ? CUSTOM_CONTROLLER_SUFFIX : ""}`;
}