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.

Publish resumable host events for editor sessions (#11304)

Trevor Manz03a7f176c86e
diff --git a/marimo/_core/host.py b/marimo/_core/host.py
index 2588cc4076..9441ed9ab6 100644
--- a/marimo/_core/host.py
+++ b/marimo/_core/host.py
@@ -55,9 +55,9 @@ class _NotebookSink(Sink):
return event
with self._stream.deferred():
removals = self._log.observe(event)
- recorded = self._stream.append(event)
+ recorded = self._stream._append(event)
for removed in removals:
- self._stream.append(removed)
+ self._stream._append(removed)
return recorded
diff --git a/marimo/_core/stream.py b/marimo/_core/stream.py
index 187dd51757..eb21e0cf9b 100644
--- a/marimo/_core/stream.py
+++ b/marimo/_core/stream.py
@@ -152,7 +152,10 @@ class Event:
"""Whether the event belongs in the catalog or notebook stream."""
if notebook_id is None:
return self.kind in CATALOG_KINDS
- return self.notebook_id == notebook_id and self.kind in NOTEBOOK_KINDS
+ return self.notebook_id == notebook_id and (
+ self.kind in NOTEBOOK_KINDS
+ or (self.kind is None and self.name not in ("ready", "reset"))
+ )
def wanted(
self, types: Collection[str] | None, run_id: str | None = None
@@ -160,7 +163,7 @@ class Event:
"""Apply kind and run filters, always including `ready` and `reset`."""
if self.name in ("ready", "reset"):
return True
- return (types is None or self.kind in types) and (
+ return (types is None or (self.kind or self.name) in types) and (
run_id is None or self.run_id == run_id
)
@@ -175,6 +178,10 @@ class Sink(ABC):
each event before the stream records it.
"""
+ def append(self, event: Event) -> Event:
+ """Record an event without requiring a public protocol type."""
+ return self._append(deepcopy(event))
+
def publish(
self,
body: Body,
@@ -215,7 +222,11 @@ class Sink(ABC):
@abstractmethod
def _append(self, event: Event) -> Event:
- """Record an event and return it as recorded."""
+ """Record an owned event and return an isolated copy as recorded.
+
+ The event must already be isolated from the caller. Forward it to
+ another sink's `_append` without copying it again.
+ """
class Stream(Sink):
@@ -281,10 +292,6 @@ class Stream(Sink):
self._dispatching = False
self._drain()
- def append(self, event: Event) -> Event:
- """Record an emitted event with a cursor belonging to this log."""
- return self._append(deepcopy(event))
-
def _append(self, event: Event) -> Event:
self._last_id += 1
stamped = Event(
diff --git a/marimo/_server/api/endpoints/ws/session_handler.py b/marimo/_server/api/endpoints/ws/session_handler.py
index 11955c5f20..70da09d458 100644
--- a/marimo/_server/api/endpoints/ws/session_handler.py
+++ b/marimo/_server/api/endpoints/ws/session_handler.py
@@ -75,6 +75,8 @@ class SessionHandler(SessionConsumer, abc.ABC):
`message_queue`.
"""
+ _replay_notebook_on_reconnect = False
+
def __init__(
self,
*,
@@ -311,7 +313,9 @@ class SessionHandler(SessionConsumer, abc.ABC):
description="You have reconnected to an existing session.",
)
)
- self._write_environment_state(session)
+ self._replay_previous_session(
+ session, include_notebook=self._replay_notebook_on_reconnect
+ )
return
self._write_kernel_ready_from_session_view(session, self.params.kiosk)
@@ -357,29 +361,15 @@ class SessionHandler(SessionConsumer, abc.ABC):
# Replay all operations
self._replay_previous_session(session)
- def _write_environment_state(self, session: Session) -> None:
- # Attachment and snapshot delivery run in one event-loop turn, before
- # any later live deltas. Empty states also clear a previous session.
- for source in ("kernel", "server"):
- self._serialize_and_notify(
- EnvironmentStateNotification(
- source=source,
- state=session.session_view.get_environment_state(source),
- )
- )
- if session.session_view.startup_progress is not None:
- # Completed startup follows kernel-ready/reconnected on the normal
- # queue, so replay cannot put a ready notebook back into startup.
- self._serialize_and_notify(session.session_view.startup_progress)
-
- def _replay_previous_session(self, session: Session) -> None:
- """Replay the previous session view."""
- self._write_environment_state(session)
- notifications = session.session_view.notifications
- if len(notifications) == 0:
- LOGGER.debug("No notifications to replay")
- return
- LOGGER.debug(f"Replaying {len(notifications)} notifications")
+ def _replay_previous_session(
+ self, session: Session, *, include_notebook: bool = True
+ ) -> None:
+ """Replay retained state to this client."""
+ # Send after kernel-ready/reconnected and before later live deltas.
+ notifications = session.session_view.snapshot_notifications(
+ include_notebook=include_notebook
+ )
+ LOGGER.debug("Replaying %s notifications", len(notifications))
for notif in notifications:
LOGGER.debug("Replaying notification %s", notif)
self._serialize_and_notify(notif)
diff --git a/marimo/_server/api/endpoints/ws/ws_message_loop.py b/marimo/_server/api/endpoints/ws/ws_message_loop.py
index c9a75578d9..cf27998d4a 100644
--- a/marimo/_server/api/endpoints/ws/ws_message_loop.py
+++ b/marimo/_server/api/endpoints/ws/ws_message_loop.py
@@ -33,7 +33,7 @@ KIOSK_EXCLUDED_OPERATIONS = {
}
-def _should_filter_operation(op: str, *, is_kiosk: bool) -> bool:
+def should_filter_operation(op: str, *, is_kiosk: bool) -> bool:
"""Determine if operation should be filtered based on kiosk mode.
Args:
@@ -71,7 +71,7 @@ def prepare_wire_message(data: KernelMessage, *, is_kiosk: bool) -> str | None:
"""
op: str = deserialize_kernel_notification_name(data)
- if _should_filter_operation(op, is_kiosk=is_kiosk):
+ if should_filter_operation(op, is_kiosk=is_kiosk):
return None
try:
diff --git a/marimo/_server/api/router.py b/marimo/_server/api/router.py
index fe942ec421..6dd0570bd7 100644
--- a/marimo/_server/api/router.py
+++ b/marimo/_server/api/router.py
@@ -31,6 +31,7 @@ from marimo._server.api.endpoints.sql import router as sql_router
from marimo._server.api.endpoints.storage import router as storage_router
from marimo._server.api.endpoints.terminal import router as terminal_router
from marimo._server.api.endpoints.ws_endpoint import router as ws_router
+from marimo._server.host.api import editor_events_route
from marimo._server.router import APIRouter
if TYPE_CHECKING:
@@ -83,6 +84,8 @@ def build_routes(base_url: str = "") -> list[BaseRoute]:
packages_router, prefix="/api/packages", name="packages"
)
app_router.include_router(lsp_router, prefix="/api/lsp", name="lsp")
+ # Register before the catch-all mount shared by health, ws, and assets.
+ app_router.routes.append(editor_events_route(base_url))
app_router.include_router(health_router, name="health")
app_router.include_router(ws_router, name="ws")
app_router.include_router(assets_router, name="assets")
diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.py
index dd74271b1a..43f2606721 100644
--- a/marimo/_server/host/api.py
+++ b/marimo/_server/host/api.py
@@ -7,15 +7,18 @@ import asyncio
import hashlib
import threading
from collections.abc import Awaitable, Callable
+from contextlib import contextmanager
from functools import wraps
from pathlib import Path
from typing import TYPE_CHECKING, TypeAlias, TypeVar, get_args
from urllib.parse import quote
import msgspec
+from anyio import create_task_group
from starlette.exceptions import HTTPException
from starlette.responses import Response, StreamingResponse
-from starlette.routing import Route, Router
+from starlette.routing import Route, Router, WebSocketRoute
+from starlette.websockets import WebSocket, WebSocketDisconnect
from marimo import _loggers
from marimo._core import protocol
@@ -27,20 +30,30 @@ from marimo._core.errors import (
NoRuntime,
NotFound,
)
-from marimo._server.api.auth import TOKEN_QUERY_PARAM
-from marimo._server.api.deps import AppStateBase
+from marimo._server.api.auth import TOKEN_QUERY_PARAM, validate_auth
+from marimo._server.api.deps import AppState, AppStateBase
+from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ ConnectionRejection,
+ parse_connection_params,
+)
+from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGER
from marimo._server.api.utils import format_url_host, open_url_in_browser
+from marimo._server.host import HOST_API_PATH
from marimo._server.host.context import CachedMutation
+from marimo._server.host.events import serialize_event
+from marimo._server.host.websocket import EditorEventSocket
from marimo._server.sse import SSE_HEADERS
from marimo._server.tokens import AuthToken
if TYPE_CHECKING:
- from collections.abc import AsyncIterator
+ from collections.abc import AsyncIterator, Iterator
- from starlette.requests import Request
+ from anyio import CancelScope
+ from starlette.requests import HTTPConnection, Request
from marimo._core.notebook import Notebook
from marimo._core.stream import Event
+ from marimo._server.host.bridge import SessionBridge
from marimo._server.host.context import HostContext
LOGGER = _loggers.marimo_logger()
@@ -65,7 +78,9 @@ _ATTACHMENT_HEADERS = {
PING = b": ping\n\n"
PING_SECONDS = 15.0
-OBJECT_TYPES = frozenset(get_args(get_args(protocol.ObjectType)[0]))
+OBJECT_TYPES = frozenset(get_args(get_args(protocol.ObjectType)[0])) | {
+ "marimo"
+}
"""Values the `types` stream filter accepts."""
_TITLES = {
@@ -133,6 +148,7 @@ def build_app() -> Router:
Route("/notebooks/{id}", _update_notebook, methods=["PATCH"]),
Route("/notebooks/{id}", _delete_notebook, methods=["DELETE"]),
Route("/notebooks/{id}/events", _notebook_events, methods=["GET"]),
+ WebSocketRoute("/notebooks/{id}/events/ws", _notebook_events_ws),
Route("/notebooks/{id}/edits", _edit_notebook, methods=["POST"]),
Route("/notebooks/{id}/save", _save_notebook, methods=["POST"]),
Route("/notebooks/{id}/open", _open_notebook, methods=["POST"]),
@@ -153,7 +169,7 @@ def build_app() -> Router:
for route in routes:
# Starlette implies HEAD for every GET route, but a HEAD here would
# open a real stream and attach a client nobody can see.
- if route.methods == {"GET", "HEAD"}:
+ if isinstance(route, Route) and route.methods == {"GET", "HEAD"}:
route.methods = {"GET"}
return Router(
routes=routes,
@@ -164,16 +180,21 @@ def build_app() -> Router:
async def _not_found(scope, receive, send) -> None: # type: ignore[no-untyped-def]
+ if scope["type"] == "websocket":
+ await WebSocket(scope, receive, send).close(
+ code=1008, reason="No such route"
+ )
+ return
await problem(404, "not-found", "No such route")(scope, receive, send)
-def _context(request: Request) -> HostContext:
+def _context(request: HTTPConnection) -> HostContext:
context = getattr(request.app.state, "host_context", None)
assert context is not None, "HostApiMiddleware admits requests only then"
return context # type: ignore[no-any-return]
-async def _notebook(request: Request) -> Notebook:
+async def _notebook(request: HTTPConnection) -> Notebook:
return await _context(request).bridge.host.notebook(
request.path_params["id"]
)
@@ -454,8 +475,160 @@ async def _notebook_events(request: Request) -> Response:
)
-def _cursor(request: Request) -> int | Response | None:
+def editor_events_route(base_url: str = "") -> WebSocketRoute:
+ """Expose the notebook event socket through editor authentication."""
+ return WebSocketRoute(
+ f"{base_url}{HOST_API_PATH}/notebooks/{{id}}/events/ws",
+ _editor_events_ws,
+ )
+
+
+async def _editor_events_ws(websocket: WebSocket) -> None:
+ state = AppStateBase.from_app(websocket.app)
+ if state.enable_auth and not validate_auth(websocket):
+ await websocket.close(
+ code=1008, reason="Editor authentication required"
+ )
+ return
+ # TODO: Move editor lifecycle and recipient routing to host attachments so
+ # event subscriptions no longer need the legacy session_id.
+ if "session_id" not in websocket.query_params:
+ await _notebook_events_ws(websocket)
+ return
+
+ if "run_id" in websocket.query_params:
+ await websocket.close(
+ code=1008,
+ reason="Editor sessions do not support run_id filtering",
+ )
+ return
+
+ cursor = _cursor(websocket)
+ if isinstance(cursor, Response):
+ await websocket.close(code=1008, reason="Invalid event cursor")
+ return
+ types = _types(websocket)
+ if isinstance(types, Response):
+ await websocket.close(code=1008, reason="Invalid event types")
+ return
+ app_state = AppState(websocket)
+ params = parse_connection_params(app_state)
+ if isinstance(params, ConnectionRejection):
+ await websocket.close(params.code, params.reason)
+ return
+ bridge = _context(websocket).bridge
+ try:
+ notebook = await _notebook(websocket)
+ except (NotFound, Conflict) as exc:
+ await websocket.close(code=1008, reason=str(exc))
+ return
+ manager = app_state.session_manager
+ app = manager.app_manager(params.file_key)
+ record = bridge.index.notebook_for(app.path)
+ existing = manager.get_session(params.session_id)
+ if (
+ record is None
+ or record.id != notebook.id
+ or (
+ existing is not None and existing.app_file_manager.path != app.path
+ )
+ ):
+ await websocket.close(
+ code=1008, reason="Session notebook does not match"
+ )
+ return
+ await EditorEventSocket(
+ websocket,
+ notebook=notebook,
+ bridge=bridge,
+ manager=manager,
+ params=params,
+ doc_manager=DOC_MANAGER,
+ types=types,
+ cursor=cursor,
+ ).start()
+
+
+async def _notebook_events_ws(websocket: WebSocket) -> None:
+ """Send a snapshot or replay, then live notebook events."""
+ cursor = _cursor(websocket)
+ if isinstance(cursor, Response):
+ await websocket.close(code=1008, reason="Invalid event cursor")
+ return
+ types = _types(websocket)
+ if isinstance(types, Response):
+ await websocket.close(code=1008, reason="Invalid event types")
+ return
+ run_id = websocket.query_params.get("run_id")
+ if run_id == "":
+ await websocket.close(code=1008, reason="run_id must not be empty")
+ return
+ try:
+ notebook = await _notebook(websocket)
+ attachment = notebook.attach(
+ identity=websocket.headers.get(ATTACHMENT_IDENTITY),
+ kind=websocket.headers.get(ATTACHMENT_KIND),
+ name=websocket.headers.get(ATTACHMENT_NAME),
+ )
+ except (NotFound, Conflict) as exc:
+ await websocket.close(code=1008, reason=str(exc))
+ return
+ except msgspec.ValidationError as exc:
+ await websocket.close(code=1008, reason=_attachment_problem(exc))
+ return
+
+ bridge = _context(websocket).bridge
+
+ async def send_events(
+ subscription: _EventSubscription, cancel_scope: CancelScope
+ ) -> None:
+ try:
+ for event in subscription.initial:
+ await websocket.send_text(serialize_event(event))
+ while True:
+ event = await subscription.next()
+ await websocket.send_text(serialize_event(event))
+ except WebSocketDisconnect:
+ cancel_scope.cancel()
+
+ message = None
+ try:
+ with _subscribe_events(
+ bridge,
+ cursor,
+ types,
+ notebook_id=notebook.id,
+ run_id=run_id,
+ include_session=True,
+ ) as subscription:
+ await websocket.accept()
+ async with create_task_group() as tasks:
+ tasks.start_soon(send_events, subscription, tasks.cancel_scope)
+ try:
+ message = await websocket.receive()
+ finally:
+ tasks.cancel_scope.cancel()
+ if (
+ message is not None
+ and message["type"] != "websocket.disconnect"
+ ):
+ await websocket.close(
+ code=1003, reason="This socket only sends events"
+ )
+ except WebSocketDisconnect:
+ pass
+ finally:
+ notebook.detach(attachment.id)
+
+
+def _cursor(request: HTTPConnection) -> int | Response | None:
raw = request.headers.get("Last-Event-ID")
+ if request.scope["type"] == "websocket":
+ query = request.query_params.get("cursor")
+ if query is not None:
+ if raw is not None and raw != query:
+ return problem(400, "invalid-request", "Conflicting cursors")
+ raw = query
if raw is None:
return None
# Header text is latin-1, where superscripts count as digits.
@@ -467,7 +640,7 @@ def _cursor(request: Request) -> int | Response | None:
return problem(400, "invalid-request", "Last-Event-ID is too long")
-def _types(request: Request) -> set[str] | Response | None:
+def _types(request: HTTPConnection) -> set[str] | Response | None:
asked = request.query_params.get("types")
if not asked:
return None
@@ -491,45 +664,109 @@ def _attachment_problem(error: msgspec.ValidationError) -> str:
return "attachment headers are invalid"
+def _initial_events(
+ bridge: SessionBridge,
+ cursor: int | None,
+ types: set[str] | None,
+ *,
+ notebook_id: protocol.NotebookId | None,
+ run_id: str | None = None,
+ include_session: bool = False,
+) -> list[Event]:
+ """Capture a snapshot or replay, with `ready` marking its end."""
+ events = bridge.host.events(
+ cursor, notebook_id=notebook_id, types=types, run_id=run_id
+ )
+ needs_snapshot = cursor is None or events[0].name == "reset"
+ if include_session and notebook_id is not None and needs_snapshot:
+ ready = events.pop()
+ events.extend(
+ event
+ for event in bridge.session_snapshot(notebook_id)
+ if event.wanted(types, run_id)
+ )
+ events.append(ready)
+ return events
+
+
+class _EventSubscription:
+ def __init__(
+ self, initial: list[Event], queue: asyncio.Queue[Event]
+ ) -> None:
+ self.initial = initial
+ self._queue = queue
+ self._ready_id = initial[-1].id or 0
+
+ async def next(self) -> Event:
+ """Wait for a live event not already covered by the initial state."""
+ while True:
+ event = await self._queue.get()
+ if event.id is None or event.id > self._ready_id:
+ return event
+
+
+@contextmanager
+def _subscribe_events(
+ bridge: SessionBridge,
+ cursor: int | None,
+ types: set[str] | None,
+ *,
+ notebook_id: protocol.NotebookId | None,
+ run_id: str | None = None,
+ include_session: bool = False,
+) -> Iterator[_EventSubscription]:
+ queue: asyncio.Queue[Event] = asyncio.Queue()
+ # Subscribe and capture state in one event-loop turn to avoid lost updates.
+ unsubscribe = bridge.host.subscribe(
+ queue.put_nowait,
+ notebook_id=notebook_id,
+ types=types,
+ run_id=run_id,
+ )
+ try:
+ initial = _initial_events(
+ bridge,
+ cursor,
+ types,
+ notebook_id=notebook_id,
+ run_id=run_id,
+ include_session=include_session,
+ )
+ yield _EventSubscription(initial, queue)
+ finally:
+ unsubscribe()
+
+
def _stream(
context: HostContext,
cursor: int | None,
types: set[str] | None,
*,
- notebook_id: str | None,
+ notebook_id: protocol.NotebookId | None,
run_id: str | None = None,
on_close: Callable[[], None] | None = None,
) -> Response:
- host = context.bridge.host
-
async def body() -> AsyncIterator[bytes]:
- queue: asyncio.Queue[Event] = asyncio.Queue()
- # Subscribe before reading initial events to avoid losing updates.
- # Queued events at or before the ready cursor are skipped.
- unsubscribe = host.subscribe(
- queue.put_nowait,
- notebook_id=notebook_id,
- types=types,
- run_id=run_id,
- )
try:
- initial = host.events(
- cursor, notebook_id=notebook_id, types=types, run_id=run_id
- )
- for event in initial:
- yield _frame(event)
- ready_id = initial[-1].id or 0
- while True:
- try:
- event = await asyncio.wait_for(queue.get(), PING_SECONDS)
- except asyncio.TimeoutError:
- yield PING
- continue
- if event.id is not None and event.id <= ready_id:
- continue
- yield _frame(event)
+ with _subscribe_events(
+ context.bridge,
+ cursor,
+ types,
+ notebook_id=notebook_id,
+ run_id=run_id,
+ ) as subscription:
+ for event in subscription.initial:
+ yield _frame(event)
+ while True:
+ try:
+ event = await asyncio.wait_for(
+ subscription.next(), PING_SECONDS
+ )
+ except asyncio.TimeoutError:
+ yield PING
+ continue
+ yield _frame(event)
finally:
- unsubscribe()
if on_close is not None:
on_close()
diff --git a/marimo/_server/host/backend.py b/marimo/_server/host/backend.py
index 0169389c59..9e125806ba 100644
--- a/marimo/_server/host/backend.py
+++ b/marimo/_server/host/backend.py
@@ -21,6 +21,7 @@ from marimo._messaging.notification import (
from marimo._messaging.serde import deserialize_kernel_message
from marimo._runtime.commands import ExecuteScratchpadCommand
from marimo._runtime.scratch import SCRATCH_CELL_ID
+from marimo._server.host.events import notification_event
from marimo._server.host.translate import RunTranslator
from marimo._server.scratchpad import snapshot_for_scratchpad
from marimo._session.consumer import SessionConsumer
@@ -31,6 +32,8 @@ from marimo._types.ids import ConsumerId, SessionId
from marimo._version import __version__
if TYPE_CHECKING:
+ from marimo._core.stream import Sink
+ from marimo._messaging.notification import NotificationMessage
from marimo._messaging.types import KernelMessage
from marimo._server.session_manager import SessionManager
from marimo._session.events import SessionEventBus
@@ -77,6 +80,7 @@ class SessionBackend(SessionConsumer):
file: Callable[[], str | None],
manager: SessionManager,
observe: Observe,
+ sink: Sink,
document_changed: Callable[[], None] | None = None,
session_attached: Callable[[], None] | None = None,
session_detached: Callable[[Session], None] | None = None,
@@ -86,6 +90,7 @@ class SessionBackend(SessionConsumer):
"""Resolve the notebook's current path after file moves."""
self._manager = manager
self._observe = observe
+ self._sink = sink
self._document_changed = document_changed
"""Called after the session's document changes, from any writer."""
self._session_attached = session_attached
@@ -292,6 +297,11 @@ class SessionBackend(SessionConsumer):
def notify(self, notification: KernelMessage) -> None:
message = deserialize_kernel_message(notification)
+ with self._sink.deferred():
+ self._sink.append(notification_event(self._notebook_id, message))
+ self._handle_notification(message)
+
+ def _handle_notification(self, message: NotificationMessage) -> None:
if isinstance(message, NotebookDocumentTransactionNotification):
if self._document_changed is not None and self.session is not None:
self._document_changed()
diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.py
index 3c98b9726b..94880074d6 100644
--- a/marimo/_server/host/bridge.py
+++ b/marimo/_server/host/bridge.py
@@ -24,6 +24,7 @@ from marimo._runtime.commands import RenameNotebookCommand
from marimo._server.host import OPERATIONS, document as documents
from marimo._server.host.analysis import HostAnalyzer
from marimo._server.host.backend import SessionBackend
+from marimo._server.host.events import notification_event
from marimo._server.host.index import WorkspaceIndex
from marimo._session.events import SessionEventListener
from marimo._session.notebook.storage import rename_no_replace
@@ -163,7 +164,7 @@ class SessionBridge(SessionEventListener):
saved_etag = document.etag if session is None else None
if session is not None and loaded is not None:
saved_etag = Document(loaded.cells, loaded.app_config).etag
- backend = self._make_backend(record.id)
+ backend = self._make_backend(record.id, sink)
return Notebook(
record.id,
document,
@@ -380,6 +381,18 @@ class SessionBridge(SessionEventListener):
cells=response.cells, document=mirrored.document
)
+ def session_snapshot(
+ self, notebook_id: protocol.NotebookId
+ ) -> list[Event]:
+ """Return retained marimo events for one client without publishing them."""
+ session = self._session_of(notebook_id)
+ if session is None:
+ return []
+ return [
+ notification_event(notebook_id, notification)
+ for notification in session.session_view.snapshot_notifications()
+ ]
+
def _session_of(self, notebook_id: protocol.NotebookId) -> Session | None:
backend = self._backends.get(notebook_id)
return None if backend is None else backend.session
@@ -615,7 +628,7 @@ class SessionBridge(SessionEventListener):
self.index.moved(notebook_id, str(target), request_id=request_id)
def _make_backend(
- self, notebook_id: protocol.NotebookId
+ self, notebook_id: protocol.NotebookId, sink: Sink
) -> SessionBackend:
def file() -> str | None:
path = self.index.file_of(notebook_id)
@@ -635,6 +648,7 @@ class SessionBridge(SessionEventListener):
file,
self._manager,
observe,
+ sink,
document_changed=lambda: self._mirror(notebook_id),
session_attached=lambda: self._attach_document(notebook_id),
session_detached=lambda session: self._detach_document(
diff --git a/marimo/_server/host/events.py b/marimo/_server/host/events.py
new file mode 100644
index 0000000000..07246a34cc
--- /dev/null
+++ b/marimo/_server/host/events.py
@@ -0,0 +1,43 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal marimo events for the host stream."""
+
+from __future__ import annotations
+
+import msgspec
+
+from marimo._core import protocol
+from marimo._core.stream import Event
+from marimo._messaging.notification import NotificationMessage
+
+
+class MarimoMessage(msgspec.Struct, frozen=True):
+ """A marimo notification carried by the host event stream.
+
+ This type is internal to marimo and may change between releases.
+ """
+
+ marimo: NotificationMessage
+
+
+def notification_event(
+ notebook_id: protocol.NotebookId, notification: NotificationMessage
+) -> Event:
+ """Wrap a notification with its notebook and optional run scope."""
+ run_id = getattr(notification, "run_id", None)
+ return Event(
+ "marimo",
+ MarimoMessage(notification),
+ notebook_id=notebook_id,
+ run_id=protocol.RunId(run_id) if run_id is not None else None,
+ )
+
+
+def serialize_event(event: Event) -> str:
+ """Encode one host event as a WebSocket frame."""
+ frame: dict[str, object] = {
+ "event": event.name,
+ "data": {} if event.data is None else event.data,
+ }
+ if event.id is not None:
+ frame["id"] = str(event.id)
+ return msgspec.json.encode(frame).decode()
diff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.py
index c057d463cb..1a630aab74 100644
--- a/marimo/_server/host/middleware.py
+++ b/marimo/_server/host/middleware.py
@@ -1,8 +1,9 @@
# Copyright 2026 Marimo. All rights reserved.
"""Local access and bearer-token authentication for the host API.
-Requests must come from loopback and address a loopback name on the
-server's port. The bearer token comes from the host discovery record.
+Host bearer requests must come from loopback and address a loopback name
+on the server's port. The bearer token comes from the host discovery record.
+The notebook event socket also accepts the editor's authentication.
"""
from __future__ import annotations
@@ -13,12 +14,13 @@ from ipaddress import IPv6Address, ip_address
from typing import TYPE_CHECKING
from starlette.exceptions import HTTPException
-from starlette.requests import Request
+from starlette.requests import HTTPConnection
from starlette.routing import Match, Route
+from starlette.websockets import WebSocket
from marimo import _loggers
from marimo._server.host import HOST_API_PATH
-from marimo._server.host.api import build_app, problem
+from marimo._server.host.api import build_app, editor_events_route, problem
if TYPE_CHECKING:
from collections.abc import Sequence
@@ -39,19 +41,31 @@ class HostApiMiddleware:
self.app = app
self.prefix = base_url + HOST_API_PATH
self.host_app = build_app()
+ self.editor_socket = editor_events_route(base_url)
async def __call__(
self, scope: Scope, receive: Receive, send: Send
) -> None:
- if scope["type"] != "http" or not self._is_host_path(scope["path"]):
+ if scope["type"] not in (
+ "http",
+ "websocket",
+ ) or not self._is_host_path(scope["path"]):
await self.app(scope, receive, send)
return
- request = Request(scope)
+ request = HTTPConnection(scope)
client = scope.get("client")
context = getattr(request.app.state, "host_context", None)
if context is None:
response = problem(404, "not-found", "This server is not a host")
+ elif self.editor_socket.matches(scope)[
+ 0
+ ] is Match.FULL and not _bearer_matches(
+ request.headers.get("Authorization"), context.token
+ ):
+ # Let the editor middleware load the cookie before authenticating.
+ await self.app(scope, receive, send)
+ return
elif client is None or not _is_loopback(client[0]):
response = problem(
403, "forbidden", "The host API answers only this machine"
@@ -74,7 +88,11 @@ class HostApiMiddleware:
async def guarded(message: Message) -> None:
nonlocal started
- if message["type"] == "http.response.start":
+ if message["type"] in (
+ "http.response.start",
+ "websocket.accept",
+ "websocket.close",
+ ):
started = True
await send(message)
@@ -86,21 +104,33 @@ class HostApiMiddleware:
# The bare router has no exception middleware, so a known
# path with an unsupported method surfaces here as a 405.
response = _router_problem(exc, scope, self.host_app.routes)
- await response(scope, receive, send)
+ await _respond(response, scope, receive, send)
except Exception:
if started:
# The server logs the failure once it ends the stream.
raise
LOGGER.exception("The host API failed on %s", scope["path"])
response = problem(500, "internal", "The host failed")
- await response(scope, receive, send)
+ await _respond(response, scope, receive, send)
return
- await response(scope, receive, send)
+ await _respond(response, scope, receive, send)
def _is_host_path(self, path: str) -> bool:
return path == self.prefix or path.startswith(self.prefix + "/")
+async def _respond(
+ response: Response, scope: Scope, receive: Receive, send: Send
+) -> None:
+ if scope["type"] == "websocket":
+ await WebSocket(scope, receive, send).close(
+ code=1008,
+ reason=f"Host API request rejected ({response.status_code})",
+ )
+ else:
+ await response(scope, receive, send)
+
+
def _router_problem(
exc: HTTPException, scope: Scope, routes: Sequence[BaseRoute]
) -> Response:
diff --git a/marimo/_server/host/websocket.py b/marimo/_server/host/websocket.py
new file mode 100644
index 0000000000..64609865ff
--- /dev/null
+++ b/marimo/_server/host/websocket.py
@@ -0,0 +1,196 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Editor sessions carried by the host event socket."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from starlette.websockets import WebSocketDisconnect, WebSocketState
+
+from marimo._messaging.notification import KernelStartupErrorNotification
+from marimo._messaging.serde import deserialize_kernel_message
+from marimo._server.api.endpoints.ws.session_handler import SessionHandler
+from marimo._server.api.endpoints.ws.ws_message_loop import (
+ should_filter_operation,
+)
+from marimo._server.api.endpoints.ws.ws_session_connector import ConnectionType
+from marimo._server.codes import WebSocketCloseReason, WebSocketCodes
+from marimo._server.host.events import (
+ MarimoMessage,
+ notification_event,
+ serialize_event,
+)
+from marimo._session.managers.ipc import KernelStartupError
+from marimo._utils.asyncio_utils import cancel_and_wait
+
+if TYPE_CHECKING:
+ from starlette.websockets import WebSocket
+
+ from marimo._core.notebook import Notebook
+ from marimo._core.stream import Event
+ from marimo._messaging.types import KernelMessage
+ from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ ConnectionParams,
+ )
+ from marimo._server.host.bridge import SessionBridge
+ from marimo._server.rtc.doc import LoroDocManager
+ from marimo._server.session_manager import SessionManager
+
+
+@dataclass(frozen=True)
+class _Close:
+ code: int
+ reason: str
+
+
+class EditorEventSocket(SessionHandler):
+ """Merge host events with the session's private notification delivery."""
+
+ # Shared-log replay omits native notifications to preserve recipients.
+ _replay_notebook_on_reconnect = True
+
+ def __init__(
+ self,
+ websocket: WebSocket,
+ *,
+ notebook: Notebook,
+ bridge: SessionBridge,
+ manager: SessionManager,
+ params: ConnectionParams,
+ doc_manager: LoroDocManager,
+ types: set[str] | None,
+ cursor: int | None,
+ ) -> None:
+ super().__init__(
+ manager=manager,
+ params=params,
+ mode=manager.mode,
+ doc_manager=doc_manager,
+ )
+ self.websocket = websocket
+ self.notebook = notebook
+ self.bridge = bridge
+ self.types = types
+ self.cursor = cursor
+ self._ready_id = 0
+ self._events: asyncio.Queue[Event | _Close] = asyncio.Queue()
+ self._connection_type = (
+ ConnectionType.RTC_EXISTING
+ if params.rtc_enabled and not params.kiosk
+ else ConnectionType.NEW
+ )
+
+ def notify(self, notification: KernelMessage) -> None:
+ event = notification_event(
+ self.notebook.id, deserialize_kernel_message(notification)
+ )
+ if event.wanted(self.types):
+ self._events.put_nowait(event)
+
+ def _on_host_event(self, event: Event) -> None:
+ # The session delivers marimo notifications with recipient filtering,
+ # including edits that must not echo to the client that sent them.
+ if event.name != "marimo" and (
+ event.id is None or event.id > self._ready_id
+ ):
+ self._events.put_nowait(event)
+
+ async def start(self) -> None:
+ attachment = self.notebook.attach(identity=self.params.session_id)
+ unsubscribe = self.bridge.host.subscribe(
+ self._on_host_event,
+ notebook_id=self.notebook.id,
+ types=self.types,
+ )
+ try:
+ initial = self.bridge.host.events(
+ self.cursor, notebook_id=self.notebook.id, types=self.types
+ )
+ self._ready_id = initial[-1].id or 0
+ for event in initial:
+ # Session notifications must retain their recipient filtering,
+ # including on reconnect; only protocol records use replay.
+ if event.name != "marimo":
+ self._events.put_nowait(event)
+ await self.websocket.accept()
+ async with self._connection_lifetime(self.websocket) as startup:
+ sending = asyncio.create_task(self._send_events())
+
+ async def connect_and_listen() -> None:
+ try:
+ _, self._connection_type = await startup
+ except asyncio.CancelledError:
+ return
+ except KernelStartupError as exc:
+ self._serialize_and_notify(
+ KernelStartupErrorNotification(error=str(exc))
+ )
+ self._request_close(
+ WebSocketCodes.UNEXPECTED_ERROR,
+ WebSocketCloseReason.KERNEL_STARTUP_ERROR,
+ )
+ await sending
+ return
+ except WebSocketDisconnect as exc:
+ self._request_close(exc.code, exc.reason or "")
+ await sending
+ return
+ self._check_status_update()
+ await self._wait_for_disconnect()
+
+ listening = asyncio.create_task(connect_and_listen())
+ try:
+ done, _ = await asyncio.wait(
+ (sending, listening),
+ return_when=asyncio.FIRST_COMPLETED,
+ )
+ for task in done:
+ task.result()
+ except WebSocketDisconnect:
+ pass
+ finally:
+ await cancel_and_wait(listening)
+ await cancel_and_wait(sending)
+ finally:
+ unsubscribe()
+ self.notebook.detach(attachment.id)
+
+ async def _send_events(self) -> None:
+ while True:
+ event = await self._events.get()
+ if isinstance(event, _Close):
+ if (
+ self.websocket.client_state
+ is not WebSocketState.DISCONNECTED
+ ):
+ await self.websocket.close(event.code, event.reason)
+ return
+ if isinstance(event.data, MarimoMessage):
+ viewer = self.params.kiosk
+ if self._session is not None:
+ viewer = self._is_viewer(
+ self._session, self._connection_type
+ )
+ if should_filter_operation(
+ event.data.marimo.name, is_kiosk=viewer
+ ):
+ continue
+ await self.websocket.send_text(serialize_event(event))
+
+ async def _wait_for_disconnect(self) -> None:
+ while True:
+ message = await self.websocket.receive()
+ if message["type"] == "websocket.disconnect":
+ return
+
+ def _request_close(self, code: int, reason: str) -> None:
+ self._events.put_nowait(_Close(code, reason))
+
+ def _is_transport_connected(self) -> bool:
+ return self.websocket.application_state is WebSocketState.CONNECTED
+
+ def _cancel_message_loop(self) -> None:
+ # on_detach queues a close behind pending notifications.
+ pass
diff --git a/marimo/_session/state/session_view.py b/marimo/_session/state/session_view.py
index f525d8b654..f8e8198306 100644
--- a/marimo/_session/state/session_view.py
+++ b/marimo/_session/state/session_view.py
@@ -18,6 +18,7 @@ from marimo._messaging.notification import (
DataSourceConnectionsNotification,
EnvironmentOperationNotification,
EnvironmentState,
+ EnvironmentStateNotification,
EsmSpec,
InterruptedNotification,
ModelClose,
@@ -599,8 +600,25 @@ class SessionView:
self.last_execution_time[cell_id] = time_elapsed
- @property
- def notifications(self) -> list[NotificationMessage]:
+ def snapshot_notifications(
+ self, *, include_notebook: bool = True
+ ) -> list[NotificationMessage]:
+ """Copy retained notifications for a connecting client.
+
+ An existing client can omit notebook state and refresh only its
+ environment and startup status. The caller supplies kernel-ready.
+ """
+ notifications: list[NotificationMessage] = [
+ EnvironmentStateNotification(source=source, state=state)
+ for source, state in self._environment_states.items()
+ ]
+ if self.startup_progress is not None:
+ notifications.append(self.startup_progress)
+ if include_notebook:
+ notifications.extend(self._notebook_notifications())
+ return copy.deepcopy(notifications)
+
+ def _notebook_notifications(self) -> list[NotificationMessage]:
all_notifications: list[NotificationMessage] = []
if self.variable_notifications.variables:
all_notifications.append(self.variable_notifications)
diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.py
index 316ecfbb48..23a42efbd5 100644
--- a/tests/_core/test_stream.py
+++ b/tests/_core/test_stream.py
@@ -99,10 +99,13 @@ def test_readers_cannot_change_other_readers_or_replay() -> None:
@pytest.mark.parametrize("external", [False, True])
[email protected]("via_notebook", [False, True])
def test_mutable_payloads_are_isolated_from_callers_and_listeners(
- external: bool,
+ host: Host, notebook: Notebook, external: bool, via_notebook: bool
) -> None:
- stream = Stream()
+ stream = host._stream if via_notebook else Stream()
+ sink = notebook.sink if via_notebook else stream
+ cursor = stream.last_id
payload = protocol.Custom(type="example", data={"values": [1]})
delivered: list[Event] = []
@@ -117,13 +120,13 @@ def test_mutable_payloads_are_isolated_from_callers_and_listeners(
"custom",
protocol.CustomMessage(custom=payload, time=msgspec.UNSET),
)
- published = stream.append(event)
+ published = sink.append(event)
else:
- published = stream.publish(payload)
+ published = sink.publish(payload)
payload.data["values"].append(3)
assert isinstance(published.data, protocol.CustomMessage)
published.data.custom.data["values"].append(4)
- replay = stream.since(0)
+ replay = stream.since(cursor)
assert replay is not None
assert [event.data.custom.data for event in [*delivered, *replay]] == [
{"values": [1]},
diff --git a/tests/_export/test_exporter.py b/tests/_export/test_exporter.py
index 62b2a69e19..731f967a4b 100644
--- a/tests/_export/test_exporter.py
+++ b/tests/_export/test_exporter.py
@@ -269,7 +269,7 @@ async def test_run_notebook_with_stop() -> None:
assert did_error is False
cell_notifications = [
op
- for op in session_view.notifications
+ for op in session_view.snapshot_notifications()
if isinstance(op, CellNotification)
]
snapshot(
@@ -354,7 +354,7 @@ async def test_run_notebook_with_stack_trace() -> None:
assert did_error is True
cell_notifications = [
op
- for op in session_view.notifications
+ for op in session_view.snapshot_notifications()
if isinstance(op, CellNotification)
]
@@ -401,7 +401,7 @@ async def test_run_notebook_with_console_output(
cell_notifications = [
op
- for op in session_view.notifications
+ for op in session_view.snapshot_notifications()
if isinstance(op, CellNotification)
]
snapshot(
@@ -632,7 +632,7 @@ def test_export_as_html_omits_getpass_response(
)
assert secret not in html
- assert secret not in encode_json_str(session_view.notifications)
+ assert secret not in encode_json_str(session_view.snapshot_notifications())
assert parse_mount_config(html)["session"]["cells"][0]["console"] == [
{
"type": "stream",
diff --git a/tests/_server/api/endpoints/test_kiosk.py b/tests/_server/api/endpoints/test_kiosk.py
index 4c978ba9ab..650216c8bd 100644
--- a/tests/_server/api/endpoints/test_kiosk.py
+++ b/tests/_server/api/endpoints/test_kiosk.py
@@ -204,8 +204,6 @@ def test_third_viewer_survives_takeover(client: TestClient) -> None:
def test_capabilities_changed_is_not_recorded(client: TestClient) -> None:
- from marimo._messaging.serde import deserialize_kernel_message
-
with client.websocket_connect("/ws?session_id=a", headers=_HEADERS) as ta:
assert_kernel_ready_response(ta.receive_json())
with client.websocket_connect(
@@ -221,8 +219,7 @@ def test_capabilities_changed_is_not_recorded(client: TestClient) -> None:
sm = client.app.state.session_manager
session = next(iter(sm.sessions.values()))
recorded = [
- deserialize_kernel_message(n).name
- for n in session.session_view.notifications
+ n.name for n in session.session_view.snapshot_notifications()
]
assert "consumer-capabilities" not in recorded
diff --git a/tests/_server/host/drive.py b/tests/_server/host/drive.py
index c22b247a40..64a9e13aa6 100644
--- a/tests/_server/host/drive.py
+++ b/tests/_server/host/drive.py
@@ -16,6 +16,8 @@ if TYPE_CHECKING:
from collections.abc import Callable, MutableMapping
from starlette.applications import Starlette
+ from starlette.testclient import WebSocketTestSession
+ from starlette.types import ASGIApp, Receive, Scope, Send
PORT = 1234
"""Server port used to validate the request's Host header."""
@@ -24,6 +26,31 @@ AUTHORITY = f"127.0.0.1:{PORT}"
LOOPBACK = ("127.0.0.1", 50000)
+def with_client_address(
+ app: ASGIApp, address: tuple[str, int] = LOOPBACK
+) -> ASGIApp:
+ """Set the peer address without requiring Starlette's newer `client` option."""
+
+ async def wrapped(scope: Scope, receive: Receive, send: Send) -> None:
+ if scope["type"] in ("http", "websocket"):
+ scope = {**scope, "client": address}
+ await app(scope, receive, send)
+
+ return wrapped
+
+
+def socket_snapshot(websocket: WebSocketTestSession) -> list[dict[str, Any]]:
+ """Read the opening snapshot or replay, including its ready boundary."""
+ events = []
+ while True:
+ event = websocket.receive_json()
+ events.append(event)
+ if event["event"] == "ready":
+ assert event["data"] == {}
+ assert isinstance(event["id"], str)
+ return events
+
+
class Response:
def __init__(self) -> None:
self.status = 0
diff --git a/tests/_server/host/test_editor_websocket.py b/tests/_server/host/test_editor_websocket.py
new file mode 100644
index 0000000000..6f2859f4de
--- /dev/null
+++ b/tests/_server/host/test_editor_websocket.py
@@ -0,0 +1,418 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""The editor's session lifecycle on the host event stream."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+import msgspec
+import pytest
+from starlette.websockets import WebSocketDisconnect
+
+from marimo._messaging.cell_output import CellChannel, CellOutput
+from marimo._messaging.notification import (
+ AlertNotification,
+ CellNotification,
+ StartupProgressNotification,
+)
+from marimo._messaging.serde import serialize_kernel_message
+from marimo._server.host import HOST_API_PATH
+from marimo._server.host.bridge import SessionBridge
+from marimo._server.host.context import HostContext
+from marimo._session.managers.ipc import KernelStartupError
+from marimo._types.ids import ConsumerId, SessionId
+from tests._server.api.endpoints.ws_helpers import headers
+from tests._server.host.drive import socket_snapshot
+from tests._server.mocks import get_session_manager
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+ from pathlib import Path
+
+ from starlette.testclient import TestClient, WebSocketTestSession
+
+
+def editor_host(client: TestClient) -> Iterator[SessionBridge]:
+ bridge = SessionBridge(get_session_manager(client))
+ client.app.state.host_context = HostContext( # type: ignore[union-attr]
+ bridge=bridge, token="host-token", port=1234
+ )
+ with client:
+ assert client.portal is not None
+ client.portal.call(bridge.open)
+ try:
+ yield bridge
+ finally:
+ client.portal.call(bridge.close)
+
+
+def socket_url(bridge: SessionBridge, session_id: str = "s1") -> str:
+ (notebook_id,) = bridge.host.notebooks
+ return f"{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?session_id={session_id}&access_token=fake-token"
+
+
+def receive_notification(
+ websocket: WebSocketTestSession, op: str
+) -> dict[str, Any]:
+ while True:
+ event = websocket.receive_json()
+ assert "op" not in event
+ if event["event"] == "marimo" and event["data"]["marimo"]["op"] == op:
+ return event["data"]["marimo"]
+
+
[email protected]("types", [None, "marimo", "marimo,run"])
+def test_editor_starts_and_runs_through_the_host_socket(
+ client: TestClient, editor_host: SessionBridge, types: str | None
+) -> None:
+ url = socket_url(editor_host)
+ if types is not None:
+ url += f"&types={types}"
+ with client.websocket_connect(url) as websocket:
+ messages = []
+ while True:
+ event = websocket.receive_json()
+ messages.append(event)
+ if (
+ event["event"] == "marimo"
+ and event["data"]["marimo"]["op"] == "kernel-ready"
+ ):
+ ready = event["data"]["marimo"]
+ break
+ assert ready["resumed"] is False
+ assert ready["consumer_capabilities"]["edit"] is True
+ boundary = next(
+ i for i, event in enumerate(messages) if event["event"] == "ready"
+ )
+ assert all("id" not in event for event in messages[:boundary])
+ assert messages[boundary]["data"] == {}
+ if types is None:
+ names = [event["event"] for event in messages[:boundary]]
+ assert names[0] == "notebook"
+ assert names.index("cell") < names.index("document")
+ cell_id = ready["cell_ids"][0]
+ response = client.post(
+ "/api/kernel/run",
+ headers=headers("s1"),
+ json={"cellIds": [cell_id], "codes": ["print('host socket')"]},
+ )
+ assert response.status_code == 200, response.text
+ while True:
+ event = websocket.receive_json()
+ messages.append(event)
+ if (
+ event["event"] == "marimo"
+ and event["data"]["marimo"]["op"] == "completed-run"
+ ):
+ break
+ received_types = {event["event"] for event in messages}
+ if types is None:
+ assert "run" in received_types
+ else:
+ assert received_types == {*types.split(","), "ready"}
+ consoles = [
+ event["data"]["marimo"]["console"]
+ for event in messages
+ if event["event"] == "marimo"
+ and event["data"]["marimo"]["op"] == "cell-op"
+ and event["data"]["marimo"]["console"]
+ ]
+ assert sum("host socket" in str(output) for output in consoles) == 1
+
+
+def test_reconnect_keeps_state_and_refresh_replays_it(
+ client: TestClient, editor_host: SessionBridge
+) -> None:
+ url = f"{socket_url(editor_host)}&types=marimo"
+ with client.websocket_connect(url) as websocket:
+ ready = receive_notification(websocket, "kernel-ready")
+ cell_id = ready["cell_ids"][0]
+ response = client.post(
+ "/api/kernel/run",
+ headers=headers("s1"),
+ json={"cellIds": [cell_id], "codes": ["print('retained output')"]},
+ )
+ assert response.status_code == 200, response.text
+ receive_notification(websocket, "completed-run")
+ with client.websocket_connect(url) as websocket:
+ socket_snapshot(websocket)
+ while True:
+ event = websocket.receive_json()
+ assert event["event"] == "marimo"
+ notification = event["data"]["marimo"]
+ assert notification["op"] not in ("kernel-ready", "cell-op")
+ if notification["op"] == "reconnected":
+ break
+ assert (
+ receive_notification(websocket, "alert")["title"] == "Reconnected"
+ )
+ cell = receive_notification(websocket, "cell-op")
+ assert cell["cell_id"] == cell_id
+ assert "retained output" in str(cell["console"])
+ with client.websocket_connect(
+ f"{socket_url(editor_host, 's2')}&types=marimo"
+ ) as websocket:
+ ready = receive_notification(websocket, "kernel-ready")
+ assert ready["resumed"] is True
+ assert ready["kiosk"] is False
+ cell = receive_notification(websocket, "cell-op")
+ assert cell["cell_id"] == cell_id
+ assert "retained output" in str(cell["console"])
+
+
[email protected]("replay", ["snapshot", "cursor", "reset"])
+def test_reconnect_recovers_offline_notifications(
+ client: TestClient, editor_host: SessionBridge, replay: str
+) -> None:
+ url = f"{socket_url(editor_host)}&types=marimo"
+ with client.websocket_connect(url) as socket:
+ cursor = socket_snapshot(socket)[-1]["id"]
+ ready = receive_notification(socket, "kernel-ready")
+ session = get_session_manager(client).get_session(SessionId("s1"))
+ assert session is not None
+ assert client.portal is not None
+ update = CellNotification(
+ cell_id=ready["cell_ids"][0],
+ status="idle",
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/plain",
+ data="offline output",
+ timestamp=1.0,
+ ),
+ console=[
+ CellOutput(
+ channel=CellChannel.STDOUT,
+ mimetype="text/plain",
+ data="offline console",
+ timestamp=1.0,
+ )
+ ],
+ timestamp=1.0,
+ )
+ client.portal.call(session.notify, update, None)
+ client.portal.call(
+ session.notify,
+ AlertNotification(title="excluded", description=""),
+ ConsumerId("s1"),
+ )
+ if replay == "cursor":
+ url += f"&cursor={cursor}"
+ elif replay == "reset":
+ url += "&cursor=999999999"
+ with client.websocket_connect(url) as socket:
+ opening = socket_snapshot(socket)
+ assert [event["event"] for event in opening] == (
+ ["reset", "ready"] if replay == "reset" else ["ready"]
+ )
+ receive_notification(socket, "reconnected")
+ client.portal.call(
+ session.notify,
+ AlertNotification(title="marker", description=""),
+ None,
+ )
+ notifications = []
+ while True:
+ event = socket.receive_json()
+ notification = event["data"]["marimo"]
+ if (
+ notification["op"] == "alert"
+ and notification["title"] == "marker"
+ ):
+ break
+ notifications.append(notification)
+ assert [n for n in notifications if n["op"] == "cell-op"] == [
+ msgspec.json.decode(serialize_kernel_message(update))
+ ]
+ assert not any(n["op"] == "kernel-ready" for n in notifications)
+ assert not any(
+ n["op"] == "alert" and n["title"] == "excluded"
+ for n in notifications
+ )
+
+
[email protected]("run_id", ["", "wanted"])
+def test_run_filter_is_rejected_before_starting_an_editor_session(
+ client: TestClient, editor_host: SessionBridge, run_id: str
+) -> None:
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"{socket_url(editor_host)}&run_id={run_id}"
+ ):
+ pytest.fail("Editor run filter was accepted")
+ assert (exc.value.code, exc.value.reason) == (
+ 1008,
+ "Editor sessions do not support run_id filtering",
+ )
+ assert not get_session_manager(client).sessions
+
+
+def test_second_tab_gets_private_startup_and_excluded_messages_do_not_echo(
+ client: TestClient, editor_host: SessionBridge
+) -> None:
+ with client.websocket_connect(socket_url(editor_host)) as first:
+ receive_notification(first, "kernel-ready")
+ with client.websocket_connect(socket_url(editor_host, "s2")) as second:
+ ready = receive_notification(second, "kernel-ready")
+ assert ready["kiosk"] is True
+ assert ready["consumer_capabilities"]["edit"] is False
+ session = get_session_manager(client).get_session(SessionId("s1"))
+ assert session is not None
+ first.portal.call(
+ session.notify,
+ AlertNotification(title="other client", description=""),
+ ConsumerId("s1"),
+ )
+ first.portal.call(
+ session.notify,
+ AlertNotification(title="marker", description=""),
+ None,
+ )
+ while True:
+ event = first.receive_json()
+ if event["event"] != "marimo":
+ continue
+ notification = event["data"]["marimo"]
+ assert notification["op"] != "kernel-ready"
+ if notification["op"] == "alert":
+ assert notification["title"] == "marker"
+ break
+ assert (
+ receive_notification(second, "alert")["title"]
+ == "other client"
+ )
+ assert receive_notification(second, "alert")["title"] == "marker"
+
+
+def test_session_cannot_bind_to_another_notebook(
+ client: TestClient, editor_host: SessionBridge, tmp_path: Path
+) -> None:
+ other = tmp_path / "other.py"
+ other.write_text("import marimo\napp = marimo.App()\n")
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"{socket_url(editor_host)}&file={other}"
+ ):
+ pytest.fail("Mismatched notebook was accepted")
+ assert exc.value.code == 1008
+ assert not get_session_manager(client).sessions
+
+
+def test_startup_failure_is_sent_before_the_close(
+ client: TestClient,
+ editor_host: SessionBridge,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ async def fail(**kwargs: Any) -> None:
+ del kwargs
+ raise KernelStartupError("kernel could not start")
+
+ monkeypatch.setattr(get_session_manager(client), "create_session", fail)
+ with client.websocket_connect(socket_url(editor_host)) as websocket:
+ assert (
+ receive_notification(websocket, "kernel-startup-error")["error"]
+ == "kernel could not start"
+ )
+ with pytest.raises(WebSocketDisconnect) as exc:
+ websocket.receive_json()
+ assert (exc.value.code, exc.value.reason) == (
+ 1011,
+ "MARIMO_KERNEL_STARTUP_ERROR",
+ )
+
+
+def test_disconnect_during_startup_cancels_the_connection(
+ client: TestClient,
+ editor_host: SessionBridge,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ cancelled = asyncio.Event()
+
+ async def wait_for_startup(**kwargs: Any) -> None:
+ kwargs["session_consumer"].notify(
+ serialize_kernel_message(
+ StartupProgressNotification(
+ phase="starting-kernel",
+ logs="Starting",
+ log_mode="replace",
+ )
+ )
+ )
+ try:
+ await asyncio.Event().wait()
+ finally:
+ cancelled.set()
+
+ monkeypatch.setattr(
+ get_session_manager(client), "create_session", wait_for_startup
+ )
+ with client.websocket_connect(socket_url(editor_host)) as websocket:
+ assert (
+ receive_notification(websocket, "startup-progress")["logs"]
+ == "Starting"
+ )
+ assert client.portal is not None
+ client.portal.call(asyncio.wait_for, cancelled.wait(), 5)
+ assert not get_session_manager(client).sessions
+
+
+def test_invalid_event_types_are_rejected_before_starting_a_session(
+ client: TestClient, editor_host: SessionBridge
+) -> None:
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"{socket_url(editor_host)}&types=unknown"
+ ):
+ pytest.fail("Invalid event types were accepted")
+ assert (exc.value.code, exc.value.reason) == (1008, "Invalid event types")
+ assert not get_session_manager(client).sessions
+
+
+def test_editor_resumes_host_events_without_replaying_private_notifications(
+ client: TestClient, editor_host: SessionBridge
+) -> None:
+ url = f"{socket_url(editor_host)}&types=marimo,custom"
+ with client.websocket_connect(url) as socket:
+ cursor = socket_snapshot(socket)[-1]["id"]
+ receive_notification(socket, "kernel-ready")
+ session = get_session_manager(client).get_session(SessionId("s1"))
+ assert session is not None
+ socket.portal.call(
+ session.notify,
+ AlertNotification(title="excluded", description=""),
+ ConsumerId("s1"),
+ )
+ socket.portal.call(
+ session.notify,
+ AlertNotification(title="marker", description=""),
+ None,
+ )
+ assert receive_notification(socket, "alert")["title"] == "marker"
+ assert client.portal is not None
+ (notebook_id,) = editor_host.host.notebooks
+ notebook = client.portal.call(editor_host.host.notebook, notebook_id)
+ client.portal.call(notebook.emit, "test.missed", {"text": "replayed"})
+ with client.websocket_connect(f"{url}&cursor={cursor}") as socket:
+ opening = socket_snapshot(socket)
+ assert [event["event"] for event in opening] == ["custom", "ready"]
+ assert opening[0]["data"]["custom"] == {
+ "type": "test.missed",
+ "data": {"text": "replayed"},
+ }
+ receive_notification(socket, "reconnected")
+ assert receive_notification(socket, "alert")["title"] == "Reconnected"
+
+
[email protected]("cursor", ["bad", "-1", ""])
+def test_invalid_cursor_is_rejected_before_starting_a_session(
+ client: TestClient, editor_host: SessionBridge, cursor: str
+) -> None:
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"{socket_url(editor_host)}&cursor={cursor}"
+ ):
+ pytest.fail("Invalid cursor was accepted")
+ assert (exc.value.code, exc.value.reason) == (1008, "Invalid event cursor")
+ assert not get_session_manager(client).sessions
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index dd438a7399..3bfcc69073 100644
--- a/tests/_server/host/test_host_api.py
+++ b/tests/_server/host/test_host_api.py
@@ -13,15 +13,20 @@ from urllib.parse import parse_qs, urlsplit
import msgspec
import pytest
from starlette.routing import Route
+from starlette.testclient import TestClient
+from starlette.websockets import WebSocketDisconnect
from marimo._core import backend as be, protocol
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.protocol import ProjectMessage
from marimo._core.run_log import RetentionPolicy
-from marimo._server.host import api as api_module
+from marimo._core.stream import Event
+from marimo._messaging.notification import CompletedRunNotification
+from marimo._server.host import HOST_API_PATH, api as api_module
from marimo._server.host.bridge import SessionBridge
from marimo._server.host.context import HostContext
+from marimo._server.host.events import MarimoMessage
from marimo._server.host.index import WorkspaceIndex
from marimo._server.main import create_starlette_app
from marimo._server.models.home import MarimoFile
@@ -29,12 +34,16 @@ from marimo._server.workspace import FixedFilesWorkspace, SingleFileWorkspace
from marimo._session.notebook import AppFileManager
from tests._core.conftest import ScriptedBackend, make_notebook, runtime_id_of
from tests._server.host.drive import (
+ AUTHORITY,
+ LOOPBACK,
PORT,
Response,
finished,
request,
+ socket_snapshot,
until_ready,
wait_for,
+ with_client_address,
)
from tests._server.mocks import (
get_mock_session_manager,
@@ -46,6 +55,8 @@ if TYPE_CHECKING:
from starlette.applications import Starlette
+ from marimo._core.stream import Sink
+
TOKEN = "record-token"
AUTH = {"Authorization": f"Bearer {TOKEN}"}
pytestmark = pytest.mark.usefixtures("enable_host")
@@ -129,7 +140,8 @@ def harness(
bridge.host.retention = getattr(request, "param", RetentionPolicy())
harness = Harness(app, bridge, tmp_path)
- def make(notebook_id: str) -> ScriptedBackend:
+ def make(notebook_id: str, sink: Sink) -> ScriptedBackend:
+ del sink
backend = ScriptedBackend()
harness.backends[notebook_id] = backend
return backend
@@ -199,7 +211,8 @@ async def test_a_wrong_method_on_a_known_route_is_a_405_problem(
def _declared_routes() -> dict[str, set[str]]:
methods: dict[str, set[str]] = {}
for route in api_module.build_app().routes:
- assert isinstance(route, Route)
+ if not isinstance(route, Route):
+ continue
path = route.path.replace("{id}", "nb-x").replace("{run_id}", "run-x")
methods.setdefault(path, set()).update(route.methods or set())
return methods
@@ -384,6 +397,7 @@ async def test_a_failure_inside_a_stream_does_not_restart_the_response(
raise RuntimeError("frame failed")
monkeypatch.setattr(api_module, "_frame", broken)
+ listeners = len(harness.host._stream._listeners)
response, task, _ = request(harness.app, "GET", "/events", headers=AUTH)
# Older Starlette raises the body's error inside an ExceptionGroup.
with pytest.raises(Exception) as caught:
@@ -391,6 +405,39 @@ async def test_a_failure_inside_a_stream_does_not_restart_the_response(
assert "frame failed" in repr(caught.value)
assert response.status == 200
assert response.body == b""
+ assert len(harness.host._stream._listeners) == listeners
+
+
+async def test_sse_heartbeats_do_not_end_the_subscription(
+ harness: Harness, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(api_module, "PING_SECONDS", 0.01)
+ notebook = await harness.host.notebook(harness.notebook_id)
+ response, task, disconnect = request(
+ harness.app,
+ "GET",
+ f"/notebooks/{notebook.id}/events",
+ headers=AUTH,
+ query="types=custom",
+ )
+ try:
+ await wait_for(
+ response,
+ lambda r: (
+ sum(record.get("comment") == "ping" for record in r.records)
+ >= 2
+ ),
+ )
+ notebook.emit("test.after-heartbeat", {"value": 42})
+ await wait_for(response, lambda r: "custom" in r.names())
+ assert [
+ record["data"]["custom"]
+ for record in response.records
+ if record.get("event") == "custom"
+ ] == [{"type": "test.after-heartbeat", "data": {"value": 42}}]
+ finally:
+ disconnect()
+ await asyncio.wait_for(task, 5)
async def test_the_catalog_stream_sends_a_snapshot_then_changes(
@@ -1894,3 +1941,364 @@ async def test_a_file_changed_outside_marimo_needs_a_decision(
)
assert edited.status == 200, edited.body
assert (await save(f"save-{n}", b"{}")).status == 200
+
+
[email protected]("query", ["", "types=marimo"])
+async def test_marimo_notifications_use_their_own_sse_kind(
+ harness: Harness, query: str
+) -> None:
+ notebook = await harness.host.notebook(harness.notebook_id)
+ response, task, disconnect = request(
+ harness.app,
+ "GET",
+ f"/notebooks/{notebook.id}/events",
+ headers=AUTH,
+ query=query,
+ )
+ try:
+ await wait_for(response, until_ready)
+ payload = MarimoMessage(CompletedRunNotification(run_id="r1"))
+ published = notebook.sink.append(
+ Event("marimo", payload, notebook_id=notebook.id)
+ )
+ await wait_for(response, lambda r: "marimo" in r.names())
+ assert [r for r in response.records if r.get("event") == "marimo"] == [
+ {
+ "id": str(published.id),
+ "event": "marimo",
+ "data": {
+ "marimo": {
+ "op": "completed-run",
+ "run_id": "r1",
+ "outcome": "succeeded",
+ "error": None,
+ }
+ },
+ }
+ ]
+ finally:
+ disconnect()
+ await asyncio.wait_for(task, 5)
+
+
+ "query", ["", "?types=marimo", "?types=marimo&run_id=r1"]
+)
+def test_websocket_delivers_live_events(harness: Harness, query: str) -> None:
+ with TestClient(
+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"
+ ) as client:
+ assert client.portal is not None
+ notebook = client.portal.call(
+ harness.host.notebook, harness.notebook_id
+ )
+ client.portal.call(analyzed, notebook)
+ payload = MarimoMessage(CompletedRunNotification(run_id="r1"))
+ event = Event("marimo", payload, notebook_id=notebook.id, run_id="r1")
+ client.portal.call(notebook.sink.append, event)
+ path = f"{HOST_API_PATH}/notebooks/{notebook.id}/events/ws{query}"
+ with client.websocket_connect(
+ f"ws://{AUTHORITY}{path}", headers=dict(AUTH)
+ ) as websocket:
+ initial = socket_snapshot(websocket)
+ assert all("id" not in event for event in initial[:-1])
+ client.portal.call(
+ notebook.sink.append,
+ Event("marimo", payload, notebook_id="nb_other", run_id="r1"),
+ )
+ if "run_id" in query:
+ client.portal.call(
+ notebook.sink.append,
+ Event(
+ "marimo", payload, notebook_id=notebook.id, run_id="r2"
+ ),
+ )
+ first = client.portal.call(notebook.sink.append, event)
+ client.portal.call(
+ notebook.emit, "test.message", {"text": "hello"}
+ )
+ second = client.portal.call(notebook.sink.append, event)
+ expected = {
+ "event": "marimo",
+ "data": {
+ "marimo": {
+ "op": "completed-run",
+ "run_id": "r1",
+ "outcome": "succeeded",
+ "error": None,
+ }
+ },
+ }
+ assert websocket.receive_json() == {
+ "id": str(first.id),
+ **expected,
+ }
+ if not query:
+ custom = websocket.receive_json()
+ assert custom["event"] == "custom"
+ assert custom["data"]["custom"] == {
+ "type": "test.message",
+ "data": {"text": "hello"},
+ }
+ assert websocket.receive_json() == {
+ "id": str(second.id),
+ **expected,
+ }
+
+
[email protected]("send_message", [False, True])
+def test_websocket_disconnect_detaches_the_client(
+ harness: Harness,
+ send_message: bool,
+) -> None:
+ with TestClient(
+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"
+ ) as client:
+ assert client.portal is not None
+ notebook = client.portal.call(
+ harness.host.notebook, harness.notebook_id
+ )
+ client.portal.call(analyzed, notebook)
+ removed = asyncio.Event()
+ events: list[Event] = []
+
+ def observe(event: Event) -> None:
+ if event.notebook_id == notebook.id and event.kind == "attachment":
+ events.append(event)
+ if event.name == "attachment.removed":
+ removed.set()
+
+ unsubscribe = client.portal.call(harness.host.subscribe, observe)
+ try:
+ path = f"{HOST_API_PATH}/notebooks/{notebook.id}/events/ws"
+ with client.websocket_connect(
+ f"ws://{AUTHORITY}{path}", headers=dict(AUTH)
+ ) as websocket:
+ socket_snapshot(websocket)
+ if send_message:
+ websocket.send_json({"command": "run"})
+ with pytest.raises(WebSocketDisconnect) as exc:
+ websocket.receive_json()
+ assert exc.value.code == 1003
+ else:
+ websocket.close()
+ client.portal.call(asyncio.wait_for, removed.wait(), 5)
+ assert [event.name for event in events] == [
+ "attachment",
+ "attachment.removed",
+ ]
+ assert isinstance(events[0].data, protocol.AttachmentMessage)
+ assert isinstance(events[1].data, protocol.RemovedMessage)
+ assert events[1].data.id == events[0].data.attachment.id
+ assert harness.backend().calls == []
+ finally:
+ client.portal.call(unsubscribe)
+
+
+ ("headers", "address", "authority"),
+ [
+ ({}, LOOPBACK, AUTHORITY),
+ ({"Authorization": "Bearer wrong"}, LOOPBACK, AUTHORITY),
+ (AUTH, ("192.0.2.1", 50000), AUTHORITY),
+ (AUTH, LOOPBACK, "example.com:1234"),
+ ],
+)
+def test_websocket_rejects_invalid_authentication(
+ harness: Harness,
+ headers: dict[str, str],
+ address: tuple[str, int],
+ authority: str,
+) -> None:
+ client = TestClient(
+ with_client_address(harness.app, address),
+ base_url=f"http://{authority}",
+ )
+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}/events/ws"
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"ws://{authority}{path}", headers=dict(headers)
+ ):
+ pytest.fail("Unauthenticated socket was accepted")
+ assert exc.value.code == 1008
+ assert harness.backends == {}
+
+
[email protected]("base_url", ["", "/app"])
[email protected]("credential", ["cookie", "query"])
+ ("authority", "address", "rejected_status"),
+ [
+ (AUTHORITY, LOOPBACK, 401),
+ ("notebooks.example:1234", ("192.0.2.1", 50000), 403),
+ ],
+)
+def test_editor_authentication_is_limited_to_the_event_socket(
+ harness: Harness,
+ base_url: str,
+ credential: str,
+ authority: str,
+ address: tuple[str, int],
+ rejected_status: int,
+) -> None:
+ app = create_starlette_app(base_url=base_url, enable_auth=True)
+ manager = harness.app.state.session_manager
+ get_starlette_server_state_init(
+ session_manager=manager, base_url=base_url
+ ).apply(app.state)
+ app.state.host_context = harness.app.state.host_context
+ with TestClient(
+ with_client_address(app, address), base_url=f"http://{authority}"
+ ) as client:
+ query = ""
+ if credential == "cookie":
+ response = client.post(
+ f"{base_url}/auth/login",
+ data={"password": str(manager.auth_token)},
+ follow_redirects=False,
+ )
+ assert response.status_code == 302
+ assert client.cookies
+ else:
+ query = f"?access_token={manager.auth_token}"
+ assert client.portal is not None
+ notebook = client.portal.call(
+ harness.host.notebook, harness.notebook_id
+ )
+ path = f"{base_url}{HOST_API_PATH}/notebooks/{notebook.id}"
+ separator = "&" if query else "?"
+ with client.websocket_connect(
+ f"ws://{authority}{path}/events/ws{query}{separator}types=marimo"
+ ) as websocket:
+ socket_snapshot(websocket)
+ payload = MarimoMessage(CompletedRunNotification(run_id="r1"))
+ published = client.portal.call(
+ notebook.sink.append,
+ Event("marimo", payload, notebook_id=notebook.id),
+ )
+ assert websocket.receive_json() == {
+ "id": str(published.id),
+ "event": "marimo",
+ "data": {
+ "marimo": {
+ "op": "completed-run",
+ "run_id": "r1",
+ "outcome": "succeeded",
+ "error": None,
+ }
+ },
+ }
+ assert harness.backend().calls == []
+ for endpoint in (path, f"{path}/events"):
+ assert (
+ client.get(f"{endpoint}{query}").status_code == rejected_status
+ )
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"ws://{authority}{base_url}{HOST_API_PATH}/events/ws{query}"
+ ):
+ pytest.fail("Editor credentials authorized another socket")
+ assert exc.value.code == 1008
+
+
[email protected]("token", ["wrong", TOKEN])
+def test_event_socket_query_requires_the_editor_token(
+ harness: Harness, token: str
+) -> None:
+ client = TestClient(with_client_address(harness.app))
+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}/events/ws"
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"ws://{AUTHORITY}{path}?access_token={token}"
+ ):
+ pytest.fail("Invalid editor token was accepted")
+ assert exc.value.code == 1008
+ assert harness.backends == {}
+
+
+def test_event_socket_respects_disabled_editor_authentication(
+ harness: Harness,
+) -> None:
+ app = create_starlette_app(base_url="", enable_auth=False)
+ get_starlette_server_state_init(
+ session_manager=harness.app.state.session_manager
+ ).apply(app.state)
+ app.state.enable_auth = False
+ app.state.host_context = harness.app.state.host_context
+ with TestClient(
+ with_client_address(app), base_url=f"http://{AUTHORITY}"
+ ) as client:
+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}"
+ with client.websocket_connect(f"ws://{AUTHORITY}{path}/events/ws"):
+ pass
+ assert client.get(path).status_code == 401
+ assert harness.backend().calls == []
+
+
+ ("query", "headers", "reason"),
+ [
+ ("?types=bogus", AUTH, "Invalid event types"),
+ ("?run_id=", AUTH, "run_id must not be empty"),
+ ("?cursor=bad", AUTH, "Invalid event cursor"),
+ ("?cursor=", AUTH, "Invalid event cursor"),
+ ("", {**AUTH, "Last-Event-ID": "-1"}, "Invalid event cursor"),
+ ("?cursor=1", {**AUTH, "Last-Event-ID": "2"}, "Invalid event cursor"),
+ (
+ "",
+ {**AUTH, "Marimo-Attachment-Identity": ""},
+ "Marimo-Attachment-Identity is invalid",
+ ),
+ ],
+)
+def test_websocket_rejects_invalid_subscriptions(
+ harness: Harness, query: str, headers: dict[str, str], reason: str
+) -> None:
+ client = TestClient(
+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"
+ )
+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}/events/ws{query}"
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"ws://{AUTHORITY}{path}", headers=dict(headers)
+ ):
+ pytest.fail("Invalid subscription was accepted")
+ assert (exc.value.code, exc.value.reason) == (1008, reason)
+
+
[email protected]("path", ["/notebooks/missing/events/ws", "/missing"])
+def test_websocket_rejects_unknown_notebooks_and_routes(
+ harness: Harness, path: str
+) -> None:
+ client = TestClient(
+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"
+ )
+ with pytest.raises(WebSocketDisconnect) as exc:
+ with client.websocket_connect(
+ f"ws://{AUTHORITY}{HOST_API_PATH}{path}", headers=dict(AUTH)
+ ):
+ pytest.fail("Unknown resource was accepted")
+ assert exc.value.code == 1008
+
+
+def test_websocket_snapshot_failure_releases_subscription(
+ harness: Harness, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ def broken(*_args: Any, **_kwargs: Any) -> list[Event]:
+ raise RuntimeError("snapshot failed")
+
+ with TestClient(with_client_address(harness.app)) as client:
+ assert client.portal is not None
+ notebook = client.portal.call(
+ harness.host.notebook, harness.notebook_id
+ )
+ client.portal.call(analyzed, notebook)
+ listeners = len(harness.host._stream._listeners)
+ monkeypatch.setattr(harness.host, "events", broken)
+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook.id}/events/ws"
+ with pytest.raises(WebSocketDisconnect) as caught:
+ with client.websocket_connect(url, headers=dict(AUTH)):
+ pytest.fail("Snapshot failure accepted a connection")
+ assert caught.value.code == 1008
+ assert notebook._attachments == {}
+ assert len(harness.host._stream._listeners) == listeners
diff --git a/tests/_server/host/test_host_backend.py b/tests/_server/host/test_host_backend.py
index 42ff53a81b..7df12cc98f 100644
--- a/tests/_server/host/test_host_backend.py
+++ b/tests/_server/host/test_host_backend.py
@@ -8,6 +8,7 @@ import asyncio
import pytest
from marimo._core import backend as be, protocol
+from marimo._core.stream import Stream
from marimo._messaging.notification import (
CellNotification,
CompletedRunNotification,
@@ -34,6 +35,7 @@ def backend(manager: FakeManager, observed: Observed) -> SessionBackend:
lambda: "/ws/forecasts.py",
manager, # type: ignore[arg-type]
observed,
+ Stream(),
)
@@ -88,6 +90,7 @@ async def test_a_notebook_without_a_file_cannot_start(
lambda: None,
manager, # type: ignore[arg-type]
observed,
+ Stream(),
).start(RT1)
await observed.wait_for(be.Exited)
assert observed.messages == [
diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.py
index ab8868743e..d3936332de 100644
--- a/tests/_server/host/test_host_bridge.py
+++ b/tests/_server/host/test_host_bridge.py
@@ -16,9 +16,11 @@ from marimo._messaging.notification import (
CompletedRunNotification,
ExecutionNotification,
StartupProgressNotification,
+ VariablesNotification,
)
from marimo._runtime.scratch import SCRATCH_CELL_ID
from marimo._server.host.bridge import SessionBridge
+from marimo._server.host.events import MarimoMessage
from marimo._server.models.home import MarimoFile
from marimo._server.workspace import FixedFilesWorkspace
from tests._core.conftest import names
@@ -450,7 +452,6 @@ async def test_host_edits_reach_the_session_as_one_transaction(
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
notebook = await bridge.host.notebook(record.id)
- document = notebook.document
events: list[Event] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
@@ -472,8 +473,14 @@ async def test_host_edits_reach_the_session_as_one_transaction(
(notification,) = session.notifications
assert isinstance(notification, NotebookDocumentTransactionNotification)
assert notification.transaction.source == "host"
- # The backend saw its own edit come back and mirrored nothing new.
- assert names(events) == ["cell", "document"]
+ # The session echoes the edit without publishing the document twice.
+ assert names([e for e in events if e.name != "marimo"]) == [
+ "cell",
+ "document",
+ ]
+ assert [e.data for e in events if e.name == "marimo"] == [
+ MarimoMessage(notification)
+ ]
assert notebook.document.etag == response.document.etag
assert "y = x" not in (tmp_path / "a.py").read_text()
bridge.close()
@@ -983,3 +990,48 @@ async def test_reloading_refuses_to_drop_an_edit_made_while_reading(
assert conflict.value.document == edited.document
assert notebook.document.cell(cell.id).code == "x = 3" # type: ignore[union-attr]
bridge.close()
+
+
+async def test_session_notifications_join_the_notebook_stream_once(
+ manager: FakeManager, tmp_path: Path
+) -> None:
+ prepare(manager, tmp_path, "a.py", "b.py")
+ session = FakeSession(str(tmp_path / "a.py"))
+ manager.sessions["browser"] = session
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+ await bridge.open()
+ a = bridge.index.notebook_for(str(tmp_path / "a.py"))
+ b = bridge.index.notebook_for(str(tmp_path / "b.py"))
+ assert a is not None
+ assert b is not None
+
+ first: list[Event] = []
+ second: list[Event] = []
+ catalog: list[Event] = []
+ other: list[Event] = []
+ filtered: list[Event] = []
+ bridge.host.subscribe(first.append, notebook_id=a.id)
+ bridge.host.subscribe(second.append, notebook_id=a.id)
+ bridge.host.subscribe(catalog.append)
+ bridge.host.subscribe(other.append, notebook_id=b.id)
+ bridge.host.subscribe(filtered.append, notebook_id=a.id, types={"marimo"})
+
+ variables = VariablesNotification(variables=[])
+ planned = ExecutionNotification(
+ run_id="run-1",
+ execution_id="execution-1",
+ cell_id="cell-1",
+ phase="planned",
+ code="x = 1",
+ )
+ session.broadcast(variables)
+ session.broadcast(planned)
+
+ assert first == second
+ assert catalog == other == []
+ assert filtered == [e for e in first if e.name == "marimo"]
+ assert [(e.run_id, e.data) for e in filtered] == [
+ (None, MarimoMessage(variables)),
+ (protocol.RunId("run-1"), MarimoMessage(planned)),
+ ]
+ bridge.close()
diff --git a/tests/_server/host/test_host_websocket.py b/tests/_server/host/test_host_websocket.py
new file mode 100644
index 0000000000..1d04e2fd57
--- /dev/null
+++ b/tests/_server/host/test_host_websocket.py
@@ -0,0 +1,322 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Retained session state on the host WebSocket."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import msgspec
+import pytest
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.testclient import TestClient
+
+from marimo._messaging.cell_output import CellChannel, CellOutput
+from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
+)
+from marimo._server.host import HOST_API_PATH
+from marimo._server.host.bridge import SessionBridge
+from marimo._server.host.context import HostContext
+from marimo._server.host.middleware import HostApiMiddleware
+from marimo._server.models.home import MarimoFile
+from marimo._server.workspace import FixedFilesWorkspace
+from marimo._session.notebook import AppFileManager
+from marimo._session.state.session_view import SessionView
+from tests._server.host.conftest import FakeManager, FakeSession
+from tests._server.host.drive import (
+ AUTHORITY,
+ PORT,
+ socket_snapshot,
+ with_client_address,
+)
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from starlette.types import Message, Receive, Scope, Send
+
+AUTH = {"Authorization": "Bearer snapshot-test"}
+
+
+def session_host(
+ manager: FakeManager, tmp_path: Path
+) -> tuple[Starlette, SessionBridge, FakeSession]:
+ path = tmp_path / "notebook.py"
+ path.write_text(
+ "import marimo\napp = marimo.App()\n"
+ "@app.cell\ndef _():\n x = 1\n return (x,)\n"
+ )
+ manager.workspace = FixedFilesWorkspace(
+ [MarimoFile(name=path.name, path=str(path))], directory=str(tmp_path)
+ )
+ session = FakeSession(str(path))
+ session.document = AppFileManager(str(path)).app.cell_manager.document
+ session.session_view = SessionView()
+ session.session_view.add_notification(
+ CellNotification(
+ cell_id=session.document.cell_ids[0],
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/plain",
+ data="retained output",
+ timestamp=1.0,
+ ),
+ status="idle",
+ run_id="r1",
+ timestamp=1.0,
+ )
+ )
+ manager.sessions["existing"] = session
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+ app = Starlette(middleware=[Middleware(HostApiMiddleware)])
+ app.state.host_context = HostContext(
+ bridge=bridge, token="snapshot-test", port=PORT
+ )
+ return app, bridge, session
+
+
+def test_snapshot_is_private_and_precedes_updates_during_accept(
+ session_host: tuple[Starlette, SessionBridge, FakeSession],
+) -> None:
+ app, bridge, session = session_host
+ connections = 0
+
+ async def app_with_update(
+ scope: Scope, receive: Receive, send: Send
+ ) -> None:
+ async def send_with_update(message: Message) -> None:
+ nonlocal connections
+ if message["type"] == "websocket.accept":
+ connections += 1
+ if connections == 2:
+ session.notify(CompletedRunNotification(run_id="live"))
+ await send(message)
+
+ await app(scope, receive, send_with_update)
+
+ with TestClient(with_client_address(app_with_update)) as client:
+ assert client.portal is not None
+ client.portal.call(bridge.open)
+ try:
+ (notebook_id,) = bridge.host.notebooks
+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?types=marimo"
+ with client.websocket_connect(url, headers=dict(AUTH)) as first:
+ opening = socket_snapshot(first)
+ initial = opening[:-1]
+ assert initial == [
+ {
+ "event": "marimo",
+ "data": {
+ "marimo": {
+ "op": "environment-state",
+ "source": source,
+ "state": {
+ "restart_required": False,
+ "operations": [],
+ },
+ }
+ },
+ }
+ for source in ("kernel", "server")
+ ] + [
+ {
+ "event": "marimo",
+ "data": {
+ "marimo": {
+ "op": "cell-op",
+ "cell_id": session.document.cell_ids[0],
+ "output": {
+ "channel": "output",
+ "mimetype": "text/plain",
+ "data": "retained output",
+ "timestamp": 1.0,
+ },
+ "console": None,
+ "status": "idle",
+ "stale_inputs": None,
+ "run_id": "r1",
+ "execution_id": None,
+ "timestamp": 1.0,
+ }
+ },
+ }
+ ]
+ with client.websocket_connect(
+ url, headers=dict(AUTH)
+ ) as second:
+ assert socket_snapshot(second)[:-1] == initial
+ live = second.receive_json()
+ assert first.receive_json() == live
+ assert live == {
+ "id": live["id"],
+ "event": "marimo",
+ "data": {
+ "marimo": {
+ "op": "completed-run",
+ "run_id": "live",
+ "outcome": "succeeded",
+ "error": None,
+ }
+ },
+ }
+ finally:
+ client.portal.call(bridge.close)
+
+
+ ("query", "has_snapshot"),
+ [
+ ("types=marimo&run_id=r1", True),
+ ("types=marimo&run_id=other", False),
+ ("types=custom", False),
+ ],
+)
+def test_snapshot_obeys_type_and_run_filters(
+ session_host: tuple[Starlette, SessionBridge, FakeSession],
+ query: str,
+ has_snapshot: bool,
+) -> None:
+ app, bridge, session = session_host
+ with TestClient(with_client_address(app)) as client:
+ assert client.portal is not None
+ client.portal.call(bridge.open)
+ try:
+ (notebook_id,) = bridge.host.notebooks
+ notebook = client.portal.call(bridge.host.notebook, notebook_id)
+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?{query}"
+ with client.websocket_connect(
+ url, headers=dict(AUTH)
+ ) as websocket:
+ opening = socket_snapshot(websocket)
+ assert len(opening) == (2 if has_snapshot else 1)
+ if has_snapshot:
+ snapshot = opening[0]
+ assert "id" not in snapshot
+ assert snapshot["event"] == "marimo"
+ assert snapshot["data"]["marimo"]["run_id"] == "r1"
+ assert (
+ snapshot["data"]["marimo"]["output"]["data"]
+ == "retained output"
+ )
+ if query == "types=custom":
+ client.portal.call(notebook.emit, "test.marker", {})
+ assert websocket.receive_json()["event"] == "custom"
+ else:
+ run_id = "r1" if has_snapshot else "other"
+ client.portal.call(
+ session.notify, CompletedRunNotification(run_id=run_id)
+ )
+ assert websocket.receive_json()["data"]["marimo"] == {
+ "op": "completed-run",
+ "run_id": run_id,
+ "outcome": "succeeded",
+ "error": None,
+ }
+ finally:
+ client.portal.call(bridge.close)
+
+
+def test_opening_delivers_protocol_and_session_state_before_ready(
+ session_host: tuple[Starlette, SessionBridge, FakeSession],
+) -> None:
+ app, bridge, session = session_host
+ with TestClient(with_client_address(app)) as client:
+ assert client.portal is not None
+ client.portal.call(bridge.open)
+ try:
+ (notebook_id,) = bridge.host.notebooks
+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws"
+ with client.websocket_connect(url, headers=dict(AUTH)) as socket:
+ opening = socket_snapshot(socket)
+ names = [event["event"] for event in opening]
+ assert names[0] == "notebook"
+ assert names.index("cell") < names.index("document")
+ assert names.index("document") < names.index("marimo")
+ assert "attachment" in names
+ assert all("id" not in event for event in opening[:-1])
+ cell = next(
+ e["data"]["cell"] for e in opening if e["event"] == "cell"
+ )
+ document = next(
+ e["data"]["document"]
+ for e in opening
+ if e["event"] == "document"
+ )
+ assert cell["id"] == session.document.cell_ids[0]
+ assert document["order"] == [cell["id"]]
+ finally:
+ client.portal.call(bridge.close)
+
+
[email protected]("use_header", [False, True])
+def test_reconnect_replays_original_events_then_continues_live(
+ session_host: tuple[Starlette, SessionBridge, FakeSession],
+ use_header: bool,
+) -> None:
+ app, bridge, session = session_host
+ with TestClient(with_client_address(app)) as client:
+ assert client.portal is not None
+ client.portal.call(bridge.open)
+ try:
+ (notebook_id,) = bridge.host.notebooks
+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?types=marimo"
+ with client.websocket_connect(url, headers=dict(AUTH)) as socket:
+ cursor = socket_snapshot(socket)[-1]["id"]
+ client.portal.call(
+ session.notify, CompletedRunNotification(run_id="missed")
+ )
+ missed = socket.receive_json()
+ headers = dict(AUTH)
+ if use_header:
+ headers["Last-Event-ID"] = cursor
+ else:
+ url += f"&cursor={cursor}"
+ with client.websocket_connect(url, headers=headers) as socket:
+ replay = socket_snapshot(socket)
+ assert replay[:-1] == [missed]
+ client.portal.call(
+ session.notify, CompletedRunNotification(run_id="live")
+ )
+ live = socket.receive_json()
+ assert live["data"]["marimo"]["run_id"] == "live"
+ assert int(live["id"]) > int(replay[-1]["id"])
+ finally:
+ client.portal.call(bridge.close)
+
+
+def test_expired_cursor_resets_to_current_state(
+ session_host: tuple[Starlette, SessionBridge, FakeSession],
+) -> None:
+ app, bridge, _ = session_host
+ with TestClient(with_client_address(app)) as client:
+ assert client.portal is not None
+ client.portal.call(bridge.open)
+ try:
+ (notebook_id,) = bridge.host.notebooks
+ notebook = client.portal.call(bridge.host.notebook, notebook_id)
+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?types=cell,document,marimo,custom"
+ with client.websocket_connect(url, headers=dict(AUTH)) as socket:
+ initial = socket_snapshot(socket)
+ cursor = initial[-1]["id"]
+ # Expire the default 1000-event replay history.
+ for index in range(1001):
+ client.portal.call(
+ notebook.emit, "test.expire", {"index": index}
+ )
+ with client.websocket_connect(
+ f"{url}&cursor={cursor}", headers=dict(AUTH)
+ ) as socket:
+ reset = socket_snapshot(socket)
+ assert reset[0] == {"event": "reset", "data": {}}
+ assert reset[1:-1] == initial[:-1]
+ assert int(reset[-1]["id"]) > int(cursor)
+ event = client.portal.call(notebook.emit, "test.live", {})
+ live = socket.receive_json()
+ assert live["event"] == "custom"
+ assert live["data"]["custom"] == msgspec.to_builtins(event)
+ assert int(live["id"]) > int(reset[-1]["id"])
+ finally:
+ client.portal.call(bridge.close)
diff --git a/tests/_session/state/test_session_external_storage.py b/tests/_session/state/test_session_external_storage.py
index b2aed2bcc3..08588a8d4c 100644
--- a/tests/_session/state/test_session_external_storage.py
+++ b/tests/_session/state/test_session_external_storage.py
@@ -130,7 +130,8 @@ def test_add_storage_namespaces(session_view: SessionView) -> None:
# Check namespaces appear in notifications
assert (
- session_view.external_storage_namespaces in session_view.notifications
+ session_view.external_storage_namespaces
+ in session_view.snapshot_notifications()
)
@@ -212,7 +213,7 @@ def test_storage_namespaces_empty_not_in_notifications(
assert session_view.external_storage_namespaces.namespaces == []
storage_ops = [
op
- for op in session_view.notifications
+ for op in session_view.snapshot_notifications()
if isinstance(op, StorageNamespacesNotification)
]
assert len(storage_ops) == 0
@@ -238,7 +239,7 @@ def test_storage_namespaces_in_notifications(
)
storage_ops = [
op
- for op in session_view.notifications
+ for op in session_view.snapshot_notifications()
if isinstance(op, StorageNamespacesNotification)
]
assert storage_ops == snapshot(
diff --git a/tests/_session/state/test_session_view.py b/tests/_session/state/test_session_view.py
index d2e9b2b39c..33927364b8 100644
--- a/tests/_session/state/test_session_view.py
+++ b/tests/_session/state/test_session_view.py
@@ -27,6 +27,7 @@ from marimo._messaging.notification import (
EnvironmentOperationNotification,
EnvironmentOperationStatus,
EnvironmentState,
+ EnvironmentStateNotification,
EsmSpec,
ModelClose,
ModelCustom,
@@ -44,6 +45,7 @@ from marimo._messaging.notification import (
SQLTableListPreviewNotification,
SQLTablePreviewNotification,
StartupLogsNotification,
+ StartupProgressNotification,
VariableDeclarationNotification,
VariablesNotification,
VariableValue,
@@ -1011,7 +1013,9 @@ def test_add_data_source_connections(session_view: SessionView) -> None:
assert INTERNAL_DUCKDB_ENGINE in names
# Check connectors in operations
- assert session_view.data_connectors in session_view.notifications
+ assert (
+ session_view.data_connectors in session_view.snapshot_notifications()
+ )
# Filter out connections from variables
session_view.add_raw_notification(
@@ -1830,7 +1834,7 @@ def test_session_view_startup_logs_operations_exclude_done(
session_view.add_notification(start_log)
# Should include in operations while in progress
- operations = session_view.notifications
+ operations = session_view.snapshot_notifications()
startup_ops = [
op for op in operations if isinstance(op, StartupLogsNotification)
]
@@ -1842,7 +1846,7 @@ def test_session_view_startup_logs_operations_exclude_done(
session_view.add_notification(done_log)
# Should not include done startup logs in operations
- operations = session_view.notifications
+ operations = session_view.snapshot_notifications()
startup_ops = [
op for op in operations if isinstance(op, StartupLogsNotification)
]
@@ -2428,3 +2432,60 @@ def test_preparation_remains_available_after_package_changes(
logs={},
),
]
+
+
[email protected]("include_notebook", [False, True])
+def test_snapshot_notifications_preserve_replay_order(
+ session_view: SessionView, include_notebook: bool
+) -> None:
+ progress = StartupProgressNotification(
+ phase="starting-kernel", logs="Ready\n", log_mode="replace"
+ )
+ model = ModelLifecycleNotification(
+ model_id=WidgetModelId("model"),
+ message=ModelOpen(state={"value": 1}, buffer_paths=[], buffers=[]),
+ )
+ cell = CellNotification(
+ cell_id=cell_id,
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/plain",
+ data="old output",
+ ),
+ status="idle",
+ )
+ # The output can arrive before its widget model exists.
+ for notification in (cell, model, progress):
+ session_view.add_notification(notification)
+
+ notifications = session_view.snapshot_notifications(
+ include_notebook=include_notebook
+ )
+ assert notifications == [
+ EnvironmentStateNotification(
+ source="kernel",
+ state=EnvironmentState(restart_required=False, operations=[]),
+ ),
+ EnvironmentStateNotification(
+ source="server",
+ state=EnvironmentState(restart_required=False, operations=[]),
+ ),
+ progress,
+ *([model, cell] if include_notebook else []),
+ ]
+ captured = msgspec.json.encode(notifications)
+ session_view.update_cell_outputs({cell_id: ("text/plain", "new output")})
+ session_view.add_notification(
+ StartupProgressNotification(
+ phase="starting-kernel", logs="More logs\n", log_mode="append"
+ )
+ )
+ assert msgspec.json.encode(notifications) == captured
+ assert (
+ msgspec.json.encode(
+ session_view.snapshot_notifications(
+ include_notebook=include_notebook
+ )
+ )
+ != captured
+ )
diff --git a/tests/conftest.py b/tests/conftest.py
index 459e5bf560..6deb957e14 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -471,7 +471,7 @@ def session_view() -> Generator[SessionView, None, None]:
yield sv
# Test all operations can be serialized/deserialized
- for operation in sv.notifications:
+ for operation in sv.snapshot_notifications():
assert_serialize_roundtrip(operation)