refactor: sniff browser routes in response hooks

Move browser route cache warming into the shared sync and async response hooks so browser metadata endpoints populate the cache consistently, including raw responses. Remove the handwritten browsers resource priming and cover the narrowed sniffing behavior with focused routing tests.

Made-with: Cursor

Author: rgarcia

src/kernel/_client.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import os
-from typing import TYPE_CHECKING, Any, Dict, Mapping, cast
+from typing import TYPE_CHECKING, Any, Dict, Type, Mapping, cast
 from typing_extensions import Self, Literal, override
 
 import httpx
@@ -14,13 +14,15 @@
     Omit,
     Timeout,
     NotGiven,
+    ResponseT,
     Transport,
     ProxiesTypes,
     RequestOptions,
     not_given,
 )
 from ._utils import is_given, get_async_library
 from ._compat import cached_property
+from ._models import FinalRequestOptions
 from ._version import __version__
 from ._streaming import Stream as Stream, AsyncStream as AsyncStream
 from ._exceptions import KernelError, APIStatusError
@@ -35,6 +37,7 @@
     strip_direct_vm_auth,
     rewrite_direct_vm_options,
     browser_routing_config_from_env,
+    maybe_populate_browser_route_cache_from_response,
 )
 
 if TYPE_CHECKING:
@@ -287,6 +290,27 @@ def _prepare_options(self, options: Any) -> Any:
     def _prepare_request(self, request: httpx.Request) -> None:
         strip_direct_vm_auth(request, cache=self.browser_route_cache)
 
