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
Separate notebook query parameters from stream options (#11417)
Trevor Manza18e93396099
diff --git a/frontend/src/core/runtime/__tests__/createWsUrl.test.ts b/frontend/src/core/runtime/__tests__/createWsUrl.test.tsindex 6159eeadc4..5b2480e614 100644--- a/frontend/src/core/runtime/__tests__/createWsUrl.test.ts+++ b/frontend/src/core/runtime/__tests__/createWsUrl.test.ts@@ -13,7 +13,9 @@ describe("RuntimeManager.getWsURL", () => {});const sessionId = "1234" as SessionId;const url = runtime.getWsURL(sessionId);- expect(url.toString()).toBe("wss://marimo.app/ws?session_id=1234");+ expect(url.toString()).toBe(+ "wss://marimo.app/ws?query_params=&session_id=1234",+ );expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);});@@ -24,7 +26,9 @@ describe("RuntimeManager.getWsURL", () => {});const sessionId = "1234" as SessionId;const url = runtime.getWsURL(sessionId);- expect(url.toString()).toBe("ws://marimo.app/ws?session_id=1234");+ expect(url.toString()).toBe(+ "ws://marimo.app/ws?query_params=&session_id=1234",+ );expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);});@@ -35,7 +39,9 @@ describe("RuntimeManager.getWsURL", () => {});const sessionId = "1234" as SessionId;const url = runtime.getWsURL(sessionId);- expect(url.toString()).toBe("ws://marimo.app/nested/ws?session_id=1234");+ expect(url.toString()).toBe(+ "ws://marimo.app/nested/ws?query_params=&session_id=1234",+ );expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);});@@ -48,7 +54,7 @@ describe("RuntimeManager.getWsURL", () => {const sessionId = "1234" as SessionId;const url = runtime.getWsURL(sessionId);expect(url.toString()).toBe(- "ws://marimo.app/nested/ws?foo=bar&file=test.py&session_id=1234",+ "ws://marimo.app/nested/ws?foo=bar&file=test.py&query_params=foo%3Dbar%26file%3Dtest.py&session_id=1234",);expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);});@@ -62,11 +68,75 @@ describe("RuntimeManager.getWsURL", () => {const sessionId = "1234" as SessionId;const url = runtime.getWsURL(sessionId);expect(url.toString()).toBe(- "ws://marimo.app/ws?file=test.py&search=test&other=last&session_id=1234",+ "ws://marimo.app/ws?file=test.py&query_params=file%3Dtest.py%26search%3Dtest%26other%3Dlast&session_id=1234",);expect(url.searchParams.get("file")).toBe("test.py");- expect(url.searchParams.get("search")).toBe("test");- expect(url.searchParams.get("other")).toBe("last");+ expect(url.searchParams.get("query_params")).toBe(+ "file=test.py&search=test&other=last",+ );expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);});});++describe.each(["getWsURL", "getSseURL"] as const)(+ "RuntimeManager.%s",+ (method) => {+ it("preserves runtime parameters and repeated page values", () => {+ window.history.pushState({}, "", "/?tag=page-one&tag=page-two");+ const runtime = new RuntimeManager(+ {+ url: `${window.location.origin}/nested?proxy_token=secret&tag=base&base=one&base=two`,+ lazy: true,+ },+ true,+ );+ const url = runtime[method]("session" as SessionId);+ expect([...url.searchParams]).toEqual([+ ["proxy_token", "secret"],+ ["tag", "base"],+ ["base", "one"],+ ["base", "two"],+ [+ "query_params",+ "proxy_token=secret&base=one&base=two&tag=page-one&tag=page-two",+ ],+ ["session_id", "session"],+ ]);+ });++ it("keeps notebook parameters out of the stream options", () => {+ const notebookParams = new URLSearchParams([+ ["types", "scatter"],+ ["cursor", "page-2"],+ ["run_id", "experiment"],+ ["query_params", "nested=value&other=1"],+ ["tag", "one"],+ ["tag", "two"],+ ["empty", ""],+ ["text", "a+b & café"],+ ["file", "test.py"],+ ["kiosk", "true"],+ ]);+ window.history.pushState(+ {},+ "",+ `/?${notebookParams}&session_id=page-session`,+ );+ const runtime = new RuntimeManager(+ { url: window.location.origin, lazy: true },+ true,+ );+ const url = runtime[method]("actual-session" as SessionId);++ expect(Object.fromEntries(url.searchParams)).toEqual({+ file: "test.py",+ kiosk: "true",+ session_id: "actual-session",+ query_params: notebookParams.toString(),+ });+ expect([+ ...new URLSearchParams(url.searchParams.get("query_params") ?? ""),+ ]).toEqual([...notebookParams]);+ });+ },+);diff --git a/frontend/src/core/runtime/__tests__/runtime.test.ts b/frontend/src/core/runtime/__tests__/runtime.test.tsindex 831d3537ed..061efd4bb2 100644--- a/frontend/src/core/runtime/__tests__/runtime.test.ts+++ b/frontend/src/core/runtime/__tests__/runtime.test.ts@@ -249,7 +249,8 @@ describe("RuntimeManager", () => {const url = runtime.getSseURL("s_123" as SessionId);expect(url.searchParams.get("access_token")).toBeNull();- expect(url.searchParams.get("foo")).toBe("bar");+ expect(url.searchParams.get("query_params")).toBe("foo=bar");+ expect(url.toString()).not.toContain("page-token");} finally {window.history.pushState({}, "", original);}@@ -669,9 +670,16 @@ describe("RuntimeManager", () => {expect(httpUrl.searchParams.get("base_param")).toBe("existing");// Should preserve all window-level query params (including custom ones)- expect(wsUrl.searchParams.get("custom_param")).toBe("value123");- expect(wsUrl.searchParams.get("user_token")).toBe("abc");- expect(wsUrl.searchParams.get("theme")).toBe("dark");+ expect(+ Object.fromEntries(+ new URLSearchParams(wsUrl.searchParams.get("query_params") ?? ""),+ ),+ ).toEqual({+ base_param: "existing",+ custom_param: "value123",+ user_token: "abc",+ theme: "dark",+ });expect(httpUrl.searchParams.get("custom_param")).toBe("value123");expect(httpUrl.searchParams.get("user_token")).toBe("abc");expect(httpUrl.searchParams.get("theme")).toBe("dark");@@ -738,7 +746,7 @@ describe("RuntimeManager", () => {const sessionId = "test" as SessionId;expect(runtime.getWsURL(sessionId).toString()).toMatchInlineSnapshot(- `"blob:https://example.com/12345678-1234-1234-1234-123456789abc?session_id=test"`,+ `"blob:https://example.com/12345678-1234-1234-1234-123456789abc?query_params=&session_id=test"`,);expect(Logger.warn).toHaveBeenCalledOnce();});diff --git a/frontend/src/core/runtime/runtime.ts b/frontend/src/core/runtime/runtime.tsindex a986960c11..cb155d4a19 100644--- a/frontend/src/core/runtime/runtime.ts+++ b/frontend/src/core/runtime/runtime.ts@@ -128,33 +128,32 @@ export class RuntimeManager {return asWsUrl(this.appendCrossOriginAuth(url).toString());}- /**- * Search params for a session connection: the base URL's params, merged- * with the current page's, plus the session id.- */- private getSessionSearchParams(sessionId: SessionId): URLSearchParams {- const baseUrl = new URL(this.config.url);- const searchParams = new URLSearchParams(baseUrl.search);-- // Merge in current page's query parameters- const currentParams = new URLSearchParams(window.location.search);- currentParams.forEach((value, key) => {- // Don't override base URL params- if (!searchParams.has(key)) {- searchParams.set(key, value);- }- });-- searchParams.set(KnownQueryParams.sessionId, sessionId);- return searchParams;+ /** Keep notebook page parameters separate from connection options. */+ private getSessionURL(path: string, sessionId: SessionId): URL {+ const url = this.formatHttpURL({ path });+ const notebookParams = new URLSearchParams(this.httpURL.search);+ const pageParams = new URLSearchParams(window.location.search);+ for (const key of pageParams.keys()) {+ notebookParams.delete(key);+ }+ for (const [key, value] of pageParams) {+ notebookParams.append(key, value);+ }+ // These parameters are internal and are not exposed by mo.query_params().+ notebookParams.delete(KnownQueryParams.accessToken);+ notebookParams.delete("refresh_token");+ notebookParams.delete(KnownQueryParams.sessionId);+ url.searchParams.set("query_params", notebookParams.toString());+ url.searchParams.set(KnownQueryParams.sessionId, sessionId);+ return url;}/*** The WebSocket URL of the runtime.*/public getWsURL(sessionId: SessionId): URL {- const searchParams = this.getSessionSearchParams(sessionId);- return this.formatWsURL("/ws", searchParams);+ const url = this.getSessionURL("/ws", sessionId);+ return asWsUrl(this.appendCrossOriginAuth(url).toString());}/**@@ -164,11 +163,7 @@ export class RuntimeManager {* (see `headers()`) instead of the URL.*/public getSseURL(sessionId: SessionId): URL {- const url = this.formatHttpURL({- path: "/sse",- searchParams: this.getSessionSearchParams(sessionId),- restrictToKnownQueryParams: false,- });+ const url = this.getSessionURL("/sse", sessionId);// The page URL can still carry access_token (merged in from the// current page's params, before auth cleanup strips it); never// forward it — a token in the URL leaks into proxy/server logs.@@ -180,7 +175,8 @@ export class RuntimeManager {* The WebSocket Sync URL of the runtime, for real-time updates.*/public getWsSyncURL(sessionId: SessionId): URL {- return this.formatWsURL("/ws_sync", this.getSessionSearchParams(sessionId));+ const url = this.getSessionURL("/ws_sync", sessionId);+ return asWsUrl(this.appendCrossOriginAuth(url).toString());}/**diff --git a/marimo/_runtime/params.py b/marimo/_runtime/params.pyindex 50be6cf658..ede8c5fecf 100644--- a/marimo/_runtime/params.py+++ b/marimo/_runtime/params.py@@ -37,8 +37,6 @@ class QueryParams(State[SerializedQueryParams]):"access_token","refresh_token","session_id",- "cursor",- "types",}def __init__(diff --git a/marimo/_server/api/endpoints/ws/ws_session_connector.py b/marimo/_server/api/endpoints/ws/ws_session_connector.pyindex 62bbba174b..5e98900375 100644--- a/marimo/_server/api/endpoints/ws/ws_session_connector.py+++ b/marimo/_server/api/endpoints/ws/ws_session_connector.py@@ -16,6 +16,7 @@ if TYPE_CHECKING:from marimo._server.session_manager import SessionManagerfrom marimo._session import Session+from starlette.datastructures import QueryParams as StarletteQueryParamsfrom starlette.websockets import WebSocketDisconnectfrom marimo import _loggers@@ -243,9 +244,12 @@ class SessionConnector:return new_session, ConnectionType.NEWdef _extract_query_params(self) -> QueryParams:- """Extract query params from the connection, filtering ignored keys."""+ """Read notebook parameters independently of stream options."""+ params = StarletteQueryParams(+ self.connection.query_params.get("query_params", "")+ )query_params = QueryParams({}, NoopStream())- for key, value in self.connection.query_params.multi_items():+ for key, value in params.multi_items():if key not in QueryParams.IGNORED_KEYS:query_params.append(key, value)return query_paramsdiff --git a/protocols/host/README.md b/protocols/host/README.mdindex 83d7c44591..8941edfa27 100644--- a/protocols/host/README.md+++ b/protocols/host/README.md@@ -19,12 +19,18 @@ The composed schema is the source of truth for the Python types in`packages/client/src/protocol.ts`. The frontend defines the native`marimo` extension event itself, with an `unknown` payload.-The editor consumes host events over WebSockets-when its runtime configuration includes a `notebookId`. With-`server.transport = "sse"`, it continues using the legacy `/sse` session-stream, even when a notebook ID is available. The host's SSE endpoint serves-protocol consumers but does not establish the editor session; editor support-requires that session integration as well as host event framing.+The editor consumes host events through the `/ws` and `/sse` session routes,+which establish the editor session before streaming events. Connection options+such as `session_id`, `types`, and `cursor` are top-level URL parameters.+The host notebook event endpoint also accepts `run_id`; session routes reject+that filter.+Notebook page parameters are forwarded as a URL-encoded query string in the+`query_params` parameter. For example, a notebook's `?types=scatter&tag=a&tag=b`+becomes `query_params=types%3Dscatter%26tag%3Da%26tag%3Db` on the connection URL;+it does not change the stream's `types` filter, and repeated values are preserved.++Missing or empty `query_params` supplies no notebook parameters. Top-level+connection parameters are never exposed as notebook parameters.Generate and check the Python bindings from the repository root:diff --git a/tests/_server/api/endpoints/test_sse.py b/tests/_server/api/endpoints/test_sse.pyindex f9e2923f1a..e0c0819293 100644--- a/tests/_server/api/endpoints/test_sse.py+++ b/tests/_server/api/endpoints/test_sse.py@@ -32,6 +32,7 @@ from marimo._session.managers.ipc import KernelStartupErrorfrom marimo._session.model import ConnectionState, SessionModefrom marimo._types.ids import SessionIdfrom tests._server.api.endpoints.ws_helpers import (+ QUERY_PARAMS_CASES,assert_kernel_ready_response,create_response,)@@ -199,6 +200,18 @@ async def test_sse_kernel_ready(client: TestClient) -> None:assert_kernel_ready_response(message)[email protected](("query", "expected"), QUERY_PARAMS_CASES)+async def test_sse_query_params(+ client: TestClient, query: str, expected: dict[str, str | list[str]]+) -> None:+ async with _connect(client, f"{SSE_QUERY}&{query}") as connection:+ event = await connection.next_notification()+ assert_kernel_ready_response(json.loads(event["data"]))+ session = get_session_manager(client).get_session("123")+ assert session is not None+ assert session._kernel_manager.app_metadata.query_params == expected++async def test_sse_requires_session_id(client: TestClient) -> None:async with _connect(client, "access_token=fake-token") as connection:await _expect_close(connection, 1000, "MARIMO_NO_SESSION_ID")diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.pyindex 86c47f3d1d..9cddf229c2 100644--- a/tests/_server/api/endpoints/test_ws.py+++ b/tests/_server/api/endpoints/test_ws.py@@ -31,6 +31,7 @@ from marimo._types.ids import SessionIdfrom marimo._utils.parse_dataclass import parse_rawfrom tests._server.api.endpoints.ws_helpers import (HEADERS,+ QUERY_PARAMS_CASES,assert_kernel_ready_response,assert_parse_ready_response,create_response,@@ -324,20 +325,17 @@ def test_file_watcher_calls_reload(client: TestClient) -> None:session_manager.watch = False-async def test_query_params(client: TestClient) -> None:- with client.websocket_connect(- f"{WS_URL}&foo=1&bar=2&bar=3&baz=4"- ) as websocket:[email protected](("query", "expected"), QUERY_PARAMS_CASES)+async def test_query_params(+ client: TestClient, query: str, expected: dict[str, str | list[str]]+) -> None:+ with client.websocket_connect(f"{WS_URL}&{query}") as websocket:data = receive_notification(websocket)assert_kernel_ready_response(data)session = get_session_manager(client).get_session("123")assert session- assert session._kernel_manager.app_metadata.query_params == {- "foo": "1",- "bar": ["2", "3"],- "baz": "4",- }+ assert session._kernel_manager.app_metadata.query_params == expectedasync def test_connect_kiosk_without_session(client: TestClient) -> None:diff --git a/tests/_server/api/endpoints/ws_helpers.py b/tests/_server/api/endpoints/ws_helpers.pyindex 8f77364064..7b59e4e618 100644--- a/tests/_server/api/endpoints/ws_helpers.py+++ b/tests/_server/api/endpoints/ws_helpers.py@@ -2,6 +2,7 @@from __future__ import annotationsfrom typing import TYPE_CHECKING, Any+from urllib.parse import urlencodefrom marimo._messaging.msgspec_encoder import asdictfrom marimo._messaging.notification import (@@ -103,3 +104,33 @@ def assert_kernel_ready_response(def assert_parse_ready_response(raw_data: dict[str, Any]) -> None:data = parse_raw(raw_data["data"], KernelReadyNotification)assert data is not None+++QUERY_PARAMS_CASES = [+ (+ urlencode({"query_params": "foo=1&bar=2&bar=3&baz=4"}),+ {"foo": "1", "bar": ["2", "3"], "baz": "4"},+ ),+ ("query_params=&foo=ignored", {}),+ (+ urlencode(+ {+ "query_params": "types=scatter&cursor=page-2&run_id=experiment"+ "&query_params=nested%3Dvalue%26other%3D1&tag=one&tag=two"+ "&empty=&text=a%2Bb+%26+caf%C3%A9"+ "&access_token=secret&refresh_token=secret&session_id=page-session"+ }+ )+ + "&types=marimo&foo=ignored",+ {+ "types": "scatter",+ "cursor": "page-2",+ "run_id": "experiment",+ "query_params": "nested=value&other=1",+ "tag": ["one", "two"],+ "empty": "",+ "text": "a+b & café",+ },+ ),+ ("types=marimo&cursor=expired&foo=1", {}),+]diff --git a/tests/_server/host/test_app_websocket.py b/tests/_server/host/test_app_websocket.pyindex a06119d6e5..ae15fb4f3e 100644--- a/tests/_server/host/test_app_websocket.py+++ b/tests/_server/host/test_app_websocket.py@@ -54,7 +54,9 @@ def test_app_executes_with_hidden_source_and_retained_hashes(client: TestClient, app_host: SessionBridge, include_code: bool) -> None:get_session_manager(client).include_code = include_code- with client.websocket_connect(url("alice") + "&color=blue") as ws:+ with client.websocket_connect(+ url("alice") + "&query_params=color%3Dblue"+ ) as ws:snapshot = socket_snapshot(ws)ready = receive_notification(ws, "kernel-ready")assert ready["auto_instantiated"] is True