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.

refactor: split up ws monolith (#7587)

Myles Scolnickd81218179e1a
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index ae7e21fcb9..8132b23780 100644
--- a/marimo/_server/api/endpoints/execution.py
+++ b/marimo/_server/api/endpoints/execution.py
@@ -19,7 +19,10 @@ from marimo._runtime.requests import (
SetUIElementValueRequest,
)
from marimo._server.api.deps import AppState
-from marimo._server.api.endpoints.ws import DOC_MANAGER, FILE_QUERY_PARAM_KEY
+from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ FILE_QUERY_PARAM_KEY,
+)
+from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGER
from marimo._server.api.utils import dispatch_control_request, parse_request
from marimo._server.file_router import MarimoFileKey
from marimo._server.models.models import (
diff --git a/marimo/_server/api/endpoints/ws.py b/marimo/_server/api/endpoints/ws.py
deleted file mode 100644
index 42c1c9938d..0000000000
--- a/marimo/_server/api/endpoints/ws.py
+++ /dev/null
@@ -1,782 +0,0 @@
-# Copyright 2024 Marimo. All rights reserved.
-from __future__ import annotations
-
-import asyncio
-import sys
-from typing import TYPE_CHECKING, Any, Callable, Optional
-
-from starlette.websockets import WebSocket, WebSocketDisconnect, WebSocketState
-
-from marimo import _loggers
-from marimo._ast.cell import CellConfig
-from marimo._cli.upgrade import check_for_updates
-from marimo._config.cli_state import MarimoCLIState
-from marimo._config.settings import GLOBAL_SETTINGS
-from marimo._dependencies.dependencies import DependencyManager
-from marimo._messaging.ops import (
- Alert,
- Banner,
- CompletionResult,
- FocusCell,
- KernelCapabilities,
- KernelReady,
- MessageOperation,
- Reconnected,
-)
-from marimo._messaging.serde import (
- deserialize_kernel_operation_name,
- serialize_kernel_message,
-)
-from marimo._messaging.types import KernelMessage, NoopStream
-from marimo._plugins.core.web_component import JSONType
-from marimo._runtime.params import QueryParams
-from marimo._server.api.auth import validate_auth
-from marimo._server.api.deps import AppState
-from marimo._server.codes import WebSocketCodes
-from marimo._server.consumer import SessionConsumer
-from marimo._server.file_router import MarimoFileKey
-from marimo._server.model import (
- ConnectionState,
- SessionMode,
-)
-from marimo._server.router import APIRouter
-from marimo._server.rtc.doc import LoroDocManager
-from marimo._server.sessions import Session, SessionManager
-from marimo._server.sessions.events import SessionEventBus
-from marimo._types.ids import CellId_t, ConsumerId, SessionId
-
-if TYPE_CHECKING:
- from loro import DiffEvent
-
-LOGGER = _loggers.marimo_logger()
-
-
-LORO_ALLOWED = sys.version_info >= (3, 11)
-
-
-router = APIRouter()
-
-SESSION_QUERY_PARAM_KEY = "session_id"
-FILE_QUERY_PARAM_KEY = "file"
-KIOSK_QUERY_PARAM_KEY = "kiosk"
-
-
-DOC_MANAGER = LoroDocManager()
-
-
-async def websocket_endpoint(
- websocket: WebSocket,
-) -> None:
- """
- responses:
- 200:
- description: Websocket endpoint
- """
- app_state = AppState(websocket)
-
- # Validate authentication before proceeding
- if app_state.enable_auth and not validate_auth(websocket):
- await websocket.close(
- WebSocketCodes.UNAUTHORIZED, "MARIMO_UNAUTHORIZED"
- )
- return
-
- raw_session_id = app_state.query_params(SESSION_QUERY_PARAM_KEY)
- if raw_session_id is None:
- await websocket.close(
- WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_SESSION_ID"
- )
- return
-
- session_id = SessionId(raw_session_id)
-
- file_key: Optional[MarimoFileKey] = (
- app_state.query_params(FILE_QUERY_PARAM_KEY)
- or app_state.session_manager.file_router.get_unique_file_key()
- )
-
- if file_key is None:
- await websocket.close(
- WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_FILE_KEY"
- )
- return
-
- kiosk = app_state.query_params(KIOSK_QUERY_PARAM_KEY) == "true"
-
- config = app_state.config_manager_at_file(file_key).get_config()
-
- rtc_enabled: bool = config.get("experimental", {}).get("rtc_v2", False)
- auto_instantiate = config["runtime"]["auto_instantiate"]
-
- await WebsocketHandler(
- websocket=websocket,
- manager=app_state.session_manager,
- rtc_enabled=rtc_enabled,
- session_id=session_id,
- mode=app_state.mode,
- file_key=file_key,
- kiosk=kiosk,
- auto_instantiate=auto_instantiate,
- ).start()
-
-
-# WebSocket endpoint for LoroDoc synchronization
[email protected]("/ws_sync")
-async def ws_sync(
- websocket: WebSocket,
-) -> None:
- """
- Websocket endpoint for LoroDoc synchronization
- """
- app_state = AppState(websocket)
-
- # Validate authentication before proceeding
- if app_state.enable_auth and not validate_auth(websocket):
- await websocket.close(
- WebSocketCodes.UNAUTHORIZED, "MARIMO_UNAUTHORIZED"
- )
- return
-
- if not (LORO_ALLOWED and DependencyManager.loro.has()):
- if not LORO_ALLOWED:
- LOGGER.warning("RTC: Python version is not supported")
- else:
- LOGGER.warning("RTC: Loro is not installed, closing websocket")
- await websocket.close(
- WebSocketCodes.NORMAL_CLOSE, "MARIMO_LORO_NOT_INSTALLED"
- )
- return
-
- from loro import ExportMode
-
- app_state = AppState(websocket)
- file_key: Optional[MarimoFileKey] = (
- app_state.query_params(FILE_QUERY_PARAM_KEY)
- or app_state.session_manager.file_router.get_unique_file_key()
- )
-
- if file_key is None:
- LOGGER.warning("RTC: Closing websocket - no file key")
- await websocket.close(
- WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_FILE_KEY"
- )
- return
-
- manager = app_state.session_manager
- session = manager.get_session_by_file_key(file_key)
- if session is None:
- LOGGER.warning(
- f"RTC: Closing websocket - no session found for file key {file_key}"
- )
- await websocket.close(WebSocketCodes.FORBIDDEN, "MARIMO_NOT_ALLOWED")
- return
-
- await websocket.accept()
-
- # Get or create the LoroDoc and add the client to it
- LOGGER.debug("RTC: getting document")
- update_queue = asyncio.Queue[bytes]()
- doc = await DOC_MANAGER.get_or_create_doc(file_key)
- DOC_MANAGER.add_client_to_doc(file_key, update_queue)
-
- # Send initial sync
- # Use shallow snapshot for fewer bytes
- LOGGER.debug("RTC: sending initial sync")
- init_sync_msg = doc.export(
- ExportMode.ShallowSnapshot(frontiers=doc.state_frontiers)
- )
- await websocket.send_bytes(init_sync_msg)
- LOGGER.debug("RTC: initial sync sent")
-
- def handle_doc_update(event: DiffEvent) -> None:
- LOGGER.debug("RTC: doc updated", event)
-
- # Create an async task to send updates to the client
- async def send_updates() -> None:
- try:
- while True:
- update = await update_queue.get()
- await websocket.send_bytes(update)
- except Exception as e:
- LOGGER.warning(
- f"RTC: Could not send loro update to client for file {file_key}: {str(e)}",
- )
-
- # Subscribe to LoroDoc updates
- subscription = doc.subscribe_root(handle_doc_update)
- send_task = asyncio.create_task(send_updates())
-
- try:
- # Listen for updates from the client
- while True:
- message = await websocket.receive_bytes()
- await DOC_MANAGER.broadcast_update(file_key, message, update_queue)
- # Check if the message is an awareness update
- if message.startswith(b"awareness:"):
- LOGGER.debug("RTC: received awareness update")
- else:
- # Apply the update to the LoroDoc
- doc.import_(message)
- except WebSocketDisconnect:
- LOGGER.debug("RTC: WebSocket disconnected")
- # Normal disconnection
- pass
- except Exception as e:
- LOGGER.warning(
- f"RTC: Exception in websocket loop for file {file_key}: {str(e)}"
- )
- finally:
- LOGGER.debug("RTC: Cleaning up resources")
- # Cleanup resources
- send_task.cancel()
- subscription.unsubscribe()
- await DOC_MANAGER.remove_client(file_key, update_queue)
-
-
-KIOSK_ONLY_OPERATIONS = {
- FocusCell.name,
-}
-KIOSK_EXCLUDED_OPERATIONS = {
- CompletionResult.name,
-}
-
-
-class WebsocketHandler(SessionConsumer):
- """WebSocket that sessions use to send messages to frontends.
-
- Each new socket gets a unique session. At most one session can exist when
- in edit mode.
- """
-
- def __init__(
- self,
- *,
- websocket: WebSocket,
- manager: SessionManager,
- rtc_enabled: bool,
- session_id: SessionId,
- mode: SessionMode,
- file_key: MarimoFileKey,
- kiosk: bool,
- auto_instantiate: bool,
- ):
- self.websocket = websocket
- self.manager = manager
- self.rtc_enabled = rtc_enabled
- self.session_id = session_id
- self.file_key = file_key
- self.mode = mode
- self.status: ConnectionState
- self.kiosk = kiosk
- self.auto_instantiate = auto_instantiate
- self.cancel_close_handle: Optional[asyncio.TimerHandle] = None
- self.heartbeat_task: Optional[asyncio.Task[None]] = None
- # Messages from the kernel are put in this queue
- # to be sent to the frontend
- self.message_queue: asyncio.Queue[KernelMessage]
- self.ws_future: asyncio.Future[tuple[None, None]] | None = None
- self._consumer_id = ConsumerId(session_id)
-
- @property
- def consumer_id(self) -> ConsumerId:
- return self._consumer_id
-
- def notify(self, notification: KernelMessage) -> None:
- self.message_queue.put_nowait(notification)
-
- def _serialize_and_notify(self, notification: MessageOperation) -> None:
- self.notify(serialize_kernel_message(notification))
-
- def _write_kernel_ready(
- self,
- session: Session,
- resumed: bool,
- ui_values: dict[str, JSONType],
- last_executed_code: dict[CellId_t, str],
- last_execution_time: dict[CellId_t, float],
- kiosk: bool,
- ) -> None:
- """Communicates to the client that the kernel is ready.
-
- Sends cell code and other metadata to client.
- """
- mgr = self.manager
- file_manager = session.app_file_manager
- app = file_manager.app
-
- codes: tuple[str, ...]
- names: tuple[str, ...]
- configs: tuple[CellConfig, ...]
-
- if mgr.should_send_code_to_frontend():
- codes, names, configs, cell_ids = tuple(
- zip(
- *tuple(
- (
- cell_data.code,
- cell_data.name,
- cell_data.config,
- cell_data.cell_id,
- )
- for cell_data in app.cell_manager.cell_data()
- )
- )
- )
-
- # If RTC is enabled, initialize the LoroDoc with cell code
- if self.rtc_enabled and self.mode == SessionMode.EDIT:
- if not (LORO_ALLOWED and DependencyManager.loro.has()):
- LOGGER.warning(
- "RTC: Loro is not installed, disabling real-time collaboration"
- )
- self.rtc_enabled = False
- else:
- asyncio.create_task(
- DOC_MANAGER.create_doc(self.file_key, cell_ids, codes)
- )
-
- else:
- codes, names, configs, cell_ids = tuple(
- zip(
- *tuple(
- # Don't send code to frontend in run mode
- ("", "", cell_data.config, cell_data.cell_id)
- for cell_data in app.cell_manager.cell_data()
- )
- )
- )
-
- last_executed_code = {}
- last_execution_time = {}
-
- self._serialize_and_notify(
- KernelReady(
- codes=codes,
- names=names,
- configs=configs,
- layout=file_manager.read_layout_config(),
- cell_ids=cell_ids,
- resumed=resumed,
- ui_values=ui_values,
- last_executed_code=last_executed_code,
- last_execution_time=last_execution_time,
- app_config=app.config,
- kiosk=kiosk,
- capabilities=KernelCapabilities(),
- )
- )
-
- def _reconnect_session(self, session: Session, replay: bool) -> None:
- """Reconnect to an existing session (kernel).
-
- A websocket can be closed when a user's computer goes to sleep,
- spurious network issues, etc.
- """
- # Cancel previous close handle
- if self.cancel_close_handle is not None:
- self.cancel_close_handle.cancel()
-
- self.status = ConnectionState.OPEN
- session.connect_consumer(self, main=True)
-
- # Write reconnected message
- self._serialize_and_notify(Reconnected())
-
- # If not replaying, just send a toast
- if not replay:
- self._serialize_and_notify(
- Alert(
- title="Reconnected",
- description="You have reconnected to an existing session.",
- )
- )
- return
-
- self._write_kernel_ready(
- session=session,
- resumed=True,
- ui_values=session.session_view.ui_values,
- last_executed_code=session.session_view.last_executed_code,
- last_execution_time=session.session_view.last_execution_time,
- kiosk=self.kiosk,
- )
- self._serialize_and_notify(
- Banner(
- title="Reconnected",
- description="You have reconnected to an existing session.",
- action="restart",
- )
- )
-
- self._replay_previous_session(session)
-
- def _connect_kiosk(self, session: Session) -> None:
- """Connect to a kiosk session.
-
- A kiosk session is a write-ish session that is connected to a
- frontend. It can set UI elements and interact with the sidebar,
- but cannot change or execute code. This is not a permission limitation,
- but rather we don't have full multi-player support yet.
-
- Kiosk mode is useful when the user is using an editor (VSCode or VIM)
- that does not easily support our reactive frontend or our panels.
- The user uses VSCode or VIM to write code, and the
- marimo kiosk/frontend to visualize the output.
- """
-
- session.connect_consumer(self, main=False)
- self.status = ConnectionState.CONNECTING
- self._write_kernel_ready(
- session=session,
- resumed=True,
- ui_values=session.session_view.ui_values,
- last_executed_code=session.session_view.last_executed_code,
- last_execution_time=session.session_view.last_execution_time,
- kiosk=True,
- )
- self.status = ConnectionState.OPEN
- self._replay_previous_session(session)
-
- def _replay_previous_session(self, session: Session) -> None:
- """Replay the previous session view."""
- operations = session.session_view.operations
- if len(operations) == 0:
- LOGGER.debug("No operations to replay")
- return
- LOGGER.debug(f"Replaying {len(operations)} operations")
- for op in operations:
- LOGGER.debug("Replaying operation %s", op)
- self._serialize_and_notify(op)
-
- def _on_disconnect(
- self,
- e: Exception,
- cleanup_fn: Callable[[], Any],
- ) -> None:
- LOGGER.debug(
- "Websocket disconnected for session %s with exception %s, type %s",
- self.session_id,
- str(e),
- type(e),
- )
-
- # Change the status
- self.status = ConnectionState.CLOSED
- # Disconnect the consumer
- session = self.manager.get_session(self.session_id)
- if session:
- session.disconnect_consumer(self)
-
- if self.manager.mode == SessionMode.RUN:
- # When the websocket is closed, we wait session.ttl_seconds before
- # closing the session. This is to prevent the session from being
- # closed if the during an intermittent network issue.
- def _close() -> None:
- if self.status != ConnectionState.OPEN:
- LOGGER.debug(
- "Closing session %s (TTL EXPIRED)",
- self.session_id,
- )
- # wait until TTL is expired before calling the cleanup
- # function
- cleanup_fn()
- self.manager.close_session(self.session_id)
-
- session = self.manager.get_session(self.session_id)
- if session is not None:
- cancellation_handle = asyncio.get_event_loop().call_later(
- session.ttl_seconds, _close
- )
- self.cancel_close_handle = cancellation_handle
- else:
- _close()
- else:
- cleanup_fn()
-
- async def start(self) -> None:
- # Accept the websocket connection
- await self.websocket.accept()
- # Create a new queue for this session
- self.message_queue = asyncio.Queue()
-
- session_id = self.session_id
- mgr = self.manager
- LOGGER.debug(
- "Websocket open request for session with id %s", session_id
- )
- LOGGER.debug("Existing sessions: %s", mgr.sessions)
-
- # Only one frontend can be connected at a time in edit mode,
- # if RTC is not enabled.
- if (
- mgr.mode == SessionMode.EDIT
- and mgr.any_clients_connected(self.file_key)
- and not self.kiosk
- and not self.rtc_enabled
- ):
- LOGGER.debug(
- "Refusing connection; a frontend is already connected."
- )
- if self.websocket.application_state is WebSocketState.CONNECTED:
- await self.websocket.close(
- WebSocketCodes.ALREADY_CONNECTED,
- "MARIMO_ALREADY_CONNECTED",
- )
- return
-
- def get_session() -> Session:
- # 1. If we are in kiosk mode, connect to the existing session
- if self.kiosk:
- if self.mode is not SessionMode.EDIT:
- LOGGER.debug("Kiosk mode is only supported in edit mode")
- raise WebSocketDisconnect(
- WebSocketCodes.FORBIDDEN, "MARIMO_KIOSK_NOT_ALLOWED"
- )
- kiosk_session = mgr.get_session(session_id)
- if kiosk_session is None:
- LOGGER.debug(
- "Kiosk session not found for session id %s",
- session_id,
- )
- kiosk_session = mgr.get_session_by_file_key(self.file_key)
- if kiosk_session is None:
- LOGGER.debug(
- "Kiosk session not found for file key %s",
- self.file_key,
- )
- raise WebSocketDisconnect(
- WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_SESSION"
- )
- LOGGER.debug("Connecting to kiosk session")
- self._connect_kiosk(kiosk_session)
- return kiosk_session
-
- # 2. Handle reconnection
-
- # The session already exists, but it was disconnected.
- # This can happen in local development when the client
- # goes to sleep and wakes later. Just replace the session's
- # socket, but keep its kernel.
- existing_session = mgr.get_session(session_id)
- if existing_session is not None:
- LOGGER.debug("Reconnecting session %s", session_id)
- # In case there is a lingering connection, close it
- existing_session.disconnect_main_consumer()
- self._reconnect_session(existing_session, replay=False)
- return existing_session
-
- # 3. Check for existing session with same file
- existing_session = mgr.get_session_by_file_key(self.file_key)
- if (
- existing_session is not None
- and self.rtc_enabled
- and self.mode == SessionMode.EDIT
- ):
- LOGGER.debug(
- "Connecting to existing session for file %s", self.file_key
- )
- self._connect_to_existing_session(existing_session)
- return existing_session
-
- # 4. Handle resume
- resumable_session = mgr.maybe_resume_session(
- session_id, self.file_key
- )
- if resumable_session is not None:
- LOGGER.debug("Resuming session %s", session_id)
- self._reconnect_session(resumable_session, replay=True)
- return resumable_session
-
- # 5. Create new session
-
- # Grab the query params from the websocket
- # Note: if we resume a session, we don't pick up the new query
- # params, and instead use the query params from when the
- # session was created.
- query_params = QueryParams({}, NoopStream())
- for key, value in self.websocket.query_params.multi_items():
- if key in QueryParams.IGNORED_KEYS:
- continue
- query_params.append(key, value)
-
- new_session = mgr.create_session(
- query_params=query_params.to_dict(),
- session_id=session_id,
- session_consumer=self,
- file_key=self.file_key,
- auto_instantiate=self.auto_instantiate,
- )
- self.status = ConnectionState.CONNECTING
- # Let the frontend know it can instantiate the app.
- self._write_kernel_ready(
- new_session,
- resumed=False,
- ui_values={},
- last_executed_code={},
- last_execution_time={},
- kiosk=False,
- )
- self.status = ConnectionState.OPEN
- self._replay_previous_session(new_session)
- return new_session
-
- get_session()
-
- async def listen_for_messages() -> None:
- while True:
- data = await self.message_queue.get()
- op: str = deserialize_kernel_operation_name(data)
-
- if op in KIOSK_ONLY_OPERATIONS and not self.kiosk:
- LOGGER.debug(
- "Ignoring operation %s, not in kiosk mode",
- op,
- )
- continue
- if op in KIOSK_EXCLUDED_OPERATIONS and self.kiosk:
- LOGGER.debug(
- "Ignoring operation %s, in kiosk mode",
- op,
- )
- continue
-
- try:
- text = f'{{"op": "{op}", "data": {data.decode("utf-8")}}}'
- except Exception as e:
- # This is a deserialization error
- LOGGER.error(
- "Failed to send message to frontend: %s", str(e)
- )
- LOGGER.error("Message: %s", data)
- continue
-
- try:
- await self.websocket.send_text(text)
- except WebSocketDisconnect as e:
- self._on_disconnect(
- e,
- cleanup_fn=lambda: listen_for_disconnect_task.cancel(),
- )
- except RuntimeError as e:
- # Starlette can raise a runtime error if a message is sent
- # when the socket is closed. In case the disconnection
- # error hasn't made its way to listen_for_disconnect, do
- # the cleanup here.
- if (
- self.websocket.application_state
- == WebSocketState.DISCONNECTED
- ):
- self._on_disconnect(
- e,
- cleanup_fn=lambda: listen_for_disconnect_task.cancel(), # noqa: E501
- )
-
- async def listen_for_disconnect() -> None:
- try:
- self._check_status_update()
- await self.websocket.receive_text()
- except WebSocketDisconnect as e:
- self._on_disconnect(
- e, cleanup_fn=lambda: listen_for_messages_task.cancel()
- )
-
- listen_for_messages_task = asyncio.create_task(listen_for_messages())
- listen_for_disconnect_task = asyncio.create_task(
- listen_for_disconnect()
- )
-
- try:
- self.ws_future = asyncio.gather(
- listen_for_messages_task,
- listen_for_disconnect_task,
- )
- await self.ws_future
- except asyncio.CancelledError:
- LOGGER.debug("Websocket terminated with CancelledError")
- pass
-
- def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:
- del session
- del event_bus
-
- def on_detach(self) -> None:
- # If the websocket is open, send a close message
- is_connected = (
- self.status == ConnectionState.OPEN
- or self.status == ConnectionState.CONNECTING
- ) and self.websocket.application_state is WebSocketState.CONNECTED
- if is_connected:
- asyncio.create_task(
- self.websocket.close(
- WebSocketCodes.NORMAL_CLOSE, "MARIMO_SHUTDOWN"
- )
- )
-
- if self.ws_future:
- self.ws_future.cancel()
-
- def connection_state(self) -> ConnectionState:
- return self.status
-
- def _check_status_update(self) -> None:
- # Only check for updates if we're in edit mode
- if (
- not GLOBAL_SETTINGS.CHECK_STATUS_UPDATE
- or self.mode != SessionMode.EDIT
- ):
- return
-
- def on_update(current_version: str, state: MarimoCLIState) -> None:
- # Let's only toast once per marimo server
- # so we can just store this in memory.
- # We still want to check for updates (which are debounced 24 hours)
- # but don't keep toasting.
- global has_toasted
- if has_toasted:
- return
-
- has_toasted = True
-
- title = (
- f"Update available {current_version} → {state.latest_version}"
- )
- release_url = "https://github.com/marimo-team/marimo/releases"
-
- # Build description with notices if present
- description = f"Check out the <a class='underline' target='_blank' href='{release_url}'>latest release on GitHub.</a>" # noqa: E501
-
- if state.notices:
- notices_text = (
- "<br><br><strong>Recent updates:</strong><br>"
- + "<br>".join(f"• {notice}" for notice in state.notices)
- )
- description += notices_text
-
- self._serialize_and_notify(
- Alert(title=title, description=description)
- )
-
- check_for_updates(on_update)
-
- def _connect_to_existing_session(self, session: Session) -> None:
- """Connect to an existing session and replay all messages."""
- self.status = ConnectionState.CONNECTING
- session.connect_consumer(self, main=False)
-
- # Write kernel ready with current state
- self._write_kernel_ready(
- session=session,
- resumed=True,
- ui_values=session.session_view.ui_values,
- last_executed_code=session.session_view.last_executed_code,
- last_execution_time=session.session_view.last_execution_time,
- kiosk=False,
- )
- self.status = ConnectionState.OPEN
-
- # Replay all operations
- self._replay_previous_session(session)
-
-
-has_toasted = False
diff --git a/marimo/_server/api/endpoints/ws/ws_connection_validator.py b/marimo/_server/api/endpoints/ws/ws_connection_validator.py
new file mode 100644
index 0000000000..7204022d51
--- /dev/null
+++ b/marimo/_server/api/endpoints/ws/ws_connection_validator.py
@@ -0,0 +1,119 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+ from starlette.websockets import WebSocket
+
+from marimo import _loggers
+from marimo._server.api.auth import validate_auth
+from marimo._server.api.deps import AppState
+from marimo._server.codes import WebSocketCodes
+from marimo._server.file_router import MarimoFileKey
+from marimo._types.ids import SessionId
+
+LOGGER = _loggers.marimo_logger()
+
+SESSION_QUERY_PARAM_KEY = "session_id"
+FILE_QUERY_PARAM_KEY = "file"
+KIOSK_QUERY_PARAM_KEY = "kiosk"
+
+
+@dataclass
+class ConnectionParams:
+ """Parameters extracted from WebSocket connection request."""
+
+ session_id: SessionId
+ file_key: MarimoFileKey
+ kiosk: bool
+ auto_instantiate: bool
+ rtc_enabled: bool
+
+
+class WebSocketConnectionValidator:
+ """Validates and extracts connection parameters from WebSocket requests."""
+
+ def __init__(self, websocket: WebSocket, app_state: AppState):
+ self.websocket = websocket
+ self.app_state = app_state
+
+ async def validate_auth(self) -> bool:
+ """Validate authentication, close socket if invalid.
+
+ Returns:
+ True if authentication is valid or not required, False otherwise.
+ """
+ if self.app_state.enable_auth and not validate_auth(self.websocket):
+ await self.websocket.close(
+ WebSocketCodes.UNAUTHORIZED, "MARIMO_UNAUTHORIZED"
+ )
+ return False
+ return True
+
+ async def extract_connection_params(
+ self,
+ ) -> Optional[ConnectionParams]:
+ """Extract and validate connection parameters.
+
+ Returns:
+ ConnectionParams if all parameters are valid, None otherwise.
+ """
+ # Extract session_id
+ raw_session_id = self.app_state.query_params(SESSION_QUERY_PARAM_KEY)
+ if raw_session_id is None:
+ await self.websocket.close(
+ WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_SESSION_ID"
+ )
+ return None
+
+ session_id = SessionId(raw_session_id)
+
+ # Extract file_key
+ file_key: Optional[MarimoFileKey] = (
+ self.app_state.query_params(FILE_QUERY_PARAM_KEY)
+ or self.app_state.session_manager.file_router.get_unique_file_key()
+ )
+
+ if file_key is None:
+ await self.websocket.close(
+ WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_FILE_KEY"
+ )
+ return None
+
+ # Extract kiosk mode
+ kiosk = self.app_state.query_params(KIOSK_QUERY_PARAM_KEY) == "true"
+
+ # Extract config-based parameters
+ config = self.app_state.config_manager_at_file(file_key).get_config()
+ rtc_enabled = config.get("experimental", {}).get("rtc_v2", False)
+ auto_instantiate = config["runtime"]["auto_instantiate"]
+
+ return ConnectionParams(
+ session_id=session_id,
+ file_key=file_key,
+ kiosk=kiosk,
+ auto_instantiate=auto_instantiate,
+ rtc_enabled=rtc_enabled,
+ )
+
+ async def extract_file_key_only(self) -> Optional[MarimoFileKey]:
+ """Extract only the file_key parameter (for RTC endpoint).
+
+ Returns:
+ MarimoFileKey if valid, None otherwise.
+ """
+ file_key: Optional[MarimoFileKey] = (
+ self.app_state.query_params(FILE_QUERY_PARAM_KEY)
+ or self.app_state.session_manager.file_router.get_unique_file_key()
+ )
+
+ if file_key is None:
+ LOGGER.warning("RTC: Closing websocket - no file key")
+ await self.websocket.close(
+ WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_FILE_KEY"
+ )
+ return None
+
+ return file_key
diff --git a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
new file mode 100644
index 0000000000..316b00b86e
--- /dev/null
+++ b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
@@ -0,0 +1,174 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+from marimo._ast.cell import CellConfig
+from marimo._dependencies.dependencies import DependencyManager
+from marimo._messaging.ops import KernelCapabilities, KernelReady
+from marimo._plugins.core.web_component import JSONType
+from marimo._server.model import SessionMode
+from marimo._types.ids import CellId_t
+
+if TYPE_CHECKING:
+ from marimo._server.file_router import MarimoFileKey
+ from marimo._server.rtc.doc import LoroDocManager
+ from marimo._server.sessions import Session, SessionManager
+
+LOGGER = _loggers.marimo_logger()
+
+LORO_ALLOWED = sys.version_info >= (3, 11)
+
+
+def build_kernel_ready(
+ session: Session,
+ manager: SessionManager,
+ resumed: bool,
+ ui_values: dict[str, JSONType],
+ last_executed_code: dict[CellId_t, str],
+ last_execution_time: dict[CellId_t, float],
+ kiosk: bool,
+ rtc_enabled: bool,
+ file_key: MarimoFileKey,
+ mode: SessionMode,
+ doc_manager: LoroDocManager,
+) -> KernelReady:
+ """Build a KernelReady message.
+
+ Args:
+ session: Current session
+ manager: Session manager
+ resumed: Whether this is a resumed session
+ ui_values: UI element values
+ last_executed_code: Last executed code for each cell
+ last_execution_time: Last execution time for each cell
+ kiosk: Whether this is kiosk mode
+ rtc_enabled: Whether RTC is enabled
+ file_key: File key for the session
+ mode: Session mode (edit/run)
+ doc_manager: LoroDoc manager for RTC
+
+ Returns:
+ KernelReady message operation.
+ """
+ codes, names, configs, cell_ids = _extract_cell_data(session, manager)
+
+ # Initialize RTC if needed
+ if _should_init_rtc(rtc_enabled, mode):
+ _try_init_rtc_doc(cell_ids, codes, file_key, doc_manager)
+
+ return KernelReady(
+ codes=codes,
+ names=names,
+ configs=configs,
+ layout=session.app_file_manager.read_layout_config(),
+ cell_ids=cell_ids,
+ resumed=resumed,
+ ui_values=ui_values,
+ last_executed_code=last_executed_code,
+ last_execution_time=last_execution_time,
+ app_config=session.app_file_manager.app.config,
+ kiosk=kiosk,
+ capabilities=KernelCapabilities(),
+ )
+
+
+def _extract_cell_data(
+ session: Session,
+ manager: SessionManager,
+) -> tuple[
+ tuple[str, ...],
+ tuple[str, ...],
+ tuple[CellConfig, ...],
+ tuple[CellId_t, ...],
+]:
+ """Extract cell data based on mode.
+
+ Args:
+ session: Current session
+ manager: Session manager
+
+ Returns:
+ Tuple of (codes, names, configs, cell_ids).
+ """
+ file_manager = session.app_file_manager
+ app = file_manager.app
+
+ if manager.should_send_code_to_frontend():
+ # Send full cell data to frontend
+ codes, names, configs, cell_ids = tuple(
+ zip(
+ *tuple(
+ (
+ cell_data.code,
+ cell_data.name,
+ cell_data.config,
+ cell_data.cell_id,
+ )
+ for cell_data in app.cell_manager.cell_data()
+ )
+ )
+ )
+ return codes, names, configs, cell_ids
+ else:
+ # Don't send code to frontend in run mode
+ codes, names, configs, cell_ids = tuple(
+ zip(
+ *tuple(
+ ("", "", cell_data.config, cell_data.cell_id)
+ for cell_data in app.cell_manager.cell_data()
+ )
+ )
+ )
+ return codes, names, configs, cell_ids
+
+
+def is_rtc_available() -> bool:
+ """Check if RTC (Loro) is available on this system.
+
+ Returns:
+ True if Loro is available, False otherwise.
+ """
+ return LORO_ALLOWED and DependencyManager.loro.has()
+
+
+def _should_init_rtc(rtc_enabled: bool, mode: SessionMode) -> bool:
+ """Check if RTC should be initialized.
+
+ Args:
+ rtc_enabled: Whether RTC is currently enabled
+ mode: Session mode (edit/run)
+
+ Returns:
+ True if RTC should be initialized, False otherwise.
+ """
+ return rtc_enabled and mode == SessionMode.EDIT and is_rtc_available()
+
+
+def _try_init_rtc_doc(
+ cell_ids: tuple[CellId_t, ...],
+ codes: tuple[str, ...],
+ file_key: MarimoFileKey,
+ doc_manager: LoroDocManager,
+) -> None:
+ """Try to initialize RTC document with cell data.
+
+ Logs a warning if Loro is not available but does not fail.
+
+ Args:
+ cell_ids: Cell IDs to initialize
+ codes: Cell codes to initialize
+ file_key: File key for the document
+ doc_manager: LoroDoc manager
+ """
+ if not LORO_ALLOWED:
+ LOGGER.warning("RTC: Python version is not supported (requires 3.11+)")
+ elif not DependencyManager.loro.has():
+ LOGGER.warning(
+ "RTC: Loro is not installed, disabling real-time collaboration"
+ )
+ else:
+ asyncio.create_task(doc_manager.create_doc(file_key, cell_ids, codes))
diff --git a/marimo/_server/api/endpoints/ws/ws_message_loop.py b/marimo/_server/api/endpoints/ws/ws_message_loop.py
new file mode 100644
index 0000000000..a461d45579
--- /dev/null
+++ b/marimo/_server/api/endpoints/ws/ws_message_loop.py
@@ -0,0 +1,162 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, Callable
+
+from starlette.websockets import WebSocketDisconnect, WebSocketState
+
+from marimo import _loggers
+from marimo._messaging.ops import (
+ CompletionResult,
+ FocusCell,
+)
+from marimo._messaging.serde import deserialize_kernel_operation_name
+from marimo._messaging.types import KernelMessage
+
+if TYPE_CHECKING:
+ from starlette.websockets import WebSocket
+
+LOGGER = _loggers.marimo_logger()
+
+# Operations that are only sent in kiosk mode
+KIOSK_ONLY_OPERATIONS = {
+ FocusCell.name,
+}
+
+# Operations that are excluded from kiosk mode
+KIOSK_EXCLUDED_OPERATIONS = {
+ CompletionResult.name,
+}
+
+
+class WebSocketMessageLoop:
+ """Handles the async message send/receive loops for WebSocket."""
+
+ def __init__(
+ self,
+ websocket: WebSocket,
+ message_queue: asyncio.Queue[KernelMessage],
+ kiosk: bool,
+ on_disconnect: Callable[[Exception, Callable[[], Any]], None],
+ on_check_status_update: Callable[[], None],
+ ):
+ self.websocket = websocket
+ self.message_queue = message_queue
+ self.kiosk = kiosk
+ self.on_disconnect = on_disconnect
+ self.on_check_status_update = on_check_status_update
+ self._listen_messages_task: asyncio.Task[None] | None = None
+ self._listen_disconnect_task: asyncio.Task[None] | None = None
+
+ async def start(self) -> None:
+ """Start the message loops.
+
+ Runs two concurrent tasks:
+ - listen_for_messages: Sends messages from kernel to frontend
+ - listen_for_disconnect: Detects when WebSocket disconnects
+ """
+ self._listen_messages_task = asyncio.create_task(
+ self._listen_for_messages()
+ )
+ self._listen_disconnect_task = asyncio.create_task(
+ self._listen_for_disconnect()
+ )
+
+ await asyncio.gather(
+ self._listen_messages_task,
+ self._listen_disconnect_task,
+ )
+
+ async def _listen_for_messages(self) -> None:
+ """Listen for messages from kernel and send to frontend."""
+ while True:
+ data = await self.message_queue.get()
+ op: str = deserialize_kernel_operation_name(data)
+
+ if self._should_filter_operation(op):
+ continue
+
+ # Serialize message
+ try:
+ text = f'{{"op": "{op}", "data": {data.decode("utf-8")}}}'
+ except Exception as e:
+ LOGGER.error("Failed to deserialize message: %s", str(e))
+ LOGGER.error("Message: %s", data)
+ continue
+
+ # Send to WebSocket
+ try:
+ await self.websocket.send_text(text)
+ except WebSocketDisconnect as e:
+ self.on_disconnect(e, self._cancel_disconnect_task)
+ except RuntimeError as e:
+ # Starlette can raise a runtime error if a message is sent
+ # when the socket is closed. In case the disconnection
+ # error hasn't made its way to listen_for_disconnect, do
+ # the cleanup here.
+ if (
+ self.websocket.application_state
+ == WebSocketState.DISCONNECTED
+ ):
+ self.on_disconnect(e, self._cancel_disconnect_task)
+ else:
+ LOGGER.error(
+ "Error sending message to frontend: %s", str(e)
+ )
+ except Exception as e:
+ LOGGER.error("Error sending message to frontend: %s", str(e))
+ raise e
+
+ async def _listen_for_disconnect(self) -> None:
+ """Listen for WebSocket disconnect."""
+ try:
+ # Check for marimo updates when connection starts
+ self.on_check_status_update()
+ # Wait for disconnection
+ await self.websocket.receive_text()
+ except WebSocketDisconnect as e:
+ self.on_disconnect(e, self._cancel_messages_task)
+ except Exception as e:
+ LOGGER.error("Error listening for disconnect: %s", str(e))
+ raise e
+
+ def _should_filter_operation(self, op: str) -> bool:
+ """Determine if operation should be filtered based on kiosk mode.
+
+ Args:
+ op: Operation name to check
+
+ Returns:
+ True if the operation should be filtered (not sent), False
+ otherwise.
+ """
+ if op in KIOSK_ONLY_OPERATIONS and not self.kiosk:
+ LOGGER.debug(
+ "Ignoring operation %s, not in kiosk mode",
+ op,
+ )
+ return True
+ if op in KIOSK_EXCLUDED_OPERATIONS and self.kiosk:
+ LOGGER.debug(
+ "Ignoring operation %s, in kiosk mode",
+ op,
+ )
+ return True
+ return False
+
+ def _cancel_messages_task(self) -> None:
+ """Cancel the messages task."""
+ if (
+ self._listen_messages_task
+ and not self._listen_messages_task.done()
+ ):
+ self._listen_messages_task.cancel()
+
+ def _cancel_disconnect_task(self) -> None:
+ """Cancel the disconnect task."""
+ if (
+ self._listen_disconnect_task
+ and not self._listen_disconnect_task.done()
+ ):
+ self._listen_disconnect_task.cancel()
diff --git a/marimo/_server/api/endpoints/ws/ws_rtc_handler.py b/marimo/_server/api/endpoints/ws/ws_rtc_handler.py
new file mode 100644
index 0000000000..b65eef05ef
--- /dev/null
+++ b/marimo/_server/api/endpoints/ws/ws_rtc_handler.py
@@ -0,0 +1,141 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from starlette.websockets import WebSocketDisconnect
+
+from marimo import _loggers
+
+if TYPE_CHECKING:
+ from loro import DiffEvent, ExportMode, LoroDoc
+ from starlette.websockets import WebSocket
+
+ from marimo._server.file_router import MarimoFileKey
+ from marimo._server.rtc.doc import LoroDocManager
+
+LOGGER = _loggers.marimo_logger()
+
+
+class RTCWebSocketHandler:
+ """Handles Real-Time Collaboration WebSocket connections."""
+
+ def __init__(
+ self,
+ websocket: WebSocket,
+ file_key: MarimoFileKey,
+ doc_manager: LoroDocManager,
+ ):
+ self.websocket = websocket
+ self.file_key = file_key
+ self.doc_manager = doc_manager
+
+ async def handle(self) -> None:
+ """Handle RTC WebSocket connection lifecycle.
+
+ Manages the full lifecycle of an RTC WebSocket connection:
+ 1. Accept the connection
+ 2. Get or create LoroDoc
+ 3. Send initial sync to client
+ 4. Subscribe to updates
+ 5. Handle bidirectional updates
+ 6. Cleanup on disconnect
+ """
+ from loro import ExportMode
+
+ await self.websocket.accept()
+
+ # Get or create the LoroDoc and add the client to it
+ LOGGER.debug("RTC: getting document")
+ update_queue: asyncio.Queue[bytes] = asyncio.Queue()
+ doc = await self.doc_manager.get_or_create_doc(self.file_key)
+ self.doc_manager.add_client_to_doc(self.file_key, update_queue)
+
+ # Send initial sync to client
+ await self._send_initial_sync(doc, ExportMode)
+
+ # Set up update handling
+ def handle_doc_update(event: DiffEvent) -> None:
+ LOGGER.debug("RTC: doc updated", event)
+
+ # Subscribe to LoroDoc updates
+ subscription = doc.subscribe_root(handle_doc_update)
+
+ # Create async task to send updates to the client
+ send_task = asyncio.create_task(
+ self._send_updates_to_client(update_queue)
+ )
+
+ try:
+ # Listen for updates from the client
+ await self._receive_updates_from_client(doc, update_queue)
+ except WebSocketDisconnect:
+ LOGGER.debug("RTC: WebSocket disconnected")
+ except Exception as e:
+ LOGGER.warning(
+ f"RTC: Exception in websocket loop for file {self.file_key}: {str(e)}"
+ )
+ finally:
+ LOGGER.debug("RTC: Cleaning up resources")
+ # Cleanup resources
+ send_task.cancel()
+ subscription.unsubscribe()
+ await self.doc_manager.remove_client(self.file_key, update_queue)
+
+ async def _send_initial_sync(
+ self, doc: LoroDoc, export_mode: type[ExportMode]
+ ) -> None:
+ """Send initial document sync to client.
+
+ Args:
+ doc: LoroDoc instance
+ export_mode: ExportMode from loro module
+ """
+ # Use shallow snapshot for fewer bytes
+ LOGGER.debug("RTC: sending initial sync")
+ init_sync_msg = doc.export(
+ export_mode.ShallowSnapshot(frontiers=doc.state_frontiers)
+ )
+ await self.websocket.send_bytes(init_sync_msg)
+ LOGGER.debug("RTC: initial sync sent")
+
+ async def _send_updates_to_client(
+ self, update_queue: asyncio.Queue[bytes]
+ ) -> None:
+ """Send updates from the document to the client.
+
+ Args:
+ update_queue: Queue of updates to send to client
+ """
+ try:
+ while True:
+ update = await update_queue.get()
+ await self.websocket.send_bytes(update)
+ except Exception as e:
+ LOGGER.warning(
+ f"RTC: Could not send loro update to client for file {self.file_key}: {str(e)}",
+ )
+
+ async def _receive_updates_from_client(
+ self, doc: LoroDoc, update_queue: asyncio.Queue[bytes]
+ ) -> None:
+ """Receive and process updates from the client.
+
+ Args:
+ doc: LoroDoc instance
+ update_queue: Queue used to avoid sending updates back to sender
+ """
+ while True:
+ message = await self.websocket.receive_bytes()
+ # Broadcast to other clients (but not back to sender)
+ await self.doc_manager.broadcast_update(
+ self.file_key, message, update_queue
+ )
+
+ # Check if the message is an awareness update
+ if message.startswith(b"awareness:"):
+ LOGGER.debug("RTC: received awareness update")
+ else:
+ # Apply the update to the LoroDoc
+ doc.import_(message)
diff --git a/marimo/_server/api/endpoints/ws/ws_session_connector.py b/marimo/_server/api/endpoints/ws/ws_session_connector.py
new file mode 100644
index 0000000000..7ae85e8d95
--- /dev/null
+++ b/marimo/_server/api/endpoints/ws/ws_session_connector.py
@@ -0,0 +1,201 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from starlette.websockets import WebSocket
+
+ from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ ConnectionParams,
+ )
+ from marimo._server.api.endpoints.ws_endpoint import WebSocketHandler
+ from marimo._server.sessions import Session, SessionManager
+
+from starlette.websockets import WebSocketDisconnect
+
+from marimo import _loggers
+from marimo._messaging.types import NoopStream
+from marimo._runtime.params import QueryParams
+from marimo._server.codes import WebSocketCodes
+from marimo._server.model import SessionMode
+
+LOGGER = _loggers.marimo_logger()
+
+
+class ConnectionType(Enum):
+ """Type of session connection established."""
+
+ KIOSK = "kiosk"
+ RECONNECT = "reconnect"
+ RTC_EXISTING = "rtc_existing"
+ RESUME = "resume"
+ NEW = "new"
+
+
+class SessionConnector:
+ """Handles different session connection strategies."""
+
+ def __init__(
+ self,
+ manager: SessionManager,
+ handler: WebSocketHandler,
+ params: ConnectionParams,
+ websocket: WebSocket,
+ ):
+ self.manager = manager
+ self.handler = handler
+ self.params = params
+ self.websocket = websocket
+
+ def connect(self) -> tuple[Session, ConnectionType]:
+ """Determine connection type and establish session connection.
+
+ Returns:
+ Tuple of (Session, ConnectionType) indicating the session
+ and how it was connected.
+
+ Raises:
+ WebSocketDisconnect: If the connection cannot be established.
+ """
+ # 1. Kiosk mode
+ if self.params.kiosk:
+ return self._connect_kiosk()
+
+ # 2. Reconnect to existing session with same ID
+ existing_by_id = self.manager.get_session(self.params.session_id)
+ if existing_by_id is not None:
+ return self._reconnect_session(existing_by_id)
+
+ # 3. Connect to existing session (RTC mode)
+ existing_by_file = self.manager.get_session_by_file_key(
+ self.params.file_key
+ )
+ if (
+ existing_by_file is not None
+ and self.params.rtc_enabled
+ and self.manager.mode == SessionMode.EDIT
+ ):
+ return self._connect_rtc_session(existing_by_file)
+
+ # 4. Resume previous session
+ resumable = self.manager.maybe_resume_session(
+ self.params.session_id, self.params.file_key
+ )
+ if resumable is not None:
+ return self._resume_session(resumable)
+
+ # 5. Create new session
+ return self._create_new_session()
+
+ def _connect_kiosk(self) -> tuple[Session, ConnectionType]:
+ """Connect to kiosk session.
+
+ Raises:
+ WebSocketDisconnect: If kiosk mode is not supported or session
+ not found.
+ """
+ if self.manager.mode is not SessionMode.EDIT:
+ LOGGER.debug("Kiosk mode is only supported in edit mode")
+ raise WebSocketDisconnect(
+ WebSocketCodes.FORBIDDEN, "MARIMO_KIOSK_NOT_ALLOWED"
+ )
+
+ # Try to find session by ID first
+ kiosk_session = self.manager.get_session(self.params.session_id)
+ if kiosk_session is None:
+ LOGGER.debug(
+ "Kiosk session not found for session id %s",
+ self.params.session_id,
+ )
+ # Try to find by file key
+ kiosk_session = self.manager.get_session_by_file_key(
+ self.params.file_key
+ )
+
+ if kiosk_session is None:
+ LOGGER.debug(
+ "Kiosk session not found for file key %s",
+ self.params.file_key,
+ )
+ raise WebSocketDisconnect(
+ WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_SESSION"
+ )
+
+ LOGGER.debug("Connecting to kiosk session")
+ self.handler._connect_kiosk(kiosk_session)
+ return kiosk_session, ConnectionType.KIOSK
+
+ def _reconnect_session(
+ self, session: Session
+ ) -> tuple[Session, ConnectionType]:
+ """Reconnect to existing session.
+
+ The session already exists, but it was disconnected. This can happen
+ in local development when the client goes to sleep and wakes later.
+ """
+ LOGGER.debug("Reconnecting session %s", self.params.session_id)
+ # In case there is a lingering connection, close it
+ session.disconnect_main_consumer()
+ self.handler._reconnect_session(session, replay=False)
+ return session, ConnectionType.RECONNECT
+
+ def _connect_rtc_session(
+ self, session: Session
+ ) -> tuple[Session, ConnectionType]:
+ """Connect to RTC-enabled session."""
+ LOGGER.debug(
+ "Connecting to existing session for file %s", self.params.file_key
+ )
+ self.handler._connect_to_existing_session(session)
+ return session, ConnectionType.RTC_EXISTING
+
+ def _resume_session(
+ self, session: Session
+ ) -> tuple[Session, ConnectionType]:
+ """Resume a previous session."""
+ LOGGER.debug("Resuming session %s", self.params.session_id)
+ self.handler._reconnect_session(session, replay=True)
+ return session, ConnectionType.RESUME
+
+ def _create_new_session(self) -> tuple[Session, ConnectionType]:
+ """Create a new session.
+
+ Grabs query params from the websocket and creates a new session
+ with the session manager.
+ """
+ # Grab the query params from the websocket
+ # Note: if we resume a session, we don't pick up the new query
+ # params, and instead use the query params from when the
+ # session was created.
+ query_params = QueryParams({}, NoopStream())
+ for key, value in self.websocket.query_params.multi_items():
+ if key in QueryParams.IGNORED_KEYS:
+ continue
+ query_params.append(key, value)
+
+ new_session = self.manager.create_session(
+ query_params=query_params.to_dict(),
+ session_id=self.params.session_id,
+ session_consumer=self.handler,
+ file_key=self.params.file_key,
+ auto_instantiate=self.params.auto_instantiate,
+ )
+
+ # Notify frontend that kernel is ready
+ from marimo._server.model import ConnectionState
+
+ self.handler.status = ConnectionState.CONNECTING
+ self.handler._write_kernel_ready(
+ new_session,
+ resumed=False,
+ ui_values={},
+ last_executed_code={},
+ last_execution_time={},
+ kiosk=False,
+ )
+ self.handler.status = ConnectionState.OPEN
+ self.handler._replay_previous_session(new_session)
+
+ return new_session, ConnectionType.NEW
diff --git a/marimo/_server/api/endpoints/ws_endpoint.py b/marimo/_server/api/endpoints/ws_endpoint.py
new file mode 100644
index 0000000000..2f1295f036
--- /dev/null
+++ b/marimo/_server/api/endpoints/ws_endpoint.py
@@ -0,0 +1,490 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Any, Callable, Optional
+
+from starlette.websockets import WebSocket, WebSocketState
+
+from marimo import _loggers
+from marimo._cli.upgrade import check_for_updates
+from marimo._config.cli_state import MarimoCLIState
+from marimo._config.settings import GLOBAL_SETTINGS
+from marimo._dependencies.dependencies import DependencyManager
+from marimo._messaging.ops import (
+ Alert,
+ Banner,
+ MessageOperation,
+ Reconnected,
+)
+from marimo._messaging.serde import serialize_kernel_message
+from marimo._messaging.types import KernelMessage
+from marimo._plugins.core.web_component import JSONType
+from marimo._server.api.deps import AppState
+from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ ConnectionParams,
+ WebSocketConnectionValidator,
+)
+from marimo._server.api.endpoints.ws.ws_kernel_ready import (
+ build_kernel_ready,
+ is_rtc_available,
+)
+from marimo._server.api.endpoints.ws.ws_message_loop import (
+ WebSocketMessageLoop,
+)
+from marimo._server.api.endpoints.ws.ws_rtc_handler import RTCWebSocketHandler
+from marimo._server.api.endpoints.ws.ws_session_connector import (
+ SessionConnector,
+)
+from marimo._server.codes import WebSocketCodes
+from marimo._server.consumer import SessionConsumer
+from marimo._server.model import (
+ ConnectionState,
+ SessionMode,
+)
+from marimo._server.router import APIRouter
+from marimo._server.rtc.doc import LoroDocManager
+from marimo._server.sessions import Session, SessionManager
+from marimo._server.sessions.events import SessionEventBus
+from marimo._types.ids import CellId_t, ConsumerId
+
+LOGGER = _loggers.marimo_logger()
+
+LORO_ALLOWED = sys.version_info >= (3, 11)
+
+router = APIRouter()
+
+DOC_MANAGER = LoroDocManager()
+
+
+async def websocket_endpoint(
+ websocket: WebSocket,
+) -> None:
+ """Main WebSocket endpoint for marimo sessions.
+
+ responses:
+ 200:
+ description: Websocket endpoint
+ """
+ app_state = AppState(websocket)
+ validator = WebSocketConnectionValidator(websocket, app_state)
+
+ # Validate authentication before proceeding
+ if not await validator.validate_auth():
+ return
+
+ # Extract and validate connection parameters
+ params = await validator.extract_connection_params()
+ if params is None:
+ return
+
+ # Start handler
+ await WebSocketHandler(
+ websocket=websocket,
+ manager=app_state.session_manager,
+ params=params,
+ mode=app_state.mode,
+ ).start()
+
+
+# WebSocket endpoint for LoroDoc synchronization
[email protected]("/ws_sync")
+async def ws_sync(
+ websocket: WebSocket,
+) -> None:
+ """WebSocket endpoint for LoroDoc synchronization (RTC)."""
+ app_state = AppState(websocket)
+ validator = WebSocketConnectionValidator(websocket, app_state)
+
+ # Validate authentication before proceeding
+ if not await validator.validate_auth():
+ return
+
+ # Check if Loro is available
+ if not (LORO_ALLOWED and DependencyManager.loro.has()):
+ if not LORO_ALLOWED:
+ LOGGER.warning(
+ "RTC: Python version is not supported (requires 3.11+)"
+ )
+ else:
+ LOGGER.warning("RTC: Loro is not installed, closing websocket")
+ await websocket.close(
+ WebSocketCodes.NORMAL_CLOSE, "MARIMO_LORO_NOT_INSTALLED"
+ )
+ return
+
+ # Extract file key
+ file_key = await validator.extract_file_key_only()
+ if file_key is None:
+ return
+
+ # Verify session exists
+ manager = app_state.session_manager
+ session = manager.get_session_by_file_key(file_key)
+ if session is None:
+ LOGGER.warning(
+ f"RTC: Closing websocket - no session found for file key {file_key}"
+ )
+ await websocket.close(WebSocketCodes.FORBIDDEN, "MARIMO_NOT_ALLOWED")
+ return
+
+ # Handle RTC connection
+ handler = RTCWebSocketHandler(websocket, file_key, DOC_MANAGER)
+ await handler.handle()
+
+
+class WebSocketHandler(SessionConsumer):
+ """WebSocket that sessions use to send messages to frontends.
+
+ Each new socket gets a unique session. At most one session can exist when
+ in edit mode (unless RTC is enabled).
+ """
+
+ def __init__(
+ self,
+ *,
+ websocket: WebSocket,
+ manager: SessionManager,
+ params: ConnectionParams,
+ mode: SessionMode,
+ ):
+ self.websocket = websocket
+ self.manager = manager
+ self.params = params
+ self.mode = mode
+ self.status: ConnectionState
+ self.cancel_close_handle: Optional[asyncio.TimerHandle] = None
+ # Messages from the kernel are put in this queue
+ # to be sent to the frontend
+ self.message_queue: asyncio.Queue[KernelMessage]
+ self.ws_future: Optional[asyncio.Task[None]] = None
+ self._consumer_id = ConsumerId(params.session_id)
+
+ @property
+ def consumer_id(self) -> ConsumerId:
+ return self._consumer_id
+
+ def notify(self, notification: KernelMessage) -> None:
+ self.message_queue.put_nowait(notification)
+
+ def _serialize_and_notify(self, notification: MessageOperation) -> None:
+ self.notify(serialize_kernel_message(notification))
+
+ def _write_kernel_ready_from_session_view(
+ self, session: Session, kiosk: bool
+ ) -> None:
+ """Write kernel ready message using current session view state."""
+ self._write_kernel_ready(
+ session=session,
+ resumed=True,
+ ui_values=session.session_view.ui_values,
+ last_executed_code=session.session_view.last_executed_code,
+ last_execution_time=session.session_view.last_execution_time,
+ kiosk=kiosk,
+ )
+
+ def _write_kernel_ready(
+ self,
+ session: Session,
+ resumed: bool,
+ ui_values: dict[str, JSONType],
+ last_executed_code: dict[CellId_t, str],
+ last_execution_time: dict[CellId_t, float],
+ kiosk: bool,
+ ) -> None:
+ """Communicates to the client that the kernel is ready.
+
+ Sends cell code and other metadata to client.
+ """
+ # Only send execution data if sending code to frontend
+ should_send = self.manager.should_send_code_to_frontend()
+
+ # RTC is only enabled if configured AND Loro is available
+ effective_rtc_enabled = self.params.rtc_enabled and is_rtc_available()
+
+ # Build kernel ready message
+ kernel_ready_msg = build_kernel_ready(
+ session=session,
+ manager=self.manager,
+ resumed=resumed,
+ ui_values=ui_values,
+ last_executed_code=last_executed_code if should_send else {},
+ last_execution_time=last_execution_time if should_send else {},
+ kiosk=kiosk,
+ rtc_enabled=effective_rtc_enabled,
+ file_key=self.params.file_key,
+ mode=self.mode,
+ doc_manager=DOC_MANAGER,
+ )
+ self._serialize_and_notify(kernel_ready_msg)
+
+ def _reconnect_session(self, session: Session, replay: bool) -> None:
+ """Reconnect to an existing session (kernel).
+
+ A websocket can be closed when a user's computer goes to sleep,
+ spurious network issues, etc.
+ """
+ # Cancel previous close handle
+ if self.cancel_close_handle is not None:
+ self.cancel_close_handle.cancel()
+
+ self.status = ConnectionState.OPEN
+ session.connect_consumer(self, main=True)
+
+ # Write reconnected message
+ self._serialize_and_notify(Reconnected())
+
+ # If not replaying, just send a toast
+ if not replay:
+ self._serialize_and_notify(
+ Alert(
+ title="Reconnected",
+ description="You have reconnected to an existing session.",
+ )
+ )
+ return
+
+ self._write_kernel_ready_from_session_view(session, self.params.kiosk)
+ self._serialize_and_notify(
+ Banner(
+ title="Reconnected",
+ description="You have reconnected to an existing session.",
+ action="restart",
+ )
+ )
+
+ self._replay_previous_session(session)
+
+ def _connect_kiosk(self, session: Session) -> None:
+ """Connect to a kiosk session.
+
+ A kiosk session is a write-ish session that is connected to a
+ frontend. It can set UI elements and interact with the sidebar,
+ but cannot change or execute code. This is not a permission limitation,
+ but rather we don't have full multi-player support yet.
+
+ Kiosk mode is useful when the user is using an editor (VSCode or VIM)
+ that does not easily support our reactive frontend or our panels.
+ The user uses VSCode or VIM to write code, and the
+ marimo kiosk/frontend to visualize the output.
+ """
+
+ session.connect_consumer(self, main=False)
+ self.status = ConnectionState.CONNECTING
+ self._write_kernel_ready_from_session_view(session, kiosk=True)
+ self.status = ConnectionState.OPEN
+ self._replay_previous_session(session)
+
+ def _replay_previous_session(self, session: Session) -> None:
+ """Replay the previous session view."""
+ operations = session.session_view.operations
+ if len(operations) == 0:
+ LOGGER.debug("No operations to replay")
+ return
+ LOGGER.debug(f"Replaying {len(operations)} operations")
+ for op in operations:
+ LOGGER.debug("Replaying operation %s", op)
+ self._serialize_and_notify(op)
+
+ def _on_disconnect(
+ self,
+ e: Exception,
+ cleanup_fn: Callable[[], Any],
+ ) -> None:
+ LOGGER.debug(
+ "Websocket disconnected for session %s with exception %s, type %s",
+ self.params.session_id,
+ str(e),
+ type(e),
+ )
+
+ # Change the status
+ self.status = ConnectionState.CLOSED
+ # Disconnect the consumer
+ session = self.manager.get_session(self.params.session_id)
+ if session:
+ session.disconnect_consumer(self)
+
+ if self.manager.mode == SessionMode.RUN:
+ # When the websocket is closed, we wait session.ttl_seconds before
+ # closing the session. This is to prevent the session from being
+ # closed if the during an intermittent network issue.
+ def _close() -> None:
+ if self.status != ConnectionState.OPEN:
+ LOGGER.debug(
+ "Closing session %s (TTL EXPIRED)",
+ self.params.session_id,
+ )
+ # wait until TTL is expired before calling the cleanup
+ # function
+ cleanup_fn()
+ self.manager.close_session(self.params.session_id)
+
+ session = self.manager.get_session(self.params.session_id)
+ if session is not None:
+ cancellation_handle = asyncio.get_event_loop().call_later(
+ session.ttl_seconds, _close
+ )
+ self.cancel_close_handle = cancellation_handle
+ else:
+ _close()
+ else:
+ cleanup_fn()
+
+ async def start(self) -> None:
+ """Start the WebSocket handler.
+
+ Accepts the connection, establishes a session, and starts the
+ message loop.
+ """
+ # Accept the websocket connection
+ await self.websocket.accept()
+ # Create a new queue for this session
+ self.message_queue = asyncio.Queue()
+
+ LOGGER.debug(
+ "Websocket open request for session with id %s",
+ self.params.session_id,
+ )
+ LOGGER.debug("Existing sessions: %s", self.manager.sessions)
+
+ # Check if connection is allowed
+ if not self._can_connect():
+ await self._close_already_connected()
+ return
+
+ # Use SessionConnector to establish session connection
+ connector = SessionConnector(
+ manager=self.manager,
+ handler=self,
+ params=self.params,
+ websocket=self.websocket,
+ )
+ session, connection_type = connector.connect()
+ LOGGER.debug(
+ "Connected to session %s with type %s",
+ session.initialization_id,
+ connection_type,
+ )
+
+ # Start message loops
+ message_loop = WebSocketMessageLoop(
+ websocket=self.websocket,
+ message_queue=self.message_queue,
+ kiosk=self.params.kiosk,
+ on_disconnect=self._on_disconnect,
+ on_check_status_update=self._check_status_update,
+ )
+
+ try:
+ self.ws_future = asyncio.create_task(message_loop.start())
+ await self.ws_future
+ except asyncio.CancelledError:
+ LOGGER.debug("Websocket terminated with CancelledError")
+
+ def _can_connect(self) -> bool:
+ """Check if this connection is allowed.
+
+ Only one frontend can be connected at a time in edit mode,
+ if RTC is not enabled.
+ """
+ if (
+ self.manager.mode == SessionMode.EDIT
+ and self.manager.any_clients_connected(self.params.file_key)
+ and not self.params.kiosk
+ and not self.params.rtc_enabled
+ ):
+ LOGGER.debug(
+ "Refusing connection; a frontend is already connected."
+ )
+ return False
+ return True
+
+ async def _close_already_connected(self) -> None:
+ """Close the WebSocket with an 'already connected' error."""
+ if self.websocket.application_state is WebSocketState.CONNECTED:
+ await self.websocket.close(
+ WebSocketCodes.ALREADY_CONNECTED,
+ "MARIMO_ALREADY_CONNECTED",
+ )
+
+ def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:
+ del session
+ del event_bus
+ return None
+
+ def on_detach(self) -> None:
+ # If the websocket is open, send a close message
+ is_connected = (
+ self.status == ConnectionState.OPEN
+ or self.status == ConnectionState.CONNECTING
+ ) and self.websocket.application_state is WebSocketState.CONNECTED
+ if is_connected:
+ asyncio.create_task(
+ self.websocket.close(
+ WebSocketCodes.NORMAL_CLOSE, "MARIMO_SHUTDOWN"
+ )
+ )
+
+ if self.ws_future:
+ self.ws_future.cancel()
+
+ def connection_state(self) -> ConnectionState:
+ return self.status
+
+ def _check_status_update(self) -> None:
+ # Only check for updates if we're in edit mode
+ if (
+ not GLOBAL_SETTINGS.CHECK_STATUS_UPDATE
+ or self.mode != SessionMode.EDIT
+ ):
+ return
+
+ def on_update(current_version: str, state: MarimoCLIState) -> None:
+ # Let's only toast once per marimo server
+ # so we can just store this in memory.
+ # We still want to check for updates (which are debounced 24 hours)
+ # but don't keep toasting.
+ global has_toasted
+ if has_toasted:
+ return
+
+ has_toasted = True
+
+ title = (
+ f"Update available {current_version} → {state.latest_version}"
+ )
+ release_url = "https://github.com/marimo-team/marimo/releases"
+
+ # Build description with notices if present
+ description = f"Check out the <a class='underline' target='_blank' href='{release_url}'>latest release on GitHub.</a>" # noqa: E501
+
+ if state.notices:
+ notices_text = (
+ "<br><br><strong>Recent updates:</strong><br>"
+ + "<br>".join(f"• {notice}" for notice in state.notices)
+ )
+ description += notices_text
+
+ self._serialize_and_notify(
+ Alert(title=title, description=description)
+ )
+
+ check_for_updates(on_update)
+
+ def _connect_to_existing_session(self, session: Session) -> None:
+ """Connect to an existing session and replay all messages."""
+ self.status = ConnectionState.CONNECTING
+ session.connect_consumer(self, main=False)
+
+ # Write kernel ready with current state
+ self._write_kernel_ready_from_session_view(session, kiosk=False)
+ self.status = ConnectionState.OPEN
+
+ # Replay all operations
+ self._replay_previous_session(session)
+
+
+has_toasted = False
diff --git a/marimo/_server/api/router.py b/marimo/_server/api/router.py
index 35abfa6119..259e34ef73 100644
--- a/marimo/_server/api/router.py
+++ b/marimo/_server/api/router.py
@@ -28,7 +28,7 @@ from marimo._server.api.endpoints.packages import router as packages_router
from marimo._server.api.endpoints.secrets import router as secrets_router
from marimo._server.api.endpoints.sql import router as sql_router
from marimo._server.api.endpoints.terminal import router as terminal_router
-from marimo._server.api.endpoints.ws import router as ws_router
+from marimo._server.api.endpoints.ws_endpoint import router as ws_router
from marimo._server.router import APIRouter
if TYPE_CHECKING:
diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.py
index 59b219552e..85d3ffb4bb 100644
--- a/tests/_server/api/endpoints/test_ws.py
+++ b/tests/_server/api/endpoints/test_ws.py
@@ -1,6 +1,7 @@
# Copyright 2024 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
from contextlib import contextmanager
from pathlib import Path
from typing import TYPE_CHECKING, Any, Optional
@@ -410,3 +411,160 @@ def test_ws_with_valid_authentication(client: TestClient) -> None:
# Clean up
client.post("/api/kernel/shutdown", headers=HEADERS)
+
+
+# ==============================================================================
+# Edge Cases - Session Resumption
+# ==============================================================================
+
+
+async def test_session_resumption(client: TestClient) -> None:
+ """Test that session resumption restores state and replays operations."""
+ # Create a session and instantiate it
+ with client.websocket_connect(WS_URL) as websocket:
+ data = websocket.receive_json()
+ assert_kernel_ready_response(data)
+
+ # Instantiate to generate some operations
+ client.post(
+ "/api/kernel/instantiate",
+ headers=headers("123"),
+ json={"objectIds": [], "values": [], "auto_run": True},
+ )
+
+ # Flush initial messages
+ flush_messages(websocket, at_least=1)
+
+ await asyncio.sleep(0.2)
+
+ # Resume with new session ID (simulates browser refresh)
+ with client.websocket_connect(OTHER_WS_URL) as websocket:
+ # Should receive reconnected + resumed state
+ reconnect_msg = websocket.receive_json()
+ assert reconnect_msg["op"] == "reconnected"
+
+ kernel_ready_msg = websocket.receive_json()
+ assert kernel_ready_msg["op"] == "kernel-ready"
+
+ # Verify resumed flag is True
+ data = parse_raw(kernel_ready_msg["data"], KernelReady)
+ assert data.resumed is True
+
+ # Should replay operations - collect some messages
+ replayed = flush_messages(websocket, at_least=1)
+ assert len(replayed) >= 1
+
+ client.post("/api/kernel/shutdown", headers=HEADERS)
+
+
+# ==============================================================================
+# Edge Cases - Disconnection/Reconnection
+# ==============================================================================
+
+
+async def test_reconnection_cancels_close_handle(client: TestClient) -> None:
+ """Test that reconnection properly cancels pending close handle."""
+ session_manager = get_session_manager(client)
+ session_manager.mode = SessionMode.RUN
+
+ with client.websocket_connect(WS_URL) as websocket:
+ data = websocket.receive_json()
+ assert_kernel_ready_response(data)
+
+ # Close the websocket
+ websocket.close()
+
+ # Wait briefly for disconnect handling
+ await asyncio.sleep(0.1)
+
+ # Reconnect immediately (before TTL expires)
+ with client.websocket_connect(WS_URL) as new_websocket:
+ data = new_websocket.receive_json()
+ # Should get reconnected message
+ assert data["op"] == "reconnected"
+
+ # Session should still exist (TTL was canceled)
+ session = session_manager.get_session("123")
+ assert session is not None
+
+ session_manager.mode = SessionMode.EDIT
+ client.post("/api/kernel/shutdown", headers=HEADERS)
+
+
+async def test_run_mode_ttl_expiration(client: TestClient) -> None:
+ """Test that sessions expire after TTL in RUN mode."""
+ session_manager = get_session_manager(client)
+ session_manager.mode = SessionMode.RUN
+
+ with client.websocket_connect(WS_URL) as websocket:
+ data = websocket.receive_json()
+ assert_kernel_ready_response(data)
+
+ session = session_manager.get_session("123")
+ assert session is not None
+
+ # Override TTL to be very short for testing
+ original_ttl = session.ttl_seconds
+ session.ttl_seconds = 0.1
+
+ # Close websocket
+ websocket.close()
+
+ # Wait for TTL to expire
+ await asyncio.sleep(0.3)
+
+ # Session should be closed
+ session = session_manager.get_session("123")
+ assert session is None
+
+ session_manager.mode = SessionMode.EDIT
+
+
+# ==============================================================================
+# Edge Cases - Connection Validation
+# ==============================================================================
+
+
+def test_missing_file_key_closes_connection(client: TestClient) -> None:
+ """Test that missing file key causes connection to close.
+
+ This can happen when file_router.get_unique_file_key() returns None.
+ """
+ from unittest.mock import patch
+
+ session_manager = get_session_manager(client)
+
+ # Mock get_unique_file_key to return None
+ with patch.object(
+ session_manager.file_router,
+ "get_unique_file_key",
+ return_value=None,
+ ):
+ with pytest.raises(WebSocketDisconnect) as exc_info:
+ with client.websocket_connect(
+ "/ws?session_id=123&access_token=fake-token"
+ ):
+ pass
+
+ assert exc_info.value.code == WebSocketCodes.NORMAL_CLOSE
+ assert exc_info.value.reason == "MARIMO_NO_FILE_KEY"
+
+
+async def test_rtc_config_with_loro_unavailable(client: TestClient) -> None:
+ """Regression test: connection works when RTC enabled but Loro unavailable."""
+ from unittest.mock import patch
+
+ # Enable RTC in config but mock Loro as unavailable
+ with (
+ rtc_enabled(get_user_config_manager(client)),
+ patch(
+ "marimo._server.api.endpoints.ws.ws_kernel_ready.is_rtc_available",
+ return_value=False,
+ ),
+ ):
+ # Connection should succeed without errors
+ with client.websocket_connect(WS_URL) as websocket:
+ data = websocket.receive_json()
+ assert_kernel_ready_response(data)
+
+ client.post("/api/kernel/shutdown", headers=HEADERS)
diff --git a/tests/_server/api/endpoints/test_ws_rtc.py b/tests/_server/api/endpoints/test_ws_rtc.py
index 0d74c2a5e1..e04f1bc551 100644
--- a/tests/_server/api/endpoints/test_ws_rtc.py
+++ b/tests/_server/api/endpoints/test_ws_rtc.py
@@ -5,11 +5,12 @@ from contextlib import contextmanager
from typing import TYPE_CHECKING, Any, Optional
import pytest
+from starlette.websockets import WebSocketDisconnect
from marimo._config.manager import UserConfigManager
from marimo._messaging.msgspec_encoder import asdict
from marimo._messaging.ops import KernelCapabilities, KernelReady
-from marimo._server.api.endpoints.ws import DOC_MANAGER
+from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGER
from marimo._utils.parse_dataclass import parse_raw
from tests._server.conftest import get_session_manager, get_user_config_manager
from tests._server.mocks import token_header
@@ -243,3 +244,119 @@ async def test_loro_persistence(client: TestClient) -> None:
assert len(sync_msg) > 0
client.post("/api/kernel/shutdown", headers=HEADERS)
+
+
+# ==============================================================================
+# Edge Cases - RTC Availability and Graceful Degradation
+# ==============================================================================
+
+
+ "sys.version_info < (3, 11) or sys.version_info >= (3, 14)"
+)
+async def test_rtc_degrades_without_loro(client: TestClient) -> None:
+ """Test that RTC gracefully degrades when Loro is unavailable.
+
+ Connection should succeed and no RTC doc should be created.
+ """
+ from unittest.mock import patch
+
+ file_key = get_session_manager(client).file_router.get_unique_file_key()
+ assert file_key is not None
+
+ # Clear any existing docs
+ DOC_MANAGER.loro_docs.clear()
+
+ # Mock Loro as not available
+ with (
+ rtc_enabled(get_user_config_manager(client)),
+ patch(
+ "marimo._server.api.endpoints.ws.ws_kernel_ready.DependencyManager.loro.has",
+ return_value=False,
+ ),
+ ):
+ with client.websocket_connect(
+ "/ws?session_id=123&access_token=fake-token"
+ ) as websocket:
+ data = websocket.receive_json()
+ # Should still get kernel ready, but without RTC initialized
+ assert_kernel_ready_response(data)
+
+ # Give time for any async doc creation
+ await asyncio.sleep(0.2)
+
+ # Verify no RTC doc was created
+ assert file_key not in DOC_MANAGER.loro_docs
+
+ client.post("/api/kernel/shutdown", headers=HEADERS)
+
+
+# ==============================================================================
+# Edge Cases - RTC Sync Endpoint
+# ==============================================================================
+
+
+ "sys.version_info < (3, 11) or sys.version_info >= (3, 14)"
+)
+async def test_ws_sync_without_existing_session(client: TestClient) -> None:
+ """Test that ws_sync endpoint requires an existing session."""
+ file_key = get_session_manager(client).file_router.get_unique_file_key()
+ assert file_key is not None
+
+ ws_sync_url = f"/ws_sync?file={file_key}&access_token=fake-token"
+
+ # Try to connect to ws_sync without creating a main session first
+ with pytest.raises(WebSocketDisconnect) as exc_info:
+ with client.websocket_connect(ws_sync_url):
+ pass
+
+ from marimo._server.codes import WebSocketCodes
+
+ assert exc_info.value.code == WebSocketCodes.FORBIDDEN
+ assert exc_info.value.reason == "MARIMO_NOT_ALLOWED"
+
+
+ "sys.version_info < (3, 11) or sys.version_info >= (3, 14)"
+)
+async def test_ws_sync_cleanup_on_main_disconnect(client: TestClient) -> None:
+ """Test that ws_sync clients are cleaned up when main session disconnects."""
+ file_key = get_session_manager(client).file_router.get_unique_file_key()
+ assert file_key is not None
+
+ # Clear any existing docs
+ DOC_MANAGER.loro_docs_clients.clear()
+
+ ws_1 = "/ws?session_id=123&access_token=fake-token"
+ ws_sync_url = f"/ws_sync?file={file_key}&access_token=fake-token"
+
+ with rtc_enabled(get_user_config_manager(client)):
+ with client.websocket_connect(ws_1) as main_websocket:
+ data = main_websocket.receive_json()
+ assert_kernel_ready_response(data)
+
+ # Connect to sync endpoint
+ with client.websocket_connect(ws_sync_url) as sync_websocket:
+ # Should receive initial sync
+ sync_msg = sync_websocket.receive_bytes()
+ assert len(sync_msg) > 0
+
+ # Verify client was added
+ assert file_key in DOC_MANAGER.loro_docs_clients
+ initial_client_count = len(
+ DOC_MANAGER.loro_docs_clients[file_key]
+ )
+ assert initial_client_count == 1
+
+ # Close sync websocket
+ sync_websocket.close()
+
+ # Wait for cleanup
+ await asyncio.sleep(0.2)
+
+ # Client should be removed
+ if file_key in DOC_MANAGER.loro_docs_clients:
+ assert len(DOC_MANAGER.loro_docs_clients[file_key]) == 0
+
+ client.post("/api/kernel/shutdown", headers=HEADERS)