fix: reserve internal browser request query params

Prevent browser-scoped raw HTTP helpers from letting user params override internal routing query keys, and clean up wording around browser session base_url routing.

Made-with: Cursor

Author: rgarcia

examples/browser_scoped.py

@@ -1,4 +1,4 @@
-"""Example: browser-scoped client for metro-backed process and raw HTTP."""
+"""Example: browser-scoped client for browser VM process exec and raw HTTP."""
 
 from kernel import Kernel
 

…ernel/lib/browser_scoped/metro_client.py …browser_scoped/browser_session_kernel.pysrc/kernel/lib/browser_scoped/metro_client.py renamed to src/kernel/lib/browser_scoped/browser_session_kernel.py src/kernel/lib/browser_scoped/metro_client.py renamed to src/kernel/lib/browser_scoped/browser_session_kernel.py

@@ -1,4 +1,4 @@
-"""Internal HTTP clients that speak to metro-api /browser/kernel paths."""
+"""Internal Kernel clones for browser session HTTP (base_url + /browser/kernel paths)."""
 
 from __future__ import annotations
 
@@ -9,8 +9,8 @@
 from ..._models import FinalRequestOptions
 
 
-class _BrowserMetroKernel(Kernel):
-    """Kernel client clone whose requests hit metro base_url with /browsers/{id} stripped."""
+class _BrowserSessionKernel(Kernel):
+    """Kernel clone whose HTTP base is the browser session; strips /browsers/{id} from paths."""
 
     _scoped_session_id: str
 
@@ -33,7 +33,7 @@ def _prepare_options(self, options: FinalRequestOptions) -> FinalRequestOptions:
         return cast(FinalRequestOptions, out)
 
 
-class _BrowserMetroAsyncKernel(AsyncKernel):
+class _BrowserSessionAsyncKernel(AsyncKernel):
     _scoped_session_id: str
 
     def __init__(self, *, browser_session_id: str, **kwargs: Any) -> None:
@@ -55,15 +55,17 @@ async def _prepare_options(self, options: FinalRequestOptions) -> FinalRequestOp
         return cast(FinalRequestOptions, out)
 
 
-def metro_kernel_from_browser(parent: Kernel, *, session_id: str, metro_base_url: str, jwt: str) -> _BrowserMetroKernel:
-    """Build a sync metro-scoped client sharing the parent's httpx transport."""
+def build_browser_session_kernel(
+    parent: Kernel, *, session_id: str, session_base_url: str, jwt: str
+) -> _BrowserSessionKernel:
+    """Build a sync client sharing the parent's httpx transport; requests use session_base_url."""
     base_q = getattr(parent, "_custom_query", None) or {}
     dq = {str(k): v for k, v in dict(base_q).items()}
     dq["jwt"] = jwt