+    @override
+    def _process_response(
+        self,
+        *,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        response: httpx.Response,
+        stream: bool,
+        stream_cls: type[Stream[Any]] | type[AsyncStream[Any]] | None,
+        retries_taken: int = 0,
+    ) -> ResponseT:
+        maybe_populate_browser_route_cache_from_response(response, cache=self.browser_route_cache)
+        return super()._process_response(
+            cast_to=cast_to,
+            options=options,
+            response=response,
+            stream=stream,
+            stream_cls=stream_cls,
+            retries_taken=retries_taken,
+        )
+
     def copy(
         self,
         *,
@@ -580,6 +604,27 @@ async def _prepare_options(self, options: Any) -> Any:
     async def _prepare_request(self, request: httpx.Request) -> None:
         strip_direct_vm_auth(request, cache=self.browser_route_cache)
 
+    @override
+    async def _process_response(
+        self,
+        *,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        response: httpx.Response,
+        stream: bool,
+        stream_cls: type[Stream[Any]] | type[AsyncStream[Any]] | None,
+        retries_taken: int = 0,
+    ) -> ResponseT:
+        maybe_populate_browser_route_cache_from_response(response, cache=self.browser_route_cache)
+        return await super()._process_response(
+            cast_to=cast_to,
+            options=options,
+            response=response,
+            stream=stream,
+            stream_cls=stream_cls,
+            retries_taken=retries_taken,
+        )
+
     def copy(
         self,
         *,

src/kernel/lib/browser_routing/routing.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 import os
-from typing import Any
+import re
+from typing import Any, Mapping, cast
 from dataclasses import field, dataclass
 
 import httpx
@@ -14,6 +15,7 @@
 )
 from ..._compat import model_copy
 from ..._models import FinalRequestOptions
+from ..._constants import RAW_RESPONSE_HEADER
 
 
 @dataclass
@@ -28,6 +30,9 @@ class BrowserRoutingConfig:
     subresources: tuple[str, ...] = field(default_factory=tuple)
 
 
+_BROWSER_ROUTE_CACHEABLE_PATH = re.compile(r"^/(?:v\d+/)?browsers(?:/[^/]+)?/?$")
+
+
 def browser_routing_config_from_env() -> BrowserRoutingConfig:
     raw = os.environ.get("KERNEL_BROWSER_ROUTING_SUBRESOURCES")
     if raw is None:
@@ -85,6 +90,44 @@ def _normalize_session_id(session_id: str) -> str:
     return session_id.strip()
 
 
+def maybe_populate_browser_route_cache_from_response(response: httpx.Response, *, cache: BrowserRouteCache) -> None:
+    if not _should_populate_browser_route_cache(response):
+        return
+
+    try:
+        populate_browser_route_cache_from_value(response.json(), cache=cache)
+    except Exception:
+        # Ignore malformed JSON in routing cache population.
+        return
+
+
+def populate_browser_route_cache_from_value(value: object, *, cache: BrowserRouteCache) -> None:
+    if isinstance(value, Mapping):
+        mapping = cast(Mapping[object, object], value)
+        route = browser_route_from_browser(mapping)
+        if route is not None:
+            cache.set(route)
+
+        for child in mapping.values():
+            populate_browser_route_cache_from_value(child, cache=cache)
+        return
+
+    if isinstance(value, list):
+        for item in cast(list[object], value):
+            populate_browser_route_cache_from_value(item, cache=cache)
+
+
+def _should_populate_browser_route_cache(response: httpx.Response) -> bool:
+    if response.request.headers.get(RAW_RESPONSE_HEADER) == "stream":
+        return False
+
+    content_type = response.headers.get("content-type", "").lower()
+    if "application/json" not in content_type:
+        return False
+
+    return bool(_BROWSER_ROUTE_CACHEABLE_PATH.match(response.request.url.path))
+
+
 def rewrite_direct_vm_options(
     options: FinalRequestOptions,
     *,

src/kernel/resources/browsers/browsers.py

@@ -79,7 +79,6 @@
 )
 from ...pagination import SyncOffsetPagination, AsyncOffsetPagination
 from ..._base_client import AsyncPaginator, make_request_options
-from ...lib.browser_routing.routing import browser_route_from_browser
 from ...types.browser_curl_response import BrowserCurlResponse
 from ...types.browser_list_response import BrowserListResponse
 from ...lib.browser_routing.raw_http import (
@@ -250,9 +249,6 @@ def create(
             ),
             cast_to=BrowserCreateResponse,
         )
-        route = browser_route_from_browser(result)
-        if route is not None:
-            self._client.browser_route_cache.set(route)
         return result
 
     def retrieve(
@@ -296,9 +292,6 @@ def retrieve(
             ),
             cast_to=BrowserRetrieveResponse,
         )
-        route = browser_route_from_browser(result)
-        if route is not None:
-            self._client.browser_route_cache.set(route)
         return result
 
     def update(
@@ -357,9 +350,6 @@ def update(
             ),
             cast_to=BrowserUpdateResponse,
         )
-        route = browser_route_from_browser(result)
-        if route is not None:
-            self._client.browser_route_cache.set(route)
         return result
 
     def list(
@@ -424,10 +414,6 @@ def list(
             ),
             model=BrowserListResponse,
         )
-        for item in page.items:
-            route = browser_route_from_browser(item)
-            if route is not None:
-                self._client.browser_route_cache.set(route)
         return page
 
     @typing_extensions.deprecated("deprecated")
@@ -825,9 +811,6 @@ async def create(
             ),
             cast_to=BrowserCreateResponse,
         )
-        route = browser_route_from_browser(result)
-        if route is not None:
-            self._client.browser_route_cache.set(route)
         return result
 
     async def retrieve(
@@ -871,9 +854,6 @@ async def retrieve(
             ),
             cast_to=BrowserRetrieveResponse,
         )
-        route = browser_route_from_browser(result)
-        if route is not None:
-            self._client.browser_route_cache.set(route)
         return result
 
     async def update(
@@ -932,9 +912,6 @@ async def update(
             ),
             cast_to=BrowserUpdateResponse,
         )
-        route = browser_route_from_browser(result)
-        if route is not None:
-            self._client.browser_route_cache.set(route)
         return result
 
     def list(
@@ -999,11 +976,6 @@ def list(
             ),
             model=BrowserListResponse,
         )
