fix: type-check browser-scoped helpers

Keep the browser-scoped request helpers aligned with repo linting and reserve internal raw-request query keys without exposing implementation details.

Made-with: Cursor

Author: rgarcia

src/kernel/lib/browser_scoped/client.py

@@ -133,10 +133,10 @@ def request(
             method=method.upper(),
             url="/curl/raw",
             params=q,
-            headers=headers if headers is not None else not_given,
-            content=content,
+            headers=_normalize_headers(headers),
+            content=_normalize_binary_content(content),
             json_data=json,
-            timeout=timeout,
+            timeout=_normalize_timeout(timeout),
         )
         return self._http.request(httpx.Response, opts)
 
@@ -165,8 +165,8 @@ def stream(
             self._http._prepare_url("/curl/raw"),
             params=q,
             headers=h,
-            content=content,
-            timeout=eff_timeout,
+            content=_normalize_binary_content(content),
+            timeout=_normalize_timeout(eff_timeout),
         )
         with cm as resp:
             yield resp
@@ -248,10 +248,10 @@ async def request(
             method=method.upper(),
             url="/curl/raw",
             params=q,
-            headers=headers if headers is not None else not_given,
-            content=content,
+            headers=_normalize_headers(headers),
+            content=_normalize_binary_content(content),
             json_data=json,
-            timeout=timeout,
+            timeout=_normalize_timeout(timeout),
         )
         return await self._http.request(httpx.Response, opts)
 
@@ -280,8 +280,8 @@ async def stream(
             self._http._prepare_url("/curl/raw"),
             params=q,
             headers=h,
-            content=content,
-            timeout=eff_timeout,
+            content=_normalize_binary_content(content),
+            timeout=_normalize_timeout(eff_timeout),
         ) as resp:
             yield resp
 
@@ -306,3 +306,21 @@ def async_browser_scoped_from_browser(parent: AsyncKernel, browser: Any) -> Asyn
     if not 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)
+
+
+def _normalize_headers(headers: Mapping[str, str] | None) -> Mapping[str, str]:
+    return headers if headers is not None else {}
+
+
+def _normalize_timeout(timeout: float | Timeout | None | NotGiven) -> float | Timeout | None:
+    return None if isinstance(timeout, NotGiven) else timeout
+
+
+def _normalize_binary_content(content: BinaryTypes | None) -> httpx._types.RequestContent | None:
+    if content is None:
+        return None
+    if isinstance(content, bytearray):
+        return bytes(content)
+    if isinstance(content, memoryview):
+        return content.tobytes()
+    return cast(httpx._types.RequestContent, content)

src/kernel/lib/browser_scoped/util.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Mapping
+from typing import Any, Mapping, cast
 from urllib.parse import parse_qs, urlparse
 
 # Query keys reserved for /curl/raw; user-supplied `params` must not override these.
@@ -27,7 +27,8 @@ def session_id_from_browser_like(browser: Any) -> str:
     if isinstance(sid, str) and sid:
         return sid
     if isinstance(browser, Mapping):
-        m = browser.get("session_id")
+        mapping = cast(Mapping[str, object], browser)
+        m = mapping.get("session_id")
         if isinstance(m, str) and m:
             return m
     raise TypeError("browser object must have a non-empty session_id")
@@ -38,7 +39,8 @@ def base_url_from_browser_like(browser: Any) -> str | None:
     if isinstance(bu, str) and bu.strip():
         return bu.strip().rstrip("/") + "/"
     if isinstance(browser, Mapping):
-        raw = browser.get("base_url")
+        mapping = cast(Mapping[str, object], browser)
+        raw = mapping.get("base_url")
         if isinstance(raw, str) and raw.strip():
             return raw.strip().rstrip("/") + "/"
     return None
@@ -49,7 +51,8 @@ def cdp_ws_url_from_browser_like(browser: Any) -> str:
     if isinstance(u, str) and u:
         return u
     if isinstance(browser, Mapping):
-        m = browser.get("cdp_ws_url")
+        mapping = cast(Mapping[str, object], browser)
+        m = mapping.get("cdp_ws_url")
         if isinstance(m, str) and m:
             return m
     raise TypeError("browser object must have a non-empty cdp_ws_url")

tests/test_browser_scoped.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-import os
 import json
+import os
+from typing import cast
 
 import httpx
 import respx
@@ -14,7 +15,7 @@
 api_key = "sk-123"
 
 
-def _fake_browser() -> dict[str, str]:
+def _fake_browser() -> dict[str, object]:
     return {
         "session_id": "sess-1",
         "base_url": "http://browser-session.test/browser/kernel",
@@ -47,7 +48,8 @@ def test_for_browser_process_exec_routes_to_session_base() -> None:
         b = client.for_browser(_fake_browser())
         out = b.process.exec(command="echo", args=["hi"])
     assert route.called
-    sent = route.calls[0].request.read().decode()
+    request = cast(httpx.Request, route.calls[0].request)
+    sent = request.read().decode()
     body = json.loads(sent)
     assert body["command"] == "echo"
     assert body["args"] == ["hi"]
@@ -65,8 +67,9 @@ def test_browser_request_uses_curl_raw() -> None:
     assert r.status_code == 200
     assert r.content == b"ok"
     assert route.called
-    assert "curl/raw" in str(route.calls[0].request.url)
-    assert "jwt=token-abc" in str(route.calls[0].request.url)
+    request = cast(httpx.Request, route.calls[0].request)
+    assert "curl/raw" in str(request.url)
+    assert "jwt=token-abc" in str(request.url)
 
 
 @respx.mock
@@ -82,7 +85,8 @@ def test_browser_request_params_cannot_override_target_url_or_jwt() -> None:
             params={"url": "https://evil.example", "jwt": "other", "timeout_ms": 1},
         )
     assert route.called
-    req_url = route.calls[0].request.url
+    request = cast(httpx.Request, route.calls[0].request)
+    req_url = request.url
     assert str(req_url.params.get("url")) == "https://example.com"
     assert str(req_url.params.get("jwt")) == "token-abc"
     assert str(req_url.params.get("timeout_ms")) == "1"
@@ -103,7 +107,8 @@ def test_browser_stream_params_cannot_override_target_url_or_jwt() -> None:
             assert resp.status_code == 200
             assert resp.read() == b"streamed"
     assert route.called
-    req_url = route.calls[0].request.url
+    request = cast(httpx.Request, route.calls[0].request)
+    req_url = request.url
     assert str(req_url.params.get("url")) == "https://example.com"
     assert str(req_url.params.get("jwt")) == "token-abc"