-    return _BrowserMetroKernel(
+    return _BrowserSessionKernel(
         browser_session_id=session_id,
         api_key=parent.api_key,
-        base_url=metro_base_url,
+        base_url=session_base_url,
         timeout=parent.timeout,
         max_retries=parent.max_retries,
         http_client=parent._client,
@@ -73,16 +75,16 @@ def metro_kernel_from_browser(parent: Kernel, *, session_id: str, metro_base_url
     )
 
 
-def metro_async_kernel_from_browser(
-    parent: AsyncKernel, *, session_id: str, metro_base_url: str, jwt: str
-) -> _BrowserMetroAsyncKernel:
+def build_async_browser_session_kernel(
+    parent: AsyncKernel, *, session_id: str, session_base_url: str, jwt: str
+) -> _BrowserSessionAsyncKernel:
     base_q = getattr(parent, "_custom_query", None) or {}
     dq = {str(k): v for k, v in dict(base_q).items()}
     dq["jwt"] = jwt
-    return _BrowserMetroAsyncKernel(
+    return _BrowserSessionAsyncKernel(
         browser_session_id=session_id,
         api_key=parent.api_key,
-        base_url=metro_base_url,
+        base_url=session_base_url,
         timeout=parent.timeout,
         max_retries=parent.max_retries,
         http_client=parent._client,

src/kernel/lib/browser_scoped/client.py

@@ -1,4 +1,4 @@
-"""Browser-scoped view over a session: metro-routed subresources and raw HTTP via /curl/raw."""
+"""Browser-scoped view over a session: VM subresources and raw HTTP via internal /curl/raw."""
 
 from __future__ import annotations
 
@@ -11,13 +11,14 @@
 
 from .util import (
     jwt_from_cdp_ws_url,
+    sanitize_curl_raw_params,
     base_url_from_browser_like,
     cdp_ws_url_from_browser_like,
     session_id_from_browser_like,
 )
 from ..._types import Body, Timeout, NotGiven, BinaryTypes, not_given
 from ..._models import FinalRequestOptions
-from .metro_client import metro_kernel_from_browser, metro_async_kernel_from_browser
+from .browser_session_kernel import build_browser_session_kernel, build_async_browser_session_kernel
 
 if TYPE_CHECKING:
     from ..._client import Kernel, AsyncKernel
@@ -60,12 +61,14 @@ def bound(*args: Any, **kwargs: Any) -> Any:
 class BrowserScopedClient:
     """Session-scoped API: subresources without repeating session id; HTTP via browser /curl/raw."""
 
-    def __init__(self, parent: Kernel, *, session_id: str, metro_base_url: str, jwt: str) -> None:
+    def __init__(self, parent: Kernel, *, session_id: str, session_base_url: str, jwt: str) -> None:
         self._parent = parent
         self.session_id = session_id
-        self._metro_base_url = metro_base_url
+        self._session_base_url = session_base_url
         self._jwt = jwt
-        self._metro = metro_kernel_from_browser(parent, session_id=session_id, metro_base_url=metro_base_url, jwt=jwt)
+        self._http = build_browser_session_kernel(
+            parent, session_id=session_id, session_base_url=session_base_url, jwt=jwt
+        )
 
     @property
     def parent(self) -> Kernel:
@@ -74,43 +77,43 @@ def parent(self) -> Kernel:
 
     @property
     def base_url(self) -> str:
-        return self._metro_base_url
+        return self._session_base_url
 
     @property
     def process(self) -> ProcessResource:
         from ...resources.browsers.process import ProcessResource
 
-        return cast(ProcessResource, _BoundBrowserSubresource(ProcessResource(self._metro), self.session_id))
+        return cast(ProcessResource, _BoundBrowserSubresource(ProcessResource(self._http), self.session_id))
 
     @property
     def computer(self) -> ComputerResource:
         from ...resources.browsers.computer import ComputerResource
 
-        return cast(ComputerResource, _BoundBrowserSubresource(ComputerResource(self._metro), self.session_id))
+        return cast(ComputerResource, _BoundBrowserSubresource(ComputerResource(self._http), self.session_id))
 
     @property
     def fs(self) -> FsResource:
         from ...resources.browsers.fs.fs import FsResource
 
-        return cast(FsResource, _BoundBrowserSubresource(FsResource(self._metro), self.session_id))
+        return cast(FsResource, _BoundBrowserSubresource(FsResource(self._http), self.session_id))
 
     @property
     def logs(self) -> LogsResource:
         from ...resources.browsers.logs import LogsResource
 
-        return cast(LogsResource, _BoundBrowserSubresource(LogsResource(self._metro), self.session_id))
+        return cast(LogsResource, _BoundBrowserSubresource(LogsResource(self._http), self.session_id))
 
     @property
     def playwright(self) -> PlaywrightResource:
         from ...resources.browsers.playwright import PlaywrightResource
 
-        return cast(PlaywrightResource, _BoundBrowserSubresource(PlaywrightResource(self._metro), self.session_id))
+        return cast(PlaywrightResource, _BoundBrowserSubresource(PlaywrightResource(self._http), self.session_id))
 
     @property
     def replays(self) -> ReplaysResource:
         from ...resources.browsers.replays import ReplaysResource
 
-        return cast(ReplaysResource, _BoundBrowserSubresource(ReplaysResource(self._metro), self.session_id))
+        return cast(ReplaysResource, _BoundBrowserSubresource(ReplaysResource(self._http), self.session_id))
 
     def request(
         self,
@@ -125,9 +128,7 @@ def request(
     ) -> httpx.Response:
         if json is not None and content is not None:
             raise TypeError("Passing both `json` and `content` is not supported")
-        q: dict[str, object] = {"url": url}
-        if params:
-            q.update(dict(params))
+        q: dict[str, object] = {**sanitize_curl_raw_params(params), "url": url}
         opts = FinalRequestOptions.construct(
             method=method.upper(),
             url="/curl/raw",
@@ -137,7 +138,7 @@ def request(
             json_data=json,
             timeout=timeout,
         )
-        return self._metro.request(httpx.Response, opts)
+        return self._http.request(httpx.Response, opts)
 
     @contextmanager
     def stream(
@@ -150,19 +151,18 @@ def stream(
         params: Mapping[str, object] | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
     ) -> Iterator[httpx.Response]:
-        q: dict[str, Any] = dict(self._metro.default_query)
+        q: dict[str, Any] = dict(self._http.default_query)
+        q.update(sanitize_curl_raw_params(params))
         q["url"] = url
-        if params:
-            q.update(dict(params))
-        h = {k: v for k, v in self._metro.default_headers.items() if isinstance(v, str)}
+        h = {k: v for k, v in self._http.default_headers.items() if isinstance(v, str)}
         if content is None:
             h.pop("Content-Type", None)
         if headers:
             h.update(headers)
-        eff_timeout = self._metro.timeout if isinstance(timeout, NotGiven) else timeout
-        cm = self._metro._client.stream(
+        eff_timeout = self._http.timeout if isinstance(timeout, NotGiven) else timeout
+        cm = self._http._client.stream(
             method.upper(),
-            self._metro._prepare_url("/curl/raw"),
+            self._http._prepare_url("/curl/raw"),
             params=q,
             headers=h,
             content=content,
@@ -173,13 +173,13 @@ def stream(
 
 
 class AsyncBrowserScopedClient:
-    def __init__(self, parent: AsyncKernel, *, session_id: str, metro_base_url: str, jwt: str) -> None:
+    def __init__(self, parent: AsyncKernel, *, session_id: str, session_base_url: str, jwt: str) -> None:
         self._parent = parent
         self.session_id = session_id
-        self._metro_base_url = metro_base_url
+        self._session_base_url = session_base_url
         self._jwt = jwt
-        self._metro = metro_async_kernel_from_browser(
-            parent, session_id=session_id, metro_base_url=metro_base_url, jwt=jwt
+        self._http = build_async_browser_session_kernel(
+            parent, session_id=session_id, session_base_url=session_base_url, jwt=jwt
         )
 
     @property
@@ -188,47 +188,47 @@ def parent(self) -> AsyncKernel:
 
     @property
     def base_url(self) -> str:
-        return self._metro_base_url
+        return self._session_base_url
 
     @property
     def process(self) -> AsyncProcessResource:
         from ...resources.browsers.process import AsyncProcessResource
 
-        return cast(AsyncProcessResource, _BoundBrowserSubresource(AsyncProcessResource(self._metro), self.session_id))
+        return cast(AsyncProcessResource, _BoundBrowserSubresource(AsyncProcessResource(self._http), self.session_id))
 
     @property
     def computer(self) -> AsyncComputerResource:
         from ...resources.browsers.computer import AsyncComputerResource
 
         return cast(
-            AsyncComputerResource, _BoundBrowserSubresource(AsyncComputerResource(self._metro), self.session_id)
+            AsyncComputerResource, _BoundBrowserSubresource(AsyncComputerResource(self._http), self.session_id)
         )
 
     @property
     def fs(self) -> AsyncFsResource:
         from ...resources.browsers.fs.fs import AsyncFsResource
 
-        return cast(AsyncFsResource, _BoundBrowserSubresource(AsyncFsResource(self._metro), self.session_id))
+        return cast(AsyncFsResource, _BoundBrowserSubresource(AsyncFsResource(self._http), self.session_id))
 
     @property
     def logs(self) -> AsyncLogsResource:
         from ...resources.browsers.logs import AsyncLogsResource
 
-        return cast(AsyncLogsResource, _BoundBrowserSubresource(AsyncLogsResource(self._metro), self.session_id))
+        return cast(AsyncLogsResource, _BoundBrowserSubresource(AsyncLogsResource(self._http), self.session_id))
 
     @property
     def playwright(self) -> AsyncPlaywrightResource:
         from ...resources.browsers.playwright import AsyncPlaywrightResource
 
         return cast(
-            AsyncPlaywrightResource, _BoundBrowserSubresource(AsyncPlaywrightResource(self._metro), self.session_id)
+            AsyncPlaywrightResource, _BoundBrowserSubresource(AsyncPlaywrightResource(self._http), self.session_id)
         )
 
     @property
     def replays(self) -> AsyncReplaysResource:
         from ...resources.browsers.replays import AsyncReplaysResource
 
-        return cast(AsyncReplaysResource, _BoundBrowserSubresource(AsyncReplaysResource(self._metro), self.session_id))
+        return cast(AsyncReplaysResource, _BoundBrowserSubresource(AsyncReplaysResource(self._http), self.session_id))
 
     async def request(
         self,
@@ -243,9 +243,7 @@ async def request(
     ) -> httpx.Response:
         if json is not None and content is not None:
             raise TypeError("Passing both `json` and `content` is not supported")
-        q: dict[str, object] = {"url": url}
-        if params:
-            q.update(dict(params))
+        q: dict[str, object] = {**sanitize_curl_raw_params(params), "url": url}
         opts = FinalRequestOptions.construct(
             method=method.upper(),
             url="/curl/raw",
@@ -255,7 +253,7 @@ async def request(
             json_data=json,
             timeout=timeout,
         )
-        return await self._metro.request(httpx.Response, opts)
+        return await self._http.request(httpx.Response, opts)
 
     @asynccontextmanager
     async def stream(
@@ -268,19 +266,18 @@ async def stream(
         params: Mapping[str, object] | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
     ) -> AsyncIterator[httpx.Response]:
-        q: dict[str, Any] = dict(self._metro.default_query)
+        q: dict[str, Any] = dict(self._http.default_query)
+        q.update(sanitize_curl_raw_params(params))
         q["url"] = url
-        if params:
-            q.update(dict(params))
-        h = {k: v for k, v in self._metro.default_headers.items() if isinstance(v, str)}
+        h = {k: v for k, v in self._http.default_headers.items() if isinstance(v, str)}
         if content is None:
             h.pop("Content-Type", None)
         if headers:
             h.update(headers)
-        eff_timeout = self._metro.timeout if isinstance(timeout, NotGiven) else timeout
-        async with self._metro._client.stream(
+        eff_timeout = self._http.timeout if isinstance(timeout, NotGiven) else timeout
+        async with self._http._client.stream(
             method.upper(),
-            self._metro._prepare_url("/curl/raw"),
+            self._http._prepare_url("/curl/raw"),
             params=q,
             headers=h,
             content=content,
@@ -291,21 +288,21 @@ async def stream(
 
 def browser_scoped_from_browser(parent: Kernel, browser: Any) -> BrowserScopedClient:
     session_id = session_id_from_browser_like(browser)
-    metro = base_url_from_browser_like(browser)
-    if not metro:
+    session_base = base_url_from_browser_like(browser)
+    if not session_base:
         raise ValueError("browser.base_url is required for a browser-scoped client")
     jwt = jwt_from_cdp_ws_url(cdp_ws_url_from_browser_like(browser))
     if not jwt:
-        raise ValueError("could not parse jwt from browser.cdp_ws_url; required for metro requests")
-    return BrowserScopedClient(parent, session_id=session_id, metro_base_url=metro, jwt=jwt)
+        raise ValueError("could not parse jwt from browser.cdp_ws_url; required for browser session HTTP")
+    return BrowserScopedClient(parent, session_id=session_id, session_base_url=session_base, jwt=jwt)
 
 
 def async_browser_scoped_from_browser(parent: AsyncKernel, browser: Any) -> AsyncBrowserScopedClient:
     session_id = session_id_from_browser_like(browser)
-    metro = base_url_from_browser_like(browser)
-    if not metro:
+    session_base = base_url_from_browser_like(browser)
+    if not session_base:
         raise ValueError("browser.base_url is required for a browser-scoped client")
     jwt = jwt_from_cdp_ws_url(cdp_ws_url_from_browser_like(browser))
     if not jwt:
-        raise ValueError("could not parse jwt from browser.cdp_ws_url; required for metro requests")
-    return AsyncBrowserScopedClient(parent, session_id=session_id, metro_base_url=metro, jwt=jwt)
+        raise ValueError("could not parse jwt from browser.cdp_ws_url; required for browser session HTTP")
+    return AsyncBrowserScopedClient(parent, session_id=session_id, session_base_url=session_base, jwt=jwt)

src/kernel/lib/browser_scoped/util.py

@@ -3,6 +3,16 @@
 from typing import Any, Mapping
 from urllib.parse import parse_qs, urlparse
 
+# Query keys reserved for /curl/raw; user-supplied `params` must not override these.
+CURL_RAW_RESERVED_QUERY_KEYS: frozenset[str] = frozenset({"url", "jwt"})
+
+
+def sanitize_curl_raw_params(params: Mapping[str, object] | None) -> dict[str, object]:
+    """Drop reserved keys from user params so they cannot override the target URL or auth."""
+    if not params:
+        return {}
+    return {k: v for k, v in dict(params).items() if k not in CURL_RAW_RESERVED_QUERY_KEYS}
+
 
 def jwt_from_cdp_ws_url(cdp_ws_url: str) -> str | None:
     parsed = urlparse(cdp_ws_url)

src/kernel/types/browser_create_response.py

@@ -36,7 +36,7 @@ class BrowserCreateResponse(BaseModel):
     """Websocket URL for WebDriver BiDi connections to the browser session"""
 
     base_url: Optional[str] = None
-    """Metro-API HTTP base URL for this browser session."""
+    """HTTP base URL for this browser session (browser VM / session proxy)."""
 
     browser_live_view_url: Optional[str] = None
     """Remote URL for live viewing the browser session.

src/kernel/types/browser_list_response.py

@@ -36,7 +36,7 @@ class BrowserListResponse(BaseModel):
     """Websocket URL for WebDriver BiDi connections to the browser session"""
 
     base_url: Optional[str] = None
-    """Metro-API HTTP base URL for this browser session."""
+    """HTTP base URL for this browser session (browser VM / session proxy)."""
 
     browser_live_view_url: Optional[str] = None
     """Remote URL for live viewing the browser session.