fix: sniff browser pool route cache updates

Keep the browser route cache in sync for pool acquire and release flows so leased sessions can use direct VM routing without resource-specific cache handling.

Made-with: Cursor

Author: rgarcia

src/kernel/_client.py

@@ -37,7 +37,7 @@
     strip_direct_vm_auth,
     rewrite_direct_vm_options,
     browser_routing_config_from_env,
-    maybe_evict_deleted_browser_route_from_response,
+    maybe_evict_browser_route_from_response,
     maybe_populate_browser_route_cache_from_response,
 )
 
@@ -303,7 +303,7 @@ def _process_response(
         retries_taken: int = 0,
     ) -> ResponseT:
         maybe_populate_browser_route_cache_from_response(response, cache=self.browser_route_cache)
-        maybe_evict_deleted_browser_route_from_response(response, cache=self.browser_route_cache)
+        maybe_evict_browser_route_from_response(response, cache=self.browser_route_cache)
         return super()._process_response(
             cast_to=cast_to,
             options=options,
@@ -618,7 +618,7 @@ async def _process_response(
         retries_taken: int = 0,
     ) -> ResponseT:
         maybe_populate_browser_route_cache_from_response(response, cache=self.browser_route_cache)
-        maybe_evict_deleted_browser_route_from_response(response, cache=self.browser_route_cache)
+        maybe_evict_browser_route_from_response(response, cache=self.browser_route_cache)
         return await super()._process_response(
             cast_to=cast_to,
             options=options,

src/kernel/lib/browser_routing/routing.py

@@ -2,6 +2,7 @@
 
 import os
 import re
+import json
 from typing import Any, Mapping, cast
 from dataclasses import field, dataclass
 from urllib.parse import unquote
@@ -33,6 +34,8 @@ class BrowserRoutingConfig:
 
 _BROWSER_ROUTE_CACHEABLE_PATH = re.compile(r"^/(?:v\d+/)?browsers(?:/[^/]+)?/?$")
 _BROWSER_DELETE_BY_ID_PATH = re.compile(r"^/(?:v\d+/)?browsers/([^/]+)/?$")
+_BROWSER_POOL_ACQUIRE_PATH = re.compile(r"^/(?:v\d+/)?browser_pools/[^/]+/acquire/?$")
+_BROWSER_POOL_RELEASE_PATH = re.compile(r"^/(?:v\d+/)?browser_pools/[^/]+/release/?$")
 
 
 def browser_routing_config_from_env() -> BrowserRoutingConfig:
@@ -103,15 +106,11 @@ def maybe_populate_browser_route_cache_from_response(response: httpx.Response, *
         return
 
 
-def maybe_evict_deleted_browser_route_from_response(response: httpx.Response, *, cache: BrowserRouteCache) -> None:
-    if not response.is_success or response.request.method.upper() != "DELETE":
+def maybe_evict_browser_route_from_response(response: httpx.Response, *, cache: BrowserRouteCache) -> None:
+    if not response.is_success:
         return
 
-    match = _BROWSER_DELETE_BY_ID_PATH.match(response.request.url.path)
-    if match is None:
-        return
-
-    session_id = unquote(match.group(1)).strip()
+    session_id = _session_id_to_evict_from_response(response)
     if not session_id:
         return
 
@@ -142,7 +141,51 @@ def _should_populate_browser_route_cache(response: httpx.Response) -> bool:
     if "application/json" not in content_type:
         return False
 
-    return bool(_BROWSER_ROUTE_CACHEABLE_PATH.match(response.request.url.path))
+    path = response.request.url.path
+    return bool(_BROWSER_ROUTE_CACHEABLE_PATH.match(path) or _BROWSER_POOL_ACQUIRE_PATH.match(path))
+
+
+def _session_id_to_evict_from_response(response: httpx.Response) -> str | None:
+    method = response.request.method.upper()
+    path = response.request.url.path
+
+    if method == "DELETE":
+        return _session_id_from_browser_delete_path(path)
+
+    if method == "POST":
+        return _session_id_from_browser_pool_release_request(response.request, path)
+
+    return None
+
+
+def _session_id_from_browser_delete_path(path: str) -> str | None:
+    match = _BROWSER_DELETE_BY_ID_PATH.match(path)
+    if match is None:
+        return None
+
+    session_id = unquote(match.group(1)).strip()
+    return session_id or None
+
+
+def _session_id_from_browser_pool_release_request(request: httpx.Request, path: str) -> str | None:
+    if _BROWSER_POOL_RELEASE_PATH.match(path) is None:
+        return None
+
+    content_type = request.headers.get("content-type", "").lower()
+    if "application/json" not in content_type:
+        return None
+
+    try:
+        body = json.loads(request.content.decode("utf-8"))
+    except Exception:
+        return None
+
+    session_id = body.get("session_id")
+    if not isinstance(session_id, str):
+        return None
+
+    normalized = session_id.strip()
+    return normalized or None
 
 
 def rewrite_direct_vm_options(

tests/test_browser_routing.py

@@ -190,6 +190,24 @@ def test_only_browser_metadata_endpoints_warm_route_cache() -> None:
     assert response.is_closed is True
 
 
+@respx.mock
+def test_browser_pool_acquire_warms_route_cache() -> None:
+    acquire_route = respx.post(f"{base_url}/browser_pools/pool-1/acquire").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.browser_pools.with_raw_response.acquire("pool-1")
+        routed = client.browsers.request("sess-1", "GET", "https://example.com")
+
+    assert acquire_route.called
+    assert response.is_closed is True
+    assert routed.status_code == 200
+    assert routed_request.called
+
+
 @respx.mock
 def test_browser_delete_by_id_evicts_route_cache() -> None:
     delete_route = respx.delete(f"{base_url}/browsers/sess-1").mock(return_value=httpx.Response(204))
@@ -203,6 +221,19 @@ def test_browser_delete_by_id_evicts_route_cache() -> None:
     assert response.is_closed is True
 
 
+@respx.mock
+def test_browser_pool_release_evicts_route_cache() -> None:
+    release_route = respx.post(f"{base_url}/browser_pools/pool-1/release").mock(return_value=httpx.Response(204))
+    with Kernel(base_url=base_url, api_key=api_key, _strict_response_validation=True) as client:
+        _cache_browser(client)
+        response = client.browser_pools.with_raw_response.release("pool-1", session_id="sess-1")
+        with pytest.raises(ValueError, match="route cache"):
+            client.browsers.request("sess-1", "GET", "https://example.com")
+
+    assert release_route.called
+    assert response.is_closed is True
+
+
 @respx.mock
 def test_failed_browser_delete_by_id_keeps_route_cache() -> None:
     delete_route = respx.delete(f"{base_url}/browsers/sess-1").mock(
@@ -222,6 +253,41 @@ def test_failed_browser_delete_by_id_keeps_route_cache() -> None:
     assert routed_request.called
 
 
+@respx.mock
+def test_failed_browser_pool_release_keeps_route_cache() -> None:
+    release_route = respx.post(f"{base_url}/browser_pools/pool-1/release").mock(
+        return_value=httpx.Response(500, json={"error": "boom"})
+    )
+    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:
+        _cache_browser(client)
+        with pytest.raises(InternalServerError):
+            client.browser_pools.release("pool-1", session_id="sess-1")
+        routed = client.browsers.request("sess-1", "GET", "https://example.com")
+
+    assert release_route.called
+    assert routed.status_code == 200
+    assert routed_request.called
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_browser_pool_release_evicts_route_cache() -> None:
+    release_route = respx.post(f"{base_url}/browser_pools/pool-1/release").mock(return_value=httpx.Response(204))
+    async with AsyncKernel(base_url=base_url, api_key=api_key, _strict_response_validation=True) as client:
+        route = browser_route_from_browser(_fake_browser())
+        assert route is not None
+        client.browser_route_cache.set(route)
+        response = await client.browser_pools.with_raw_response.release("pool-1", session_id="sess-1")
+        with pytest.raises(ValueError, match="route cache"):
+            await client.browsers.request("sess-1", "GET", "https://example.com")
+
+    assert release_route.called
+    assert response.is_closed is True
+
+
 def test_browser_route_cache_normalizes_session_id_keys() -> None:
     cache = BrowserRouteCache()
     cache.set(