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.

Add server registry and SSE execute endpoint (#8592)

Trevor Manz7f2c978b02e1
diff --git a/marimo/_mcp/code_server/main.py b/marimo/_mcp/code_server/main.py
index 635958c8ea..c6dc1302f7 100644
--- a/marimo/_mcp/code_server/main.py
+++ b/marimo/_mcp/code_server/main.py
@@ -8,9 +8,8 @@ in a running marimo kernel via the scratchpad.
from __future__ import annotations
-import asyncio
import os
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
from marimo._ai._tools.types import (
CodeExecutionResult,
@@ -19,11 +18,11 @@ from marimo._ai._tools.types import (
)
from marimo._dependencies.dependencies import DependencyManager
from marimo._loggers import marimo_logger
-from marimo._messaging.cell_output import CellChannel
-from marimo._messaging.notification import CellNotification
-from marimo._messaging.serde import deserialize_kernel_message
-from marimo._runtime.scratch import SCRATCH_CELL_ID
-from marimo._session.events import SessionEventBus, SessionEventListener
+from marimo._server.scratchpad import (
+ EXECUTION_TIMEOUT,
+ ScratchCellListener,
+ extract_result,
+)
from marimo._types.ids import SessionId
LOGGER = marimo_logger()
@@ -32,52 +31,6 @@ if TYPE_CHECKING:
from starlette.applications import Starlette
from starlette.types import Receive, Scope, Send
- from marimo._messaging.types import KernelMessage
- from marimo._session.session import Session
-
-_EXECUTION_TIMEOUT = 30.0 # seconds
-
-
-class _ScratchCellListener(SessionEventListener):
- """Listens for scratch cell idle notifications and signals waiters.
-
- Implements SessionExtension so it can be dynamically attached to a
- session via session.attach_extension / session.detach_extension.
- """
-
- def __init__(self) -> None:
- self._waiters: dict[str, asyncio.Event] = {}
-
- def wait_for(self, session_id: str) -> asyncio.Event:
- event = asyncio.Event()
- self._waiters[session_id] = event
- return event
-
- # SessionExtension protocol
- def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:
- del session
- event_bus.subscribe(self)
-
- def on_detach(self) -> None:
- pass
-
- def on_notification_sent(
- self, session: Session, notification: KernelMessage
- ) -> None:
- del session
- msg = deserialize_kernel_message(notification)
- if not isinstance(msg, CellNotification):
- return
- if msg.cell_id != SCRATCH_CELL_ID:
- return
- if msg.status != "idle":
- return
- # Signal any waiter for this session
- for sid, event in list(self._waiters.items()):
- if not event.is_set():
- event.set()
- del self._waiters[sid]
-
def setup_code_mcp_server(
app: Starlette, *, allow_remote: bool = False
@@ -122,10 +75,6 @@ def setup_code_mcp_server(
transport_security=transport_security,
)
- # Per-session locks to prevent overlapping scratchpad executions
- session_locks: dict[str, asyncio.Lock] = {}
- listener = _ScratchCellListener()
-
@mcp.tool()
async def list_sessions() -> ListSessionsResult:
"""List active marimo sessions.
@@ -176,38 +125,22 @@ def setup_code_mcp_server(
"Use list_sessions to find valid session IDs.",
)
- # Attach listener as a session extension
- session.attach_extension(listener)
-
- lock = session_locks.setdefault(session_id, asyncio.Lock())
- async with lock:
- try:
- # Set up event before sending command
- done = listener.wait_for(session_id)
-
- # Send the scratchpad execution command
+ listener = ScratchCellListener()
+ with session.scoped(listener):
+ async with session.scratchpad_lock:
session.put_control_request(
ExecuteScratchpadCommand(code=code),
from_consumer_id=None,
)
+ await listener.wait(timeout=EXECUTION_TIMEOUT)
- # Wait for the scratch cell to become idle
- await asyncio.wait_for(done.wait(), timeout=_EXECUTION_TIMEOUT)
-
- # FIXME: stdout/stderr are flushed every 10ms by the buffered
- # writer thread. Wait 50ms so trailing console output arrives
- # before we read cell_notifications.
- # See: marimo-team/marimo-lsp ExecutionRegistry.ts
- await asyncio.sleep(0.05)
- except asyncio.TimeoutError:
+ if listener.timed_out:
return CodeExecutionResult(
success=False,
- error=f"Execution timed out after {_EXECUTION_TIMEOUT}s",
+ error=f"Execution timed out after {EXECUTION_TIMEOUT}s",
)
- finally:
- session.detach_extension(listener)
- return _extract_result(session)
+ return extract_result(session)
# Build the streamable HTTP app
mcp_app = mcp.streamable_http_app()
@@ -228,51 +161,3 @@ def setup_code_mcp_server(
app.routes.insert(0, Mount("/mcp", mcp_app))
app.state.code_mcp = mcp
-
-
-def _extract_result(session: Any) -> CodeExecutionResult:
- """Read the scratch cell's final state from the session view."""
- cell_notif = session.session_view.cell_notifications.get(SCRATCH_CELL_ID)
- if cell_notif is None:
- return CodeExecutionResult(success=True)
-
- # Output
- output_data = None
- if cell_notif.output is not None:
- data = cell_notif.output.data
- if isinstance(data, str):
- output_data = data
- elif isinstance(data, dict):
- output_data = data.get(
- "text/plain", data.get("text/html", str(data))
- )
- # list → errors, handled below
-
- # Console
- stdout: list[str] = []
- stderr: list[str] = []
- for out in (
- cell_notif.console if isinstance(cell_notif.console, list) else []
- ):
- if out is None:
- continue
- if out.channel == CellChannel.STDOUT:
- stdout.append(str(out.data))
- elif out.channel == CellChannel.STDERR:
- stderr.append(str(out.data))
-
- # Errors
- errors: list[str] = []
- if cell_notif.output is not None and isinstance(
- cell_notif.output.data, list
- ):
- for err in cell_notif.output.data:
- errors.append(str(getattr(err, "msg", None) or err))
-
- return CodeExecutionResult(
- success=len(errors) == 0,
- output=output_data,
- stdout=stdout,
- stderr=stderr,
- errors=errors,
- )
diff --git a/marimo/_messaging/tracebacks.py b/marimo/_messaging/tracebacks.py
index 0304e6b955..72f34a549d 100644
--- a/marimo/_messaging/tracebacks.py
+++ b/marimo/_messaging/tracebacks.py
@@ -3,6 +3,7 @@ from __future__ import annotations
import sys
+from marimo._messaging.context import HTTP_REQUEST_CTX
from marimo._messaging.types import Stderr
@@ -21,10 +22,24 @@ def _highlight_traceback(traceback: str) -> str:
return f'<span class="codehilite">{body}</span>'
+def _accepts_html() -> bool:
+ """Check if the current request context accepts HTML responses.
+
+ Returns True when there is no request context (e.g. websocket/browser)
+ or when the Accept header explicitly includes text/html.
+ """
+ request = HTTP_REQUEST_CTX.get(None)
+ if request is None:
+ return True
+ return "text/html" in request.headers.get("accept", "")
+
+
def write_traceback(traceback: str) -> None:
- if isinstance(sys.stderr, Stderr):
+ if isinstance(sys.stderr, Stderr) and _accepts_html():
+ # Strip marimo's internal executor.py frame and highlight for the UI
+ trimmed = _trim_traceback(traceback)
sys.stderr._write_with_mimetype(
- _highlight_traceback(_trim_traceback(traceback)),
+ _highlight_traceback(trimmed),
mimetype="application/vnd.marimo+traceback",
)
else:
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index 7be8933b03..d03efacb49 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -1711,6 +1711,10 @@ class Kernel:
clear_console=True,
cell_id=SCRATCH_CELL_ID,
)
+ CellNotificationUtils.broadcast_status(
+ cell_id=SCRATCH_CELL_ID,
+ status="idle",
+ )
return
elif not cell:
return
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index f6443cae45..d4915b2f71 100644
--- a/marimo/_server/api/endpoints/execution.py
+++ b/marimo/_server/api/endpoints/execution.py
@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Optional
from uuid import uuid4
from starlette.authentication import requires
-from starlette.responses import JSONResponse
+from starlette.responses import JSONResponse, StreamingResponse
from marimo import _loggers
from marimo._messaging.notification import AlertNotification
@@ -34,6 +34,8 @@ from marimo._server.uvicorn_utils import close_uvicorn
from marimo._types.ids import ConsumerId
if TYPE_CHECKING:
+ from collections.abc import AsyncGenerator
+
from starlette.requests import Request
LOGGER = _loggers.marimo_logger()
@@ -239,6 +241,60 @@ async def run_cell(
return SuccessResponse()
[email protected]("/execute", include_in_schema=False)
+@requires("edit")
+async def execute_code(
+ *,
+ request: Request,
+) -> StreamingResponse:
+ """
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ExecuteScratchpadRequest"
+ responses:
+ 200:
+ description: Execute code in the kernel, streaming results as SSE.
+ content:
+ text/event-stream:
+ schema:
+ type: string
+ """ # noqa: E501
+ from marimo._runtime.commands import ExecuteScratchpadCommand
+ from marimo._server.scratchpad import (
+ EXECUTION_TIMEOUT,
+ ScratchCellListener,
+ build_done_event,
+ build_timeout_event,
+ )
+
+ app_state = AppState(request)
+ body = await parse_request(request, cls=ExecuteScratchpadRequest)
+ session = app_state.require_current_session()
+
+ async def sse_generator() -> AsyncGenerator[str, None]:
+ listener = ScratchCellListener()
+ with session.scoped(listener):
+ async with session.scratchpad_lock:
+ session.put_control_request(
+ ExecuteScratchpadCommand(
+ code=body.code,
+ request=HTTPRequest.from_request(request),
+ ),
+ from_consumer_id=None,
+ )
+ async for event in listener.stream(timeout=EXECUTION_TIMEOUT):
+ yield event
+
+ if listener.timed_out:
+ yield build_timeout_event(EXECUTION_TIMEOUT)
+ else:
+ yield build_done_event(session)
+
+ return StreamingResponse(sse_generator(), media_type="text/event-stream")
+
+
@router.post("/scratchpad/run")
@requires("edit")
async def run_scratchpad(
diff --git a/marimo/_server/api/endpoints/health.py b/marimo/_server/api/endpoints/health.py
index 9bdc38cb71..09c5e14ae5 100644
--- a/marimo/_server/api/endpoints/health.py
+++ b/marimo/_server/api/endpoints/health.py
@@ -2,7 +2,7 @@
from __future__ import annotations
from functools import lru_cache
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Optional, TypedDict
from starlette.authentication import requires
from starlette.responses import JSONResponse, PlainTextResponse
@@ -92,6 +92,42 @@ async def status(request: Request) -> JSONResponse:
)
+class SessionInfo(TypedDict):
+ filename: str | None
+ path: str | None
+
+
[email protected]("/api/sessions", include_in_schema=False)
+@requires("edit")
+async def list_sessions(request: Request) -> JSONResponse:
+ """List active session IDs and their notebook paths.
+
+ Only available when the server was started without an auth token
+ (``--no-token``) and without skew protection
+ (``--no-skew-protection``).
+ """
+
+ state = AppState(request)
+
+ if state.enable_auth or state.skew_protection:
+ return JSONResponse(
+ {
+ "error": "Session listing requires --no-token and "
+ "--no-skew-protection"
+ },
+ status_code=403,
+ )
+
+ sessions = {
+ session_id: SessionInfo(
+ filename=session.app_file_manager.filename,
+ path=session.app_file_manager.path,
+ )
+ for session_id, session in state.session_manager.sessions.items()
+ }
+ return JSONResponse(sessions)
+
+
@router.get("/api/version")
async def version(request: Request) -> PlainTextResponse:
"""
diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.py
index c64a268d59..cd469280bb 100644
--- a/marimo/_server/api/lifespans.py
+++ b/marimo/_server/api/lifespans.py
@@ -207,6 +207,49 @@ async def signal_handler(app: Starlette) -> AsyncIterator[None]:
yield
+async def server_registry(app: Starlette) -> AsyncIterator[None]:
+ """Register this server in the local registry for discovery.
+
+ Only servers started **without** an auth token (``--no-token``)
+ **and** without skew protection (``--no-skew-protection``) are
+ registered. This ensures only servers that have explicitly opted
+ into relaxed local access are discoverable.
+ """
+ from marimo._server.server_registry import (
+ ServerRegistryEntry,
+ ServerRegistryWriter,
+ )
+
+ state = AppState.from_app(app)
+
+ # Guard: only register when the user has opted into relaxed local
+ # access (no auth token, no skew protection).
+ if state.enable_auth or state.skew_protection:
+ LOGGER.debug(
+ "Skipping server registry: auth=%s, skew_protection=%s",
+ state.enable_auth,
+ state.skew_protection,
+ )
+ yield
+ return
+
+ entry = ServerRegistryEntry.from_server(
+ host=state.host,
+ port=state.port,
+ base_url=state.base_url,
+ )
+ writer = ServerRegistryWriter(entry)
+ try:
+ writer.register()
+ except Exception as e:
+ LOGGER.warning("Failed to register server: %s", e)
+
+ yield
+
+ writer.deregister()
+
+
@contextlib.asynccontextmanager
async def etc(app: Starlette) -> AsyncIterator[None]:
del app
diff --git a/marimo/_server/router.py b/marimo/_server/router.py
index 00a938a1fa..60599ee67e 100644
--- a/marimo/_server/router.py
+++ b/marimo/_server/router.py
@@ -38,7 +38,7 @@ class APIRouter(Router):
)
def post(
- self, path: str
+ self, path: str, include_in_schema: bool = True
) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""Post method that returns a JSON response"""
@@ -62,6 +62,7 @@ class APIRouter(Router):
path=self.prefix + path,
endpoint=wrapper_func,
methods=["POST"],
+ include_in_schema=include_in_schema,
)
return wrapper_func # type: ignore[return-value]
diff --git a/marimo/_server/scratchpad.py b/marimo/_server/scratchpad.py
new file mode 100644
index 0000000000..5dfe5400a9
--- /dev/null
+++ b/marimo/_server/scratchpad.py
@@ -0,0 +1,286 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Shared utilities for scratchpad execution."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import TYPE_CHECKING, Any, TypedDict
+
+if sys.version_info < (3, 11):
+ from typing_extensions import NotRequired
+else:
+ from typing import NotRequired
+
+from marimo._ai._tools.types import CodeExecutionResult
+from marimo._messaging.cell_output import CellChannel
+from marimo._messaging.notification import CellNotification
+from marimo._messaging.serde import deserialize_kernel_message
+from marimo._runtime.scratch import SCRATCH_CELL_ID
+from marimo._session.events import SessionEventBus, SessionEventListener
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncGenerator
+
+ from marimo._messaging.types import KernelMessage
+ from marimo._session.session import Session
+
+EXECUTION_TIMEOUT = 30.0 # seconds
+
+# Channel name constants for SSE events
+_CHANNEL_MAP = {
+ CellChannel.STDOUT: "stdout",
+ CellChannel.STDERR: "stderr",
+}
+
+
+# -- SSE event payload types --------------------------------------------------
+
+
+class OutputData(TypedDict):
+ mimetype: str
+ data: str
+
+
+class ErrorData(TypedDict):
+ type: str
+ msg: str
+ exception_type: NotRequired[str]
+
+
+class ConsoleEvent(TypedDict):
+ data: str
+
+
+class DoneSuccess(TypedDict):
+ success: bool
+ output: NotRequired[OutputData]
+
+
+class DoneError(TypedDict):
+ success: bool
+ error: ErrorData
+
+
+def _format_sse(event: str, data: Any) -> str:
+ """Format a single SSE event (event + JSON data)."""
+ return f"event: {event}\ndata: {json.dumps(data)}\n\n"
+
+
+# -- Listeners ----------------------------------------------------------------
+
+
+class ScratchCellListener(SessionEventListener):
+ """Listens for scratch cell notifications via an asyncio.Queue.
+
+ Supports both SSE streaming (via ``stream()``) and simple blocking
+ wait (via ``wait()``) so the same listener works for the HTTP
+ ``/execute`` endpoint and the MCP ``execute_code`` tool.
+ """
+
+ def __init__(self) -> None:
+ self._queue: asyncio.Queue[CellNotification | None] = asyncio.Queue()
+ self.timed_out = False
+
+ def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:
+ del session
+ self._event_bus = event_bus
+ event_bus.subscribe(self)
+
+ def on_detach(self) -> None:
+ if hasattr(self, "_event_bus"):
+ self._event_bus.unsubscribe(self)
+ del self._event_bus
+
+ def on_notification_sent(
+ self, session: Session, notification: KernelMessage
+ ) -> None:
+ del session
+ msg = deserialize_kernel_message(notification)
+ if not isinstance(msg, CellNotification):
+ return
+ if msg.cell_id != SCRATCH_CELL_ID:
+ return
+ self._queue.put_nowait(msg)
+ if msg.status == "idle":
+ self._queue.put_nowait(None) # sentinel
+
+ async def stream(
+ self, timeout: float = EXECUTION_TIMEOUT
+ ) -> AsyncGenerator[str, None]:
+ """Yield SSE-formatted stdout/stderr events until execution completes."""
+ import time
+
+ deadline = time.monotonic() + timeout
+ while True:
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ self.timed_out = True
+ return
+ try:
+ msg = await asyncio.wait_for(
+ self._queue.get(), timeout=remaining
+ )
+ except asyncio.TimeoutError:
+ self.timed_out = True
+ return
+
+ if msg is None:
+ # Done sentinel — but stdout/stderr are flushed every
+ # 10ms by the buffered writer thread. Wait 50ms so
+ # trailing console output arrives before we finish.
+ await asyncio.sleep(0.05)
+ while not self._queue.empty():
+ trailing = self._queue.get_nowait()
+ if trailing is not None:
+ for event_str in _format_console(trailing):
+ yield event_str
+ return
+
+ for event_str in _format_console(msg):
+ yield event_str
+
+ async def wait(self, timeout: float = EXECUTION_TIMEOUT) -> None:
+ """Block until execution completes, discarding streamed events.
+
+ Sets ``self.timed_out`` if the deadline is exceeded.
+ """
+ import time
+
+ deadline = time.monotonic() + timeout
+ while True:
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ self.timed_out = True
+ return
+ try:
+ msg = await asyncio.wait_for(
+ self._queue.get(), timeout=remaining
+ )
+ except asyncio.TimeoutError:
+ self.timed_out = True
+ return
+ if msg is None:
+ # Same flush delay as stream()
+ await asyncio.sleep(0.05)
+ return
+
+
+# -- Helpers ------------------------------------------------------------------
+
+
+def _format_console(msg: CellNotification) -> list[str]:
+ """Extract SSE-formatted stdout/stderr events from a CellNotification."""
+ if msg.console is None:
+ return []
+ console_list = (
+ msg.console if isinstance(msg.console, list) else [msg.console]
+ )
+ return [
+ _format_sse(channel, ConsoleEvent(data=str(out.data)))
+ for out in console_list
+ if out is not None
+ for channel in (_CHANNEL_MAP.get(out.channel),)
+ if channel is not None
+ ]
+
+
+def build_done_event(session: Session) -> str:
+ """Build the ``done`` SSE event from the session's scratch cell state."""
+ cell_notif = session.session_view.cell_notifications.get(SCRATCH_CELL_ID)
+ if cell_notif is None:
+ return _format_sse("done", DoneSuccess(success=True))
+
+ output = cell_notif.output
+
+ # Error case
+ if (
+ output is not None
+ and output.channel == CellChannel.MARIMO_ERROR
+ and isinstance(output.data, list)
+ and output.data
+ ):
+ err = output.data[0]
+ error_data = ErrorData(
+ type=type(err).__name__,
+ msg=str(getattr(err, "msg", None) or err),
+ )
+ if hasattr(err, "exception_type"):
+ error_data["exception_type"] = err.exception_type
+ return _format_sse("done", DoneError(success=False, error=error_data))
+
+ # Success case
+ if output is not None:
+ data = output.data
+ if isinstance(data, dict):
+ data = data.get("text/plain", data.get("text/html", str(data)))
+ return _format_sse(
+ "done",
+ DoneSuccess(
+ success=True,
+ output=OutputData(
+ mimetype=str(output.mimetype), data=str(data)
+ ),
+ ),
+ )
+
+ return _format_sse("done", DoneSuccess(success=True))
+
+
+def build_timeout_event(timeout: float) -> str:
+ """Build a ``done`` SSE event for a timeout."""
+ return _format_sse(
+ "done",
+ DoneError(
+ success=False,
+ error=ErrorData(
+ type="TimeoutError",
+ msg=f"Execution timed out after {timeout}s",
+ ),
+ ),
+ )
+
+
+def extract_result(session: Session) -> CodeExecutionResult:
+ """Read the scratch cell's final state from the session view."""
+ cell_notif = session.session_view.cell_notifications.get(SCRATCH_CELL_ID)
+ if cell_notif is None:
+ return CodeExecutionResult(success=True)
+
+ output_data = None
+ if cell_notif.output is not None:
+ data = cell_notif.output.data
+ if isinstance(data, str):
+ output_data = data
+ elif isinstance(data, dict):
+ output_data = data.get(
+ "text/plain", data.get("text/html", str(data))
+ )
+
+ stdout: list[str] = []
+ stderr: list[str] = []
+ for out in (
+ cell_notif.console if isinstance(cell_notif.console, list) else []
+ ):
+ if out is None:
+ continue
+ if out.channel == CellChannel.STDOUT:
+ stdout.append(str(out.data))
+ elif out.channel == CellChannel.STDERR:
+ stderr.append(str(out.data))
+
+ errors: list[str] = []
+ if cell_notif.output is not None and isinstance(
+ cell_notif.output.data, list
+ ):
+ for err in cell_notif.output.data:
+ errors.append(str(getattr(err, "msg", None) or err))
+
+ return CodeExecutionResult(
+ success=len(errors) == 0,
+ output=output_data,
+ stdout=stdout,
+ stderr=stderr,
+ errors=errors,
+ )
diff --git a/marimo/_server/server_registry.py b/marimo/_server/server_registry.py
new file mode 100644
index 0000000000..72c57a221b
--- /dev/null
+++ b/marimo/_server/server_registry.py
@@ -0,0 +1,130 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Local discovery registry for running marimo instances.
+
+Each marimo server writes a small JSON file to
+``~/.local/state/marimo/servers/<host>_<port>.json`` at startup and
+removes it on shutdown. External tools (e.g. ``list-sessions.sh``)
+read these files to discover running instances — no marimo import or
+HTTP endpoint is required.
+
+SECURITY: Only instances that have opted into relaxed local access —
+started **without** an auth token (``--no-token``) **and** without
+skew protection (``--no-skew-protection``) — should be registered.
+See the guard in ``lifespans.server_registry``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+from marimo import _loggers
+from marimo._utils.xdg import marimo_state_dir
+
+LOGGER = _loggers.marimo_logger()
+
+SERVERS_DIR_NAME = "servers"
+
+
+def _servers_dir() -> Path:
+ return marimo_state_dir() / SERVERS_DIR_NAME
+
+
+def _entry_path(server_id: str) -> Path:
+ safe_id = server_id.replace(":", "_").replace("/", "_")
+ return _servers_dir() / f"{safe_id}.json"
+
+
+@dataclass(frozen=True)
+class ServerRegistryEntry:
+ """Minimal descriptor for a running marimo server.
+
+ SECURITY NOTE: These files live on the local filesystem and are
+ readable by any process running as the same user. Keep the fields
+ to the bare minimum needed for discovery — no secrets, no auth
+ tokens, no session data. If you want to add a field, ask whether
+ an unauthenticated local process really needs it.
+ """
+
+ server_id: str
+ pid: int
+ host: str
+ port: int
+ base_url: str
+ started_at: str
+ version: str
+
+ @staticmethod
+ def from_server(
+ *,
+ host: str,
+ port: int,
+ base_url: str,
+ ) -> ServerRegistryEntry:
+ from marimo._version import __version__
+
+ return ServerRegistryEntry(
+ server_id=f"{host}:{port}",
+ pid=os.getpid(),
+ host=host,
+ port=port,
+ base_url=base_url,
+ started_at=datetime.now(timezone.utc).isoformat(),
+ version=__version__,
+ )
+
+
+class ServerRegistryWriter:
+ """Writes a registry entry on server start, removes on shutdown."""
+
+ def __init__(self, entry: ServerRegistryEntry) -> None:
+ self._entry = entry
+ self._path = _entry_path(entry.server_id)
+ self._registered = False
+
+ def register(self) -> None:
+ servers_dir = _servers_dir()
+ servers_dir.mkdir(parents=True, exist_ok=True)
+
+ data = json.dumps(asdict(self._entry), indent=2)
+
+ # Atomic write: temp file then rename
+ fd, tmp_path = tempfile.mkstemp(dir=str(servers_dir), suffix=".tmp")
+ try:
+ try:
+ os.write(fd, data.encode("utf-8"))
+ finally:
+ os.close(fd)
+ os.chmod(tmp_path, 0o600)
+ os.replace(tmp_path, str(self._path))
+ except Exception:
+ try:
+ os.unlink(tmp_path)
+ except OSError:
+ pass
+ raise
+
+ self._registered = True
+ atexit.register(self.deregister)
+ LOGGER.debug("Registered server: %s", self._path)
+
+ def deregister(self) -> None:
+ if not self._registered:
+ return
+ try:
+ self._path.unlink(missing_ok=True)
+ LOGGER.debug("Deregistered server: %s", self._path)
+ except OSError as e:
+ LOGGER.warning(
+ "Failed to remove registry entry %s: %s", self._path, e
+ )
+ finally:
+ self._registered = False
diff --git a/marimo/_server/start.py b/marimo/_server/start.py
index 67d3c0f8fb..1dc6723c71 100644
--- a/marimo/_server/start.py
+++ b/marimo/_server/start.py
@@ -274,6 +274,7 @@ def start(
lifespans.logging,
lifespans.open_browser,
lifespans.tool_manager,
+ lifespans.server_registry,
*LIFESPAN_REGISTRY.get_all(),
]
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 756d2dc987..3c3db1b926 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -7,6 +7,8 @@ and websocket for bidirectional communication.
from __future__ import annotations
+import asyncio
+import contextlib
from typing import TYPE_CHECKING, Optional
from uuid import uuid4
@@ -57,7 +59,7 @@ from marimo._types.ids import ConsumerId
from marimo._utils.repr import format_repr
if TYPE_CHECKING:
- from collections.abc import Mapping
+ from collections.abc import Iterator, Mapping
from marimo._server.models.models import InstantiateNotebookRequest
@@ -201,6 +203,7 @@ class SessionImpl(Session):
self.session_view = SessionView()
self.config_manager = config_manager
self.extensions = extensions
+ self.scratchpad_lock = asyncio.Lock()
self._kernel_manager.start_kernel()
self._event_bus = SessionEventBus()
@@ -239,16 +242,19 @@ class SessionImpl(Session):
)
continue
- def attach_extension(self, extension: SessionExtension) -> None:
- """Dynamically attach an extension to the session."""
+ @contextlib.contextmanager
+ def scoped(
+ self, extension: SessionExtension
+ ) -> Iterator[SessionExtension]:
+ """Attach an extension for the duration of the context."""
self.extensions.append(extension)
extension.on_attach(self, self._event_bus)
-
- def detach_extension(self, extension: SessionExtension) -> None:
- """Dynamically detach an extension from the session."""
- extension.on_detach()
- if extension in self.extensions:
- self.extensions.remove(extension)
+ try:
+ yield extension
+ finally:
+ extension.on_detach()
+ if extension in self.extensions:
+ self.extensions.remove(extension)
@property
def consumers(self) -> Mapping[SessionConsumer, ConsumerId]:
diff --git a/marimo/_session/types.py b/marimo/_session/types.py
index 26ad5c0f2e..f4ab6a1449 100644
--- a/marimo/_session/types.py
+++ b/marimo/_session/types.py
@@ -8,12 +8,14 @@ implementations.
from __future__ import annotations
+import contextlib
from enum import Enum
from typing import TYPE_CHECKING, Any, Optional, Protocol, Union
if TYPE_CHECKING:
+ import asyncio
import threading
- from collections.abc import Mapping
+ from collections.abc import Iterator, Mapping
from marimo._config.manager import MarimoConfigManager
from marimo._messaging.notification import NotificationMessage
@@ -109,6 +111,7 @@ class Session(Protocol):
config_manager: MarimoConfigManager
session_view: SessionView
ttl_seconds: int
+ scratchpad_lock: asyncio.Lock
@property
def consumers(self) -> Mapping[SessionConsumer, ConsumerId]:
@@ -182,12 +185,11 @@ class Session(Protocol):
"""Instantiate the app."""
...
- def attach_extension(self, extension: SessionExtension) -> None:
- """Dynamically attach an extension to the session."""
- ...
-
- def detach_extension(self, extension: SessionExtension) -> None:
- """Dynamically detach an extension from the session."""
+ @contextlib.contextmanager
+ def scoped(
+ self, extension: SessionExtension
+ ) -> Iterator[SessionExtension]:
+ """Attach an extension for the duration of the context."""
...
def close(self) -> None:
diff --git a/tests/_messaging/test_tracebacks.py b/tests/_messaging/test_tracebacks.py
index 84e88f2ea0..364e625f2e 100644
--- a/tests/_messaging/test_tracebacks.py
+++ b/tests/_messaging/test_tracebacks.py
@@ -3,13 +3,16 @@ from __future__ import annotations
from unittest.mock import MagicMock, patch
+from marimo._messaging.context import HTTP_REQUEST_CTX
from marimo._messaging.tracebacks import (
+ _accepts_html,
_highlight_traceback,
_trim_traceback,
is_code_highlighting,
write_traceback,
)
from marimo._messaging.types import Stderr
+from marimo._runtime.commands import HTTPRequest
class TestTracebacks:
@@ -81,6 +84,125 @@ class TestTracebacks:
assert is_code_highlighting("") is False
assert is_code_highlighting('class="not-codehilite"') is False
+ def test_write_traceback_plain_text_when_accept_not_html(self) -> None:
+ """When HTTP request has Accept without text/html, use plain text."""
+ mock_stderr = MagicMock(spec=Stderr)
+ req = HTTPRequest(
+ url={},
+ base_url={},
+ headers={"accept": "text/event-stream"},
+ query_params={},
+ path_params={},
+ cookies={},
+ meta={},
+ user=None,
+ )
+ token = HTTP_REQUEST_CTX.set(req)
+ try:
+ with patch("sys.stderr", mock_stderr):
+ traceback = 'Traceback (most recent call last):\n File "<stdin>", line 1, in <module>\nValueError: bad'
+ write_traceback(traceback)
+ mock_stderr.write.assert_called_once()
+ mock_stderr._write_with_mimetype.assert_not_called()
+ finally:
+ HTTP_REQUEST_CTX.reset(token)
+
+ def test_write_traceback_html_when_accept_includes_html(self) -> None:
+ """When HTTP request has Accept with text/html, use HTML formatting."""
+ mock_stderr = MagicMock(spec=Stderr)
+ req = HTTPRequest(
+ url={},
+ base_url={},
+ headers={"accept": "text/html, application/json"},
+ query_params={},
+ path_params={},
+ cookies={},
+ meta={},
+ user=None,
+ )
+ token = HTTP_REQUEST_CTX.set(req)
+ try:
+ with patch("sys.stderr", mock_stderr):
+ traceback = 'Traceback (most recent call last):\n File "<stdin>", line 1, in <module>\nValueError: bad'
+ write_traceback(traceback)
+ mock_stderr._write_with_mimetype.assert_called_once()
+ mock_stderr.write.assert_not_called()
+ finally:
+ HTTP_REQUEST_CTX.reset(token)
+
+
+class TestAcceptsHtml:
+ def test_no_request_context(self) -> None:
+ assert _accepts_html() is True
+
+ def test_accept_event_stream(self) -> None:
+ req = HTTPRequest(
+ url={},
+ base_url={},
+ headers={"accept": "text/event-stream"},
+ query_params={},
+ path_params={},
+ cookies={},
+ meta={},
+ user=None,
+ )
+ token = HTTP_REQUEST_CTX.set(req)
+ try:
+ assert _accepts_html() is False
+ finally:
+ HTTP_REQUEST_CTX.reset(token)
+
+ def test_accept_html(self) -> None:
+ req = HTTPRequest(
+ url={},
+ base_url={},
+ headers={"accept": "text/html"},
+ query_params={},
+ path_params={},
+ cookies={},
+ meta={},
+ user=None,
+ )
+ token = HTTP_REQUEST_CTX.set(req)
+ try:
+ assert _accepts_html() is True
+ finally:
+ HTTP_REQUEST_CTX.reset(token)
+
+ def test_accept_wildcard(self) -> None:
+ req = HTTPRequest(
+ url={},
+ base_url={},
+ headers={"accept": "*/*"},
+ query_params={},
+ path_params={},
+ cookies={},
+ meta={},
+ user=None,
+ )
+ token = HTTP_REQUEST_CTX.set(req)
+ try:
+ assert _accepts_html() is False
+ finally:
+ HTTP_REQUEST_CTX.reset(token)
+
+ def test_no_accept_header(self) -> None:
+ req = HTTPRequest(
+ url={},
+ base_url={},
+ headers={},
+ query_params={},
+ path_params={},
+ cookies={},
+ meta={},
+ user=None,
+ )
+ token = HTTP_REQUEST_CTX.set(req)
+ try:
+ assert _accepts_html() is False
+ finally:
+ HTTP_REQUEST_CTX.reset(token)
+
def test_trim(self) -> None:
prefix = "Traceback (most recent call last):\n"
head = ' File ".../marimo/_runtime/executor.py", line 139, in execute_cell\n return eval(cell.last_expr, glbls)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^\n'
diff --git a/tests/_server/test_scratchpad.py b/tests/_server/test_scratchpad.py
new file mode 100644
index 0000000000..bd650e6b7f
--- /dev/null
+++ b/tests/_server/test_scratchpad.py
@@ -0,0 +1,372 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+
+from marimo._ai._tools.types import CodeExecutionResult
+from marimo._messaging.cell_output import CellChannel, CellOutput
+from marimo._messaging.errors import (
+ MarimoExceptionRaisedError,
+ MarimoSyntaxError,
+)
+from marimo._messaging.notification import CellNotification
+from marimo._runtime.scratch import SCRATCH_CELL_ID
+from marimo._server.scratchpad import (
+ ScratchCellListener,
+ _format_console,
+ _format_sse,
+ build_done_event,
+ build_timeout_event,
+ extract_result,
+)
+
+
+def _make_session(
+ notification: CellNotification | None = None,
+) -> MagicMock:
+ session = MagicMock()
+ session.session_view.cell_notifications = {}
+ if notification is not None:
+ session.session_view.cell_notifications[SCRATCH_CELL_ID] = notification
+ return session
+
+
+def _parse_sse(sse: str) -> tuple[str, dict[str, object]]:
+ """Parse an SSE string into (event_name, json_data)."""
+ event = ""
+ data = ""
+ for line in sse.strip().splitlines():
+ if line.startswith("event: "):
+ event = line[len("event: ") :]
+ elif line.startswith("data: "):
+ data = line[len("data: ") :]
+ return event, json.loads(data)
+
+
+class TestExtractResult:
+ def test_no_notification(self) -> None:
+ result = extract_result(_make_session())
+ assert result == CodeExecutionResult(success=True)
+
+ def test_string_output(self) -> None:
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/plain",
+ data="hello",
+ ),
+ console=None,
+ status="idle",
+ )
+ result = extract_result(_make_session(notif))
+ assert result.success is True
+ assert result.output == "hello"
+
+ def test_dict_output_text_plain(self) -> None:
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/plain",
+ data={"text/plain": "value", "text/html": "<b>value</b>"},
+ ),
+ console=None,
+ status="idle",
+ )
+ result = extract_result(_make_session(notif))
+ assert result.output == "value"
+
+ def test_dict_output_html_fallback(self) -> None:
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/html",
+ data={"text/html": "<b>hi</b>"},
+ ),
+ console=None,
+ status="idle",
+ )
+ result = extract_result(_make_session(notif))
+ assert result.output == "<b>hi</b>"
+
+ def test_stdout_stderr(self) -> None:
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=None,
+ console=[
+ CellOutput(
+ channel=CellChannel.STDOUT,
+ mimetype="text/plain",
+ data="out1",
+ ),
+ CellOutput(
+ channel=CellChannel.STDERR,
+ mimetype="text/plain",
+ data="err1",
+ ),
+ CellOutput(
+ channel=CellChannel.STDOUT,
+ mimetype="text/plain",
+ data="out2",
+ ),
+ ],
+ status="idle",
+ )
+ result = extract_result(_make_session(notif))
+ assert result.stdout == ["out1", "out2"]
+ assert result.stderr == ["err1"]
+
+ def test_errors(self) -> None:
+ err_obj = MagicMock()
+ err_obj.msg = "NameError: x is not defined"
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput(
+ channel=CellChannel.MARIMO_ERROR,
+ mimetype="application/vnd.marimo+error",
+ data=[err_obj],
+ ),
+ console=None,
+ status="idle",
+ )
+ result = extract_result(_make_session(notif))
+ assert result.success is False
+ assert len(result.errors) == 1
+ assert "NameError" in result.errors[0]
+
+ def test_none_console_entries_skipped(self) -> None:
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=None,
+ console=[
+ None,
+ CellOutput( # type: ignore[list-item]
+ channel=CellChannel.STDOUT,
+ mimetype="text/plain",
+ data="ok",
+ ),
+ ],
+ status="idle",
+ )
+ result = extract_result(_make_session(notif))
+ assert result.stdout == ["ok"]
+
+
+class TestFormatSse:
+ def test_json_payload(self) -> None:
+ result = _format_sse("done", {"success": True})
+ assert result == 'event: done\ndata: {"success": true}\n\n'
+
+ def test_newlines_in_json_are_escaped(self) -> None:
+ result = _format_sse("stdout", {"data": "line1\nline2\n"})
+ # The JSON string escapes \n, so it's a single data: line
+ assert result.count("\ndata: ") == 1
+ event, payload = _parse_sse(result)
+ assert event == "stdout"
+ assert payload["data"] == "line1\nline2\n"
+
+
+class TestFormatConsole:
+ def test_stdout(self) -> None:
+ msg = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ console=CellOutput.stdout("hello world\n"),
+ )
+ events = _format_console(msg)
+ assert len(events) == 1
+ event, payload = _parse_sse(events[0])
+ assert event == "stdout"
+ assert payload["data"] == "hello world\n"
+
+ def test_stderr(self) -> None:
+ msg = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ console=CellOutput.stderr("warning\n"),
+ )
+ events = _format_console(msg)
+ assert len(events) == 1
+ event, payload = _parse_sse(events[0])
+ assert event == "stderr"
+ assert payload["data"] == "warning\n"
+
+ def test_list_of_outputs(self) -> None:
+ msg = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ console=[
+ CellOutput.stdout("line1\n"),
+ CellOutput.stderr("err1\n"),
+ ],
+ )
+ events = _format_console(msg)
+ assert len(events) == 2
+ assert _parse_sse(events[0])[0] == "stdout"
+ assert _parse_sse(events[1])[0] == "stderr"
+
+ def test_none_console(self) -> None:
+ msg = CellNotification(cell_id=SCRATCH_CELL_ID)
+ assert _format_console(msg) == []
+
+ def test_none_entries_skipped(self) -> None:
+ msg = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ console=[
+ None, # type: ignore[list-item]
+ CellOutput.stdout("ok\n"),
+ ],
+ )
+ events = _format_console(msg)
+ assert len(events) == 1
+
+ def test_multiline_data_stays_single_sse_line(self) -> None:
+ msg = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ console=CellOutput.stdout("a\nb\nc\n"),
+ )
+ events = _format_console(msg)
+ assert len(events) == 1
+ # Should be exactly one data: line (newlines escaped in JSON)
+ assert events[0].count("\ndata: ") == 1
+ _, payload = _parse_sse(events[0])
+ assert payload["data"] == "a\nb\nc\n"
+
+
+class TestBuildDoneEvent:
+ def test_no_notification(self) -> None:
+ event, data = _parse_sse(build_done_event(_make_session()))
+ assert event == "done"
+ assert data == {"success": True}
+
+ def test_success_with_output(self) -> None:
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/plain",
+ data="42",
+ ),
+ status="idle",
+ )
+ _, data = _parse_sse(build_done_event(_make_session(notif)))
+ assert data["success"] is True
+ assert data["output"]["mimetype"] == "text/plain"
+ assert data["output"]["data"] == "42"
+
+ def test_success_with_dict_output(self) -> None:
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/plain",
+ data={"text/plain": "value", "text/html": "<b>v</b>"},
+ ),
+ status="idle",
+ )
+ _, data = _parse_sse(build_done_event(_make_session(notif)))
+ assert data["success"] is True
+ assert data["output"]["data"] == "value"
+
+ def test_error_with_exception(self) -> None:
+ err = MarimoExceptionRaisedError(
+ msg="NameError: x is not defined",
+ exception_type="NameError",
+ raising_cell=None,
+ )
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput.errors([err]),
+ status="idle",
+ )
+ _, data = _parse_sse(build_done_event(_make_session(notif)))
+ assert data["success"] is False
+ assert data["error"]["type"] == "MarimoExceptionRaisedError"
+ assert data["error"]["exception_type"] == "NameError"
+ assert "NameError" in data["error"]["msg"]
+
+ def test_error_without_exception_type(self) -> None:
+ err = MarimoSyntaxError(msg="invalid syntax", lineno=1)
+ notif = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ output=CellOutput.errors([err]),
+ status="idle",
+ )
+ _, data = _parse_sse(build_done_event(_make_session(notif)))
+ assert data["success"] is False
+ assert data["error"]["type"] == "MarimoSyntaxError"
+ assert "exception_type" not in data["error"]
+
+ def test_timeout(self) -> None:
+ _, data = _parse_sse(build_timeout_event(30.0))
+ assert data["success"] is False
+ assert data["error"]["type"] == "TimeoutError"
+ assert "30.0s" in data["error"]["msg"]
+
+
+class TestScratchCellListener:
+ @pytest.mark.asyncio
+ async def test_stream_basic(self) -> None:
+ from marimo._messaging.serde import serialize_kernel_message
+
+ listener = ScratchCellListener()
+ event_bus = MagicMock()
+ session = MagicMock()
+ listener.on_attach(session, event_bus)
+
+ running = CellNotification(cell_id=SCRATCH_CELL_ID, status="running")
+ console = CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ console=CellOutput.stdout("hello\n"),
+ )
+ idle = CellNotification(cell_id=SCRATCH_CELL_ID, status="idle")
+
+ for notif in [running, console, idle]:
+ listener.on_notification_sent(
+ session, serialize_kernel_message(notif)
+ )
+
+ events: list[str] = []
+ async for event in listener.stream():
+ events.append(event)
+
+ # running has no console → no events; console has stdout; idle has no console
+ assert len(events) == 1
+ name, payload = _parse_sse(events[0])
+ assert name == "stdout"
+ assert payload["data"] == "hello\n"
+ assert not listener.timed_out
+
+ @pytest.mark.asyncio
+ async def test_ignores_other_cells(self) -> None:
+ from marimo._messaging.serde import serialize_kernel_message
+
+ listener = ScratchCellListener()
+ event_bus = MagicMock()
+ session = MagicMock()
+ listener.on_attach(session, event_bus)
+
+ other_cell = CellNotification(
+ cell_id="other_cell_id",
+ status="running", # type: ignore[arg-type]
+ )
+ listener.on_notification_sent(
+ session, serialize_kernel_message(other_cell)
+ )
+ assert listener._queue.empty()
+
+ @pytest.mark.asyncio
+ async def test_stream_timeout(self) -> None:
+ listener = ScratchCellListener()
+ event_bus = MagicMock()
+ session = MagicMock()
+ listener.on_attach(session, event_bus)
+
+ events: list[str] = []
+ async for event in listener.stream(timeout=0.1):
+ events.append(event)
+
+ assert events == []
+ assert listener.timed_out is True
diff --git a/tests/_server/test_server_registry.py b/tests/_server/test_server_registry.py
new file mode 100644
index 0000000000..679a259ed6
--- /dev/null
+++ b/tests/_server/test_server_registry.py
@@ -0,0 +1,128 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import asdict
+from typing import TYPE_CHECKING
+from unittest.mock import patch
+
+import pytest
+
+from marimo._server.server_registry import (
+ ServerRegistryEntry,
+ ServerRegistryWriter,
+)
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+def _make_entry(
+ *,
+ port: int = 2718,
+ host: str = "localhost",
+ pid: int | None = None,
+) -> ServerRegistryEntry:
+ return ServerRegistryEntry(
+ server_id=f"{host}:{port}",
+ pid=pid or os.getpid(),
+ host=host,
+ port=port,
+ base_url="",
+ started_at="2026-01-01T00:00:00+00:00",
+ version="0.0.0",
+ )
+
+
+def _patch_servers_dir(tmp_path: Path):
+ return patch(
+ "marimo._server.server_registry._servers_dir",
+ return_value=tmp_path,
+ )
+
+
+# --- Writer round-trip ---
+
+
+def test_round_trip(tmp_path: Path):
+ entry = _make_entry()
+ with _patch_servers_dir(tmp_path):
+ writer = ServerRegistryWriter(entry)
+ writer.register()
+
+ files = list(tmp_path.glob("*.json"))
+ assert len(files) == 1
+ data = json.loads(files[0].read_text())
+ assert data == asdict(entry)
+
+ writer.deregister()
+ assert list(tmp_path.glob("*.json")) == []
+
+
+def test_deregister_is_idempotent(tmp_path: Path):
+ entry = _make_entry()
+ with _patch_servers_dir(tmp_path):
+ writer = ServerRegistryWriter(entry)
+ writer.register()
+ writer.deregister()
+ writer.deregister() # should not raise
+ assert list(tmp_path.glob("*.json")) == []
+
+
[email protected](sys.platform == "win32", reason="Unix file permissions")
+def test_file_permissions(tmp_path: Path):
+ entry = _make_entry()
+ with _patch_servers_dir(tmp_path):
+ writer = ServerRegistryWriter(entry)
+ writer.register()
+
+ files = list(tmp_path.glob("*.json"))
+ assert len(files) == 1
+ assert oct(files[0].stat().st_mode & 0o777) == "0o600"
+
+ writer.deregister()
+
+
+def test_multiple_entries(tmp_path: Path):
+ e1 = _make_entry(port=2718)
+ e2 = _make_entry(port=2719)
+ with _patch_servers_dir(tmp_path):
+ w1 = ServerRegistryWriter(e1)
+ w2 = ServerRegistryWriter(e2)
+ w1.register()
+ w2.register()
+
+ files = list(tmp_path.glob("*.json"))
+ assert len(files) == 2
+
+ w1.deregister()
+ w2.deregister()
+
+
+# --- from_server ---
+
+
+def test_from_server():
+ entry = ServerRegistryEntry.from_server(
+ host="localhost",
+ port=2718,
+ base_url="",
+ )
+ assert entry.server_id == "localhost:2718"
+ assert entry.pid == os.getpid()
+ assert entry.host == "localhost"
+ assert entry.port == 2718
+ assert entry.base_url == ""
+ assert entry.version # non-empty
+
+
+def test_from_server_with_base_url():
+ entry = ServerRegistryEntry.from_server(
+ host="0.0.0.0",
+ port=8080,
+ base_url="/prefix",
+ )
+ assert entry.server_id == "0.0.0.0:8080"
+ assert entry.base_url == "/prefix"