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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
refactor: split up ws monolith (#7587)
Myles Scolnickd81218179e1a
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex 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_MANAGERfrom marimo._server.api.utils import dispatch_control_request, parse_requestfrom marimo._server.file_router import MarimoFileKeyfrom marimo._server.models.models import (diff --git a/marimo/_server/api/endpoints/ws.py b/marimo/_server/api/endpoints/ws.pydeleted file mode 100644index 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()--[email protected]("/ws")-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 = Falsediff --git a/marimo/_server/api/endpoints/ws/ws_connection_validator.py b/marimo/_server/api/endpoints/ws/ws_connection_validator.pynew file mode 100644index 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_keydiff --git a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py b/marimo/_server/api/endpoints/ws/ws_kernel_ready.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.NEWdiff --git a/marimo/_server/api/endpoints/ws_endpoint.py b/marimo/_server/api/endpoints/ws_endpoint.pynew file mode 100644index 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()++[email protected]("/ws")+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 = Falsediff --git a/marimo/_server/api/router.py b/marimo/_server/api/router.pyindex 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_routerfrom marimo._server.api.endpoints.secrets import router as secrets_routerfrom marimo._server.api.endpoints.sql import router as sql_routerfrom 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_routerfrom marimo._server.router import APIRouterif TYPE_CHECKING:diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.pyindex 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 asynciofrom contextlib import contextmanagerfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Optional@@ -410,3 +411,160 @@ def test_ws_with_valid_authentication(client: TestClient) -> None:# Clean upclient.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.pyindex 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 contextmanagerfrom typing import TYPE_CHECKING, Any, Optionalimport pytest+from starlette.websockets import WebSocketDisconnectfrom marimo._config.manager import UserConfigManagerfrom marimo._messaging.msgspec_encoder import asdictfrom marimo._messaging.ops import KernelCapabilities, KernelReady-from marimo._server.api.endpoints.ws import DOC_MANAGER+from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGERfrom marimo._utils.parse_dataclass import parse_rawfrom tests._server.conftest import get_session_manager, get_user_config_managerfrom tests._server.mocks import token_header@@ -243,3 +244,119 @@ async def test_loro_persistence(client: TestClient) -> None:assert len(sync_msg) > 0client.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)