-        typed_page = cast(AsyncOffsetPagination[BrowserListResponse], page)
-        for item in typed_page.items:
-            route = browser_route_from_browser(item)
-            if route is not None:
-                self._client.browser_route_cache.set(route)
         return page
 
     @typing_extensions.deprecated("deprecated")

tests/test_browser_routing.py

@@ -7,7 +7,7 @@
 import respx
 import pytest
 
-from kernel import Kernel
+from kernel import Kernel, AsyncKernel
 from kernel.lib.browser_routing.util import jwt_from_cdp_ws_url
 from kernel.lib.browser_routing.routing import (
     BrowserRoute,
@@ -125,6 +125,71 @@ def test_browser_request_requires_cached_route() -> None:
             client.browsers.request("sess-1", "GET", "https://example.com")
 
 
+@respx.mock
+def test_browser_create_warms_route_cache() -> None:
+    create_route = respx.post(f"{base_url}/browsers").mock(return_value=httpx.Response(200, json=_fake_browser()))
+    routed_request = respx.get("http://browser-session.test/browser/kernel/curl/raw").mock(
+        return_value=httpx.Response(200, content=b"ok")
+    )
+    with Kernel(base_url=base_url, api_key=api_key, _strict_response_validation=True) as client:
+        browser = client.browsers.create()
+        routed = client.browsers.request(browser.session_id, "GET", "https://example.com")
+
+    assert create_route.called
+    assert browser.session_id == "sess-1"
+    assert routed.status_code == 200
+    assert routed_request.called
+
+
+@respx.mock
+def test_raw_browser_create_warms_route_cache() -> None:
+    create_route = respx.post(f"{base_url}/browsers").mock(return_value=httpx.Response(200, json=_fake_browser()))
+    routed_request = respx.get("http://browser-session.test/browser/kernel/curl/raw").mock(
+        return_value=httpx.Response(200, content=b"ok")
+    )
+    with Kernel(base_url=base_url, api_key=api_key, _strict_response_validation=True) as client:
+        response = client.browsers.with_raw_response.create()
+        routed = client.browsers.request("sess-1", "GET", "https://example.com")
+
+    assert create_route.called
+    assert response.is_closed is True
+    assert routed.status_code == 200
+    assert routed.content == b"ok"
+    request = cast(httpx.Request, cast(Any, routed_request.calls[0]).request)
+    assert request.url.params.get("jwt") == "token-abc"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_raw_browser_create_warms_route_cache() -> None:
+    create_route = respx.post(f"{base_url}/browsers").mock(return_value=httpx.Response(200, json=_fake_browser()))
+    routed_request = respx.get("http://browser-session.test/browser/kernel/curl/raw").mock(
+        return_value=httpx.Response(200, content=b"ok")
+    )
+    async with AsyncKernel(base_url=base_url, api_key=api_key, _strict_response_validation=True) as client:
+        response = await client.browsers.with_raw_response.create()
+        routed = await client.browsers.request("sess-1", "GET", "https://example.com")
+
+    assert create_route.called
+    assert response.is_closed is True
+    assert routed.status_code == 200
+    assert routed.content == b"ok"
+    request = cast(httpx.Request, cast(Any, routed_request.calls[0]).request)
+    assert request.url.params.get("jwt") == "token-abc"
+
+
+@respx.mock
+def test_only_browser_metadata_endpoints_warm_route_cache() -> None:
+    projects_route = respx.get(f"{base_url}/projects").mock(return_value=httpx.Response(200, json=_fake_browser()))
+    with Kernel(base_url=base_url, api_key=api_key, _strict_response_validation=True) as client:
+        response = client.projects.with_raw_response.list()
+        with pytest.raises(ValueError, match="route cache"):
+            client.browsers.request("sess-1", "GET", "https://example.com")
+
+    assert projects_route.called
+    assert response.is_closed is True
+
+
 def test_browser_route_cache_normalizes_session_id_keys() -> None:
     cache = BrowserRouteCache()
     cache.set(