refactor: simplify browser routing cache

Remove the public cache priming helpers, keep jwt-required routes, and rename the example and tests so the python browser routing diff stays focused on cache-backed direct-to-VM behavior.

Made-with: Cursor

Author: rgarcia

examples/browser_scoped.py examples/browser_routing.pyexamples/browser_scoped.py renamed to examples/browser_routing.py

@@ -7,8 +7,6 @@ def main() -> None:
     with Kernel(browser_routing=BrowserRoutingConfig(enabled=True, direct_to_vm_subresources=("process",))) as client:
         browser = client.browsers.create(headless=True)
         try:
-            client.prime_browser_route_cache(browser)
-
             client.browsers.process.exec(browser.session_id, command="uname", args=["-a"])
 
             response = client.browsers.request(browser.session_id, "GET", "https://example.com")

src/kernel/_client.py

@@ -343,9 +343,6 @@ def copy(
     # client.with_options(timeout=10).foo.create(...)
     with_options = copy
 
-    def prime_browser_route_cache(self, browser: Any) -> None:
-        self.browser_route_cache.prime(browser)
-
     @override
     def _make_status_error(
         self,
@@ -640,9 +637,6 @@ def copy(
     # client.with_options(timeout=10).foo.create(...)
     with_options = copy
 
-    def prime_browser_route_cache(self, browser: Any) -> None:
-        self.browser_route_cache.prime(browser)
-
     @override
     def _make_status_error(
         self,

src/kernel/lib/browser_scoped/raw_http.py

@@ -27,8 +27,7 @@ def request_via_browser_route(
     if json is not None and content is not None:
         raise TypeError("Passing both `json` and `content` is not supported")
     q: dict[str, object] = {**sanitize_curl_raw_params(params), "url": url}
-    if route.jwt:
-        q["jwt"] = route.jwt
+    q["jwt"] = route.jwt
     opts = FinalRequestOptions.construct(
         method=method.upper(),
         url=route.base_url.rstrip("/") + "/curl/raw",
@@ -54,8 +53,7 @@ def stream_via_browser_route(
     timeout: float | Timeout | None | NotGiven = not_given,
 ) -> Iterator[httpx.Response]:
     q: dict[str, Any] = sanitize_curl_raw_params(params)
-    if route.jwt:
-        q["jwt"] = route.jwt
+    q["jwt"] = route.jwt
     q["url"] = url
     h = {k: v for k, v in parent.default_headers.items() if isinstance(v, str)}
     if content is None:
@@ -90,8 +88,7 @@ async def async_request_via_browser_route(
     if json is not None and content is not None:
         raise TypeError("Passing both `json` and `content` is not supported")
     q: dict[str, object] = {**sanitize_curl_raw_params(params), "url": url}
-    if route.jwt:
-        q["jwt"] = route.jwt
+    q["jwt"] = route.jwt
     opts = FinalRequestOptions.construct(
         method=method.upper(),
         url=route.base_url.rstrip("/") + "/curl/raw",
@@ -117,8 +114,7 @@ async def async_stream_via_browser_route(
     timeout: float | Timeout | None | NotGiven = not_given,
 ) -> AsyncIterator[httpx.Response]:
     q: dict[str, Any] = sanitize_curl_raw_params(params)
-    if route.jwt:
-        q["jwt"] = route.jwt
+    q["jwt"] = route.jwt
     q["url"] = url
     h = {k: v for k, v in parent.default_headers.items() if isinstance(v, str)}
     if content is None:

src/kernel/lib/browser_scoped/routing.py

@@ -7,15 +7,14 @@
 
 from ..._compat import model_copy
 from ..._models import FinalRequestOptions
-from ..._types import Headers
 from .util import base_url_from_browser_like, jwt_from_cdp_ws_url, cdp_ws_url_from_browser_like, session_id_from_browser_like
 
 
 @dataclass
 class BrowserRoute:
     session_id: str
     base_url: str
-    jwt: str | None = None
+    jwt: str
 
 
 @dataclass
@@ -35,30 +34,33 @@ def set(self, route: BrowserRoute) -> None:
         self._routes[route.session_id] = BrowserRoute(
             session_id=route.session_id.strip(),
             base_url=route.base_url.strip().rstrip("/") + "/",
-            jwt=route.jwt.strip() if isinstance(route.jwt, str) and route.jwt.strip() else None,
+            jwt=route.jwt.strip(),
         )
 
     def delete(self, session_id: str) -> None:
         self._routes.pop(session_id, None)
 
-    def prime(self, browser: Any) -> BrowserRoute:
-        session_id = session_id_from_browser_like(browser)
-        base_url = base_url_from_browser_like(browser)
-        if not base_url:
-            raise ValueError("browser.base_url is required to prime the browser route cache")
-        jwt = None
-        try:
-            jwt = jwt_from_cdp_ws_url(cdp_ws_url_from_browser_like(browser))
-        except Exception:
-            jwt = None
-        route = BrowserRoute(session_id=session_id, base_url=base_url, jwt=jwt)
-        self.set(route)
-        return route
-
     def values(self) -> list[BrowserRoute]:
         return list(self._routes.values())
 
 
+def browser_route_from_browser(browser: Any) -> BrowserRoute | None:
+    session_id = session_id_from_browser_like(browser)
+    base_url = base_url_from_browser_like(browser)
+    if not base_url:
+        return None
+
+    jwt = None
+    try:
+        jwt = jwt_from_cdp_ws_url(cdp_ws_url_from_browser_like(browser))
+    except Exception:
+        jwt = None
+    if not jwt:
+        return None
+
+    return BrowserRoute(session_id=session_id, base_url=base_url, jwt=jwt)
+
+
 def rewrite_direct_vm_options(
     options: FinalRequestOptions,
     *,
@@ -86,8 +88,7 @@ def rewrite_direct_vm_options(
     params: dict[str, object] = {}
     if isinstance(options.params, Mapping):
         params.update(cast(Mapping[str, object], options.params))
-    if route.jwt:
-        params["jwt"] = route.jwt
+    params["jwt"] = route.jwt
     rewritten.params = params or options.params
     return rewritten
 
@@ -119,9 +120,3 @@ def match_direct_vm_path(path: str) -> tuple[str, str, str] | None:
     return None
 
 
-def build_direct_vm_headers(headers: Mapping[str, str] | None) -> Headers | None:
-    if headers is None:
-        return {"Authorization": None}
-    out: dict[str, str | None] = {"Authorization": None}
-    out.update(headers)
-    return out

src/kernel/lib/browser_scoped/util.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import inspect
 from typing import Any, Mapping, cast
 from urllib.parse import parse_qs, urlparse
 
@@ -59,29 +58,3 @@ def cdp_ws_url_from_browser_like(browser: Any) -> str:
     raise TypeError("browser object must have a non-empty cdp_ws_url")
 
 
-class ScopedResourceProxy:
-    """Delegates to a generated resource; injects `id` for callables that still expose it."""
-
-    def __init__(self, inner: Any, session_id: str) -> None:
-        object.__setattr__(self, "_inner", inner)
-        object.__setattr__(self, "_session_id", session_id)
-
-    def __getattr__(self, name: str) -> Any:
-        if name.startswith("_"):
-            raise AttributeError(name)
-        attr = getattr(self._inner, name)
-        if name.startswith("with_") or not callable(attr):
-            return attr
-        try:
-            sig = inspect.signature(attr)
-        except (TypeError, ValueError):
-            return attr
-        if "id" not in sig.parameters:
-            return attr
-
-        def bound(*args: Any, **kwargs: Any) -> Any:
-            kw = dict(kwargs)
-            kw["id"] = self._session_id
-            return attr(*args, **kw)
-
-        return bound

src/kernel/resources/browsers/browsers.py

@@ -94,6 +94,7 @@
     request_via_browser_route,
     stream_via_browser_route,
 )
+from ...lib.browser_scoped.routing import browser_route_from_browser
 
 __all__ = ["BrowsersResource", "AsyncBrowsersResource"]
 
@@ -249,7 +250,9 @@ def create(
             ),
             cast_to=BrowserCreateResponse,
         )
-        self._client.prime_browser_route_cache(result)
+        route = browser_route_from_browser(result)
+        if route is not None:
+            self._client.browser_route_cache.set(route)
         return result
 
     def retrieve(
@@ -293,7 +296,9 @@ def retrieve(
             ),
             cast_to=BrowserRetrieveResponse,
         )
-        self._client.prime_browser_route_cache(result)
+        route = browser_route_from_browser(result)
+        if route is not None:
+            self._client.browser_route_cache.set(route)
         return result
 
     def update(
@@ -352,7 +357,9 @@ def update(
             ),
             cast_to=BrowserUpdateResponse,
         )
-        self._client.prime_browser_route_cache(result)
+        route = browser_route_from_browser(result)
+        if route is not None:
+            self._client.browser_route_cache.set(route)
         return result
 
     def list(
@@ -418,7 +425,9 @@ def list(
             model=BrowserListResponse,
         )
         for item in page.items:
-            self._client.prime_browser_route_cache(item)
+            route = browser_route_from_browser(item)
+            if route is not None:
+                self._client.browser_route_cache.set(route)
         return page
 
     @typing_extensions.deprecated("deprecated")
@@ -816,7 +825,9 @@ async def create(
             ),
             cast_to=BrowserCreateResponse,
         )
-        self._client.prime_browser_route_cache(result)
+        route = browser_route_from_browser(result)
+        if route is not None:
+            self._client.browser_route_cache.set(route)
         return result
 
     async def retrieve(
@@ -860,7 +871,9 @@ async def retrieve(
             ),
             cast_to=BrowserRetrieveResponse,
         )
-        self._client.prime_browser_route_cache(result)
+        route = browser_route_from_browser(result)
+        if route is not None:
+            self._client.browser_route_cache.set(route)
         return result
 
     async def update(
@@ -919,7 +932,9 @@ async def update(
             ),
             cast_to=BrowserUpdateResponse,
         )
-        self._client.prime_browser_route_cache(result)
+        route = browser_route_from_browser(result)
+        if route is not None:
+            self._client.browser_route_cache.set(route)
         return result
 
     def list(