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(server): centralize WebSocket close reasons in an enum (#9981)
Kiran Gadhaved04af986a3dd
diff --git a/frontend/src/components/editor/header/__tests__/status.test.tsx b/frontend/src/components/editor/header/__tests__/status.test.tsxindex 579eb6234b..84d90c9709 100644--- a/frontend/src/components/editor/header/__tests__/status.test.tsx+++ b/frontend/src/components/editor/header/__tests__/status.test.tsx@@ -67,10 +67,6 @@ describe("StatusOverlay disconnect indicator", () => {});it.each([- [- WebSocketClosedReason.MALFORMED_QUERY,- "the kernel did not recognize a request; please file a bug with marimo",- ],[WebSocketClosedReason.KERNEL_STARTUP_ERROR,"Failed to start kernel sandbox",diff --git a/frontend/src/components/editor/header/status.tsx b/frontend/src/components/editor/header/status.tsxindex 3a5558cfc3..56e1cbe62e 100644--- a/frontend/src/components/editor/header/status.tsx+++ b/frontend/src/components/editor/header/status.tsx@@ -22,9 +22,8 @@ export const StatusOverlay: React.FC<{const { mode } = useAtomValue(viewStateAtom);const isClosed = connection.state === WebSocketState.CLOSED;const isOpen = connection.state === WebSocketState.OPEN;- // Only KERNEL_DISCONNECTED is recoverable by a retry. Other terminal- // reasons (MALFORMED_QUERY, KERNEL_STARTUP_ERROR) would deterministically- // fail the same way.+ // Only KERNEL_DISCONNECTED is recoverable by a retry. KERNEL_STARTUP_ERROR+ // would deterministically fail the same way.const canReconnect =isClosed && connection.code === WebSocketClosedReason.KERNEL_DISCONNECTED;diff --git a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.test.ts b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.test.tsindex 4bb0a999f9..af9cc99d61 100644--- a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.test.ts+++ b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.test.ts@@ -32,7 +32,6 @@ describe("classifyCloseEvent", () => {describe("terminal closes (server-initiated)", () => {it.each([- "MARIMO_WRONG_KERNEL_ID","MARIMO_NO_FILE_KEY","MARIMO_NO_SESSION_ID","MARIMO_NO_SESSION",@@ -49,18 +48,6 @@ describe("classifyCloseEvent", () => {}});- it("MARIMO_MALFORMED_QUERY → terminal but does NOT close transport", () => {- const decision = classify("MARIMO_MALFORMED_QUERY");- expect(decision.kind).toBe("terminal");- expect(decision.status).toMatchObject({- state: WebSocketState.CLOSED,- code: WebSocketClosedReason.MALFORMED_QUERY,- });- if (decision.kind === "terminal") {- expect(decision.closeTransport).toBe(false);- }- });-it("MARIMO_KERNEL_STARTUP_ERROR → terminal + closeTransport", () => {const decision = classify("MARIMO_KERNEL_STARTUP_ERROR");expect(decision.kind).toBe("terminal");diff --git a/frontend/src/core/websocket/types.ts b/frontend/src/core/websocket/types.tsindex 709ff0f9c7..1bb4af0530 100644--- a/frontend/src/core/websocket/types.ts+++ b/frontend/src/core/websocket/types.ts@@ -14,7 +14,6 @@ export type WebSocketState =export const WebSocketClosedReason = {KERNEL_DISCONNECTED: "KERNEL_DISCONNECTED",- MALFORMED_QUERY: "MALFORMED_QUERY",KERNEL_STARTUP_ERROR: "KERNEL_STARTUP_ERROR",} as const;diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsxindex 3547ea9554..dcb13f9320 100644--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx@@ -82,12 +82,10 @@ const SUPPORTS_LAZY_KERNELS = true;// (marimo/_server/api/endpoints/ws_endpoint.py and ws/*.py). Keep in sync with// the backend literals.export type CloseReason =- | "MARIMO_WRONG_KERNEL_ID"| "MARIMO_NO_FILE_KEY"| "MARIMO_NO_SESSION_ID"| "MARIMO_NO_SESSION"| "MARIMO_SHUTDOWN"- | "MARIMO_MALFORMED_QUERY"| "MARIMO_KERNEL_STARTUP_ERROR"| typeof TRANSPORT_EXHAUSTED_REASON;@@ -107,7 +105,6 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {reason: "kernel not found",},};- case "MARIMO_WRONG_KERNEL_ID":case "MARIMO_NO_FILE_KEY":case "MARIMO_NO_SESSION_ID":case "MARIMO_NO_SESSION":@@ -121,17 +118,6 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {},closeTransport: true,};- case "MARIMO_MALFORMED_QUERY":- return {- kind: "terminal",- status: {- state: WebSocketState.CLOSED,- code: WebSocketClosedReason.MALFORMED_QUERY,- reason:- "the kernel did not recognize a request; please file a bug with marimo",- },- closeTransport: false,- };case "MARIMO_KERNEL_STARTUP_ERROR":return {kind: "terminal",diff --git a/marimo/_server/api/endpoints/terminal.py b/marimo/_server/api/endpoints/terminal.pyindex 91a3722dc3..377b39e807 100644--- a/marimo/_server/api/endpoints/terminal.py+++ b/marimo/_server/api/endpoints/terminal.py@@ -16,7 +16,7 @@ from starlette.websockets import WebSocket, WebSocketDisconnect, WebSocketStatefrom marimo import _loggersfrom marimo._server.api.auth import validate_authfrom marimo._server.api.deps import AppState-from marimo._server.codes import WebSocketCodes+from marimo._server.codes import WebSocketCloseReason, WebSocketCodesfrom marimo._server.router import APIRouterfrom marimo._session.model import SessionModefrom marimo._utils.asyncio_utils import cancel_and_wait@@ -354,7 +354,7 @@ async def websocket_endpoint(websocket: WebSocket) -> None:if app_state.enable_auth and not validate_auth(websocket):await websocket.close(- WebSocketCodes.UNAUTHORIZED, "MARIMO_UNAUTHORIZED"+ WebSocketCodes.UNAUTHORIZED, WebSocketCloseReason.UNAUTHORIZED)returndiff --git a/marimo/_server/api/endpoints/ws/ws_connection_validator.py b/marimo/_server/api/endpoints/ws/ws_connection_validator.pyindex 21f65a3d03..83f3e01478 100644--- a/marimo/_server/api/endpoints/ws/ws_connection_validator.py+++ b/marimo/_server/api/endpoints/ws/ws_connection_validator.py@@ -10,7 +10,7 @@ if TYPE_CHECKING:from marimo import _loggersfrom marimo._server.api.auth import validate_authfrom marimo._server.api.deps import AppState-from marimo._server.codes import WebSocketCodes+from marimo._server.codes import WebSocketCloseReason, WebSocketCodesfrom marimo._server.workspace import MarimoFileKeyfrom marimo._types.ids import SessionId@@ -47,7 +47,7 @@ class WebSocketConnectionValidator:"""if self.app_state.enable_auth and not validate_auth(self.websocket):await self.websocket.close(- WebSocketCodes.UNAUTHORIZED, "MARIMO_UNAUTHORIZED"+ WebSocketCodes.UNAUTHORIZED, WebSocketCloseReason.UNAUTHORIZED)return Falsereturn True@@ -64,7 +64,7 @@ class WebSocketConnectionValidator: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"+ WebSocketCodes.NORMAL_CLOSE, WebSocketCloseReason.NO_SESSION_ID)return None@@ -78,7 +78,7 @@ class WebSocketConnectionValidator:if file_key is None:await self.websocket.close(- WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_FILE_KEY"+ WebSocketCodes.NORMAL_CLOSE, WebSocketCloseReason.NO_FILE_KEY)return None@@ -112,7 +112,7 @@ class WebSocketConnectionValidator:if file_key is None:LOGGER.warning("RTC: Closing websocket - no file key")await self.websocket.close(- WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_FILE_KEY"+ WebSocketCodes.NORMAL_CLOSE, WebSocketCloseReason.NO_FILE_KEY)return Nonediff --git a/marimo/_server/api/endpoints/ws/ws_session_connector.py b/marimo/_server/api/endpoints/ws/ws_session_connector.pyindex 304ea7aaf1..7de0ddd45e 100644--- a/marimo/_server/api/endpoints/ws/ws_session_connector.py+++ b/marimo/_server/api/endpoints/ws/ws_session_connector.py@@ -21,7 +21,7 @@ from starlette.websockets import WebSocketDisconnectfrom marimo import _loggersfrom marimo._messaging.types import NoopStreamfrom marimo._runtime.params import QueryParams-from marimo._server.codes import WebSocketCodes+from marimo._server.codes import WebSocketCloseReason, WebSocketCodesfrom marimo._server.models.models import InstantiateNotebookRequestfrom marimo._session.model import ConnectionState, SessionMode@@ -130,7 +130,8 @@ class SessionConnector: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"+ WebSocketCodes.FORBIDDEN,+ WebSocketCloseReason.KIOSK_NOT_ALLOWED,)# Try to find session by ID first@@ -151,7 +152,7 @@ class SessionConnector:self.params.file_key,)raise WebSocketDisconnect(- WebSocketCodes.NORMAL_CLOSE, "MARIMO_NO_SESSION"+ WebSocketCodes.NORMAL_CLOSE, WebSocketCloseReason.NO_SESSION)LOGGER.debug("Connecting to kiosk session")diff --git a/marimo/_server/api/endpoints/ws_endpoint.py b/marimo/_server/api/endpoints/ws_endpoint.pyindex b92a9e167d..ed544e856d 100644--- a/marimo/_server/api/endpoints/ws_endpoint.py+++ b/marimo/_server/api/endpoints/ws_endpoint.py@@ -42,7 +42,7 @@ from marimo._server.api.endpoints.ws.ws_session_connector import (SessionConnector,is_viewer_connection,)-from marimo._server.codes import WebSocketCodes+from marimo._server.codes import WebSocketCloseReason, WebSocketCodesfrom marimo._server.router import APIRouterfrom marimo._server.rtc.doc import LoroDocManagerfrom marimo._server.session_manager import SessionManager@@ -124,7 +124,8 @@ async def ws_sync(else:LOGGER.warning("RTC: Loro is not installed, closing websocket")await websocket.close(- WebSocketCodes.NORMAL_CLOSE, "MARIMO_LORO_NOT_INSTALLED"+ WebSocketCodes.NORMAL_CLOSE,+ WebSocketCloseReason.LORO_NOT_INSTALLED,)return@@ -140,7 +141,9 @@ async def ws_sync(LOGGER.warning(f"RTC: Closing websocket - no session found for file key {file_key}")- await websocket.close(WebSocketCodes.FORBIDDEN, "MARIMO_NOT_ALLOWED")+ await websocket.close(+ WebSocketCodes.FORBIDDEN, WebSocketCloseReason.NOT_ALLOWED+ )return# Handle RTC connection@@ -461,7 +464,7 @@ class WebSocketHandler(SessionConsumer):# Then close with simple reasonawait self._safe_close(WebSocketCodes.UNEXPECTED_ERROR,- "MARIMO_KERNEL_STARTUP_ERROR",+ WebSocketCloseReason.KERNEL_STARTUP_ERROR,)def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:@@ -478,7 +481,7 @@ class WebSocketHandler(SessionConsumer):if is_connected:task = asyncio.create_task(self._safe_close(- WebSocketCodes.NORMAL_CLOSE, "MARIMO_SHUTDOWN"+ WebSocketCodes.NORMAL_CLOSE, WebSocketCloseReason.SHUTDOWN))_background_tasks.add(task)diff --git a/marimo/_server/codes.py b/marimo/_server/codes.pyindex 9e4dce2674..2e75f0a674 100644--- a/marimo/_server/codes.py+++ b/marimo/_server/codes.py@@ -1,7 +1,7 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from enum import IntEnum+from enum import Enum, IntEnumclass WebSocketCodes(IntEnum):@@ -10,3 +10,22 @@ class WebSocketCodes(IntEnum):FORBIDDEN = 1008UNAUTHORIZED = 3000UNEXPECTED_ERROR = 1011+++class WebSocketCloseReason(str, Enum):+ """Reasons the backend sends in a WebSocket close frame.++ The value is the raw `CloseEvent.reason` string sent over the wire. The+ frontend hand-mirrors the subset it handles in+ `frontend/src/core/websocket/useMarimoKernelConnection.tsx`.+ """++ LORO_NOT_INSTALLED = "MARIMO_LORO_NOT_INSTALLED"+ NOT_ALLOWED = "MARIMO_NOT_ALLOWED"+ UNAUTHORIZED = "MARIMO_UNAUTHORIZED"+ NO_SESSION_ID = "MARIMO_NO_SESSION_ID"+ NO_FILE_KEY = "MARIMO_NO_FILE_KEY"+ NO_SESSION = "MARIMO_NO_SESSION"+ KIOSK_NOT_ALLOWED = "MARIMO_KIOSK_NOT_ALLOWED"+ KERNEL_STARTUP_ERROR = "MARIMO_KERNEL_STARTUP_ERROR"+ SHUTDOWN = "MARIMO_SHUTDOWN"diff --git a/tests/_server/test_codes.py b/tests/_server/test_codes.pynew file mode 100644index 0000000000..0c31887be0--- /dev/null+++ b/tests/_server/test_codes.py@@ -0,0 +1,26 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from marimo._server.codes import WebSocketCloseReason+++def test_websocket_close_reason_wire_values() -> None:+ """Pin the raw close-frame strings sent over the wire.++ Renaming a member must not silently change the value the frontend+ matches against in `useMarimoKernelConnection.tsx`.+ """+ assert (+ WebSocketCloseReason.LORO_NOT_INSTALLED == "MARIMO_LORO_NOT_INSTALLED"+ )+ assert WebSocketCloseReason.NOT_ALLOWED == "MARIMO_NOT_ALLOWED"+ assert WebSocketCloseReason.UNAUTHORIZED == "MARIMO_UNAUTHORIZED"+ assert WebSocketCloseReason.NO_SESSION_ID == "MARIMO_NO_SESSION_ID"+ assert WebSocketCloseReason.NO_FILE_KEY == "MARIMO_NO_FILE_KEY"+ assert WebSocketCloseReason.NO_SESSION == "MARIMO_NO_SESSION"+ assert WebSocketCloseReason.KIOSK_NOT_ALLOWED == "MARIMO_KIOSK_NOT_ALLOWED"+ assert (+ WebSocketCloseReason.KERNEL_STARTUP_ERROR+ == "MARIMO_KERNEL_STARTUP_ERROR"+ )+ assert WebSocketCloseReason.SHUTDOWN == "MARIMO_SHUTDOWN"