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.

7.7 KB
Raw Blame
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations

import json
import socket
import subprocess
import sys
import time
import urllib.request
import uuid
from contextlib import contextmanager
from dataclasses import dataclass
from typing import TYPE_CHECKING

import websockets.sync.client

if TYPE_CHECKING:
    from collections.abc import Generator
    from pathlib import Path

    from websockets.sync.client import ClientConnection


@dataclass(frozen=True)
class PairTestServer:
    url: str
    session_id: str
    stable_session_id: str
    notebook_id: str
    _process: subprocess.Popen[bytes]
    _websocket: ClientConnection
    _stderr_path: Path
    _token: str | None = None

    @property
    def _headers(self) -> dict[str, str]:
        return (
            {"Authorization": f"Bearer {self._token}"} if self._token else {}
        )

    def wait_for_kernel(
        self,
        state: str,
        *,
        timeout: float = 10.0,
    ) -> None:
        deadline = time.monotonic() + timeout
        while time.monotonic() < deadline:
            if self._process.poll() is not None:
                raise RuntimeError(
                    "marimo server exited with code "
                    f"{self._process.returncode}:\n{_tail(self._stderr_path)}"
                )
            request = urllib.request.Request(
                f"{self.url}/api/kernel/status",
                headers={
                    **self._headers,
                    "Marimo-Session-Id": self.session_id,
                },
            )
            try:
                with urllib.request.urlopen(request, timeout=1) as response:
                    current = json.load(response)["state"]
                if current == state:
                    return
            except (OSError, KeyError, ValueError):
                pass
            time.sleep(0.05)
        raise TimeoutError(
            f"kernel did not become {state!r} within {timeout}s"
        )

    def close(self) -> None:
        try:
            request = urllib.request.Request(
                f"{self.url}/api/kernel/restart_session",
                method="POST",
                data=b"{}",
                headers={
                    **self._headers,
                    "Content-Type": "application/json",
                    "Marimo-Session-Id": self.session_id,
                },
            )
            with urllib.request.urlopen(request, timeout=5):
                pass
        except OSError:
            pass
        try:
            self._websocket.close()
        except OSError:
            pass
        _stop_process(self._process)


def _free_port() -> int:
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.bind(("127.0.0.1", 0))
        port: int = sock.getsockname()[1]
    return port


def _tail(path: Path) -> str:
    try:
        return path.read_text(errors="replace")[-4000:]
    except OSError:
        return ""


def _wait_for_server(
    url: str,
    process: subprocess.Popen[bytes],
    stderr_path: Path,
    *,
    timeout: float = 15.0,
    token: str | None = None,
) -> None:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if process.poll() is not None:
            raise RuntimeError(
                f"marimo server exited with code {process.returncode}:\n"
                f"{_tail(stderr_path)}"
            )
        try:
            request = urllib.request.Request(
                url,
                headers={"Authorization": f"Bearer {token}"} if token else {},
            )
            with urllib.request.urlopen(request, timeout=1):
                return
        except OSError:
            time.sleep(0.05)
    raise TimeoutError(
        f"marimo server at {url} did not start in {timeout}s:\n"
        f"{_tail(stderr_path)}"
    )


def _wait_for_kernel_ready(
    websocket: ClientConnection,
    *,
    timeout: float = 10.0,
) -> str:
    deadline = time.monotonic() + timeout
    notebook_id: str | None = None
    while True:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError("kernel did not become ready")
        event = json.loads(websocket.recv(timeout=remaining))
        if event["event"] == "notebook":
            notebook_id = event["data"]["notebook"]["id"]
        if event["event"] != "marimo":
            continue
        message = event["data"]["marimo"]
        if message["op"] == "kernel-ready":
            # The host publishes notebook identity before kernel-ready.
            assert isinstance(notebook_id, str), "Missing notebook snapshot"
            return notebook_id


def _stop_process(process: subprocess.Popen[bytes]) -> None:
    if process.poll() is not None:
        return
    process.terminate()
    try:
        process.wait(timeout=5)
    except subprocess.TimeoutExpired:
        process.kill()
        process.wait()


def _start_server(
    notebook: Path,
    stderr_path: Path,
    *,
    token: str | None,
    attempts: int = 3,
) -> tuple[subprocess.Popen[bytes], str]:
    for attempt in range(attempts):
        port = _free_port()
        with stderr_path.open("wb") as stderr_file:
            process = subprocess.Popen(
                [
                    sys.executable,
                    "-m",
                    "marimo",
                    "edit",
                    str(notebook),
                    "--headless",
                    *(
                        ["--token-password", token]
                        if token
                        else ["--no-token"]
                    ),
                    "--no-skew-protection",
                    "--port",
                    str(port),
                ],
                stdout=subprocess.DEVNULL,
                stderr=stderr_file,
                cwd=notebook.parent,
            )
        url = f"http://127.0.0.1:{port}"
        try:
            _wait_for_server(url, process, stderr_path, token=token)
        except RuntimeError:
            _stop_process(process)
            if attempt + 1 == attempts:
                raise
            continue
        return process, url
    raise AssertionError("server start attempts must be positive")


@contextmanager
def pair_test_server(
    tmp_path: Path, *, token: str | None = None
) -> Generator[PairTestServer, None, None]:
    notebook = tmp_path / "pair-integration.py"
    notebook.write_text("import marimo\napp = marimo.App()\n")
    stderr_path = tmp_path / "marimo-stderr.log"

    process, url = _start_server(notebook, stderr_path, token=token)
    try:
        session_id = f"pair_{uuid.uuid4().hex[:8]}"
        websocket = websockets.sync.client.connect(
            f"{url.replace('http://', 'ws://', 1)}/ws?session_id={session_id}",
            open_timeout=5,
            additional_headers={"Authorization": f"Bearer {token}"}
            if token
            else {},
        )
        notebook_id = _wait_for_kernel_ready(websocket)
        request = urllib.request.Request(
            f"{url}/api/sessions",
            headers={"Authorization": f"Bearer {token}"} if token else {},
        )
        with urllib.request.urlopen(request, timeout=5) as response:
            sessions = json.load(response)
        assert sessions[session_id]["notebook_id"] == notebook_id
        stable_session_id = sessions[session_id]["session_id"]
        server = PairTestServer(
            url=url,
            session_id=session_id,
            stable_session_id=stable_session_id,
            notebook_id=notebook_id,
            _process=process,
            _websocket=websocket,
            _stderr_path=stderr_path,
            _token=token,
        )
        try:
            yield server
        finally:
            server.close()
    finally:
        _stop_process(process)