Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

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.ts
index 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.ts
index 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.ts
index 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.py
index 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.py
index 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 SessionManager
from marimo._session import Session
+from starlette.datastructures import QueryParams as StarletteQueryParams
from starlette.websockets import WebSocketDisconnect
from marimo import _loggers
@@ -243,9 +244,12 @@ class SessionConnector:
return new_session, ConnectionType.NEW
def _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_params
diff --git a/protocols/host/README.md b/protocols/host/README.md
index 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.py
index 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 KernelStartupError
from marimo._session.model import ConnectionState, SessionMode
from marimo._types.ids import SessionId
from 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.py
index 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 SessionId
from marimo._utils.parse_dataclass import parse_raw
from 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 == expected
async 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.py
index 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 annotations
from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode
from marimo._messaging.msgspec_encoder import asdict
from 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.py
index 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