refactor: move python browser routing rollout to env

Remove the public browser routing constructor config and derive direct-to-VM subresource routing from KERNEL_BROWSER_ROUTING_SUBRESOURCES instead, defaulting to curl while keeping the raw request helpers direct to the browser.

Author: rgarcia

examples/browser_routing.py

@@ -4,16 +4,14 @@
 
 import httpx
 
-from kernel import Kernel, BrowserRoutingConfig
+from kernel import Kernel
 
 
 def main() -> None:
-    with Kernel(browser_routing=BrowserRoutingConfig(enabled=True, subresources=("process",))) as client:
+    with Kernel() as client:
         browsers = cast(Any, client.browsers)
         browser = browsers.create(headless=True)
         try:
-            browsers.process.exec(browser.session_id, command="uname", args=["-a"])
-
             response = cast(httpx.Response, browsers.request(browser.session_id, "GET", "https://example.com"))
             print("status", response.status_code)
 

src/kernel/__init__.py

@@ -16,7 +16,6 @@
     AsyncKernel,
     AsyncStream,
     RequestOptions,
-    BrowserRoutingConfig,
 )
 from ._models import BaseModel
 from ._version import __title__, __version__
@@ -80,7 +79,6 @@
     "RateLimitError",
     "InternalServerError",
     "Timeout",
-    "BrowserRoutingConfig",
     "RequestOptions",
     "Client",
     "AsyncClient",

src/kernel/_client.py

@@ -34,6 +34,7 @@
     BrowserRoutingConfig,
     strip_direct_vm_auth,
     rewrite_direct_vm_options,
+    browser_routing_config_from_env,
 )
 
 if TYPE_CHECKING:
@@ -70,7 +71,6 @@
     "Transport",
     "ProxiesTypes",
     "RequestOptions",
-    "BrowserRoutingConfig",
     "Kernel",
     "AsyncKernel",
     "Client",
@@ -89,7 +89,7 @@ class Kernel(SyncAPIClient):
     browser_route_cache: BrowserRouteCache
 
     _environment: Literal["production", "development"] | NotGiven
-    _browser_routing: BrowserRoutingConfig | None
+    _browser_routing: BrowserRoutingConfig
 
     def __init__(
         self,
@@ -101,7 +101,6 @@ def __init__(
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
         default_query: Mapping[str, object] | None = None,
-        browser_routing: BrowserRoutingConfig | None = None,
         # Configure a custom httpx client.
         # We provide a `DefaultHttpxClient` class that you can pass to retain the default values we use for `limits`, `timeout` & `follow_redirects`.
         # See the [httpx documentation](https://www.python-httpx.org/api/#client) for more details.
@@ -166,7 +165,7 @@ def __init__(
             _strict_response_validation=_strict_response_validation,
         )
         self.browser_route_cache = _browser_route_cache or BrowserRouteCache()
-        self._browser_routing = browser_routing
+        self._browser_routing = browser_routing_config_from_env()
 
     @cached_property
     def deployments(self) -> DeploymentsResource:
@@ -301,7 +300,6 @@ def copy(
         set_default_headers: Mapping[str, str] | None = None,
         default_query: Mapping[str, object] | None = None,
         set_default_query: Mapping[str, object] | None = None,
-        browser_routing: BrowserRoutingConfig | None = None,
         _browser_route_cache: BrowserRouteCache | None = None,
         _extra_kwargs: Mapping[str, Any] = {},
     ) -> Self:
@@ -336,7 +334,6 @@ def copy(
             max_retries=max_retries if is_given(max_retries) else self.max_retries,
             default_headers=headers,
             default_query=params,
-            browser_routing=browser_routing if browser_routing is not None else self._browser_routing,
             _browser_route_cache=_browser_route_cache or self.browser_route_cache,
             **_extra_kwargs,
         )
@@ -385,7 +382,7 @@ class AsyncKernel(AsyncAPIClient):
     browser_route_cache: BrowserRouteCache
 
     _environment: Literal["production", "development"] | NotGiven
-    _browser_routing: BrowserRoutingConfig | None
+    _browser_routing: BrowserRoutingConfig
 
     def __init__(
         self,
@@ -397,7 +394,6 @@ def __init__(
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
         default_query: Mapping[str, object] | None = None,
-        browser_routing: BrowserRoutingConfig | None = None,
         # Configure a custom httpx client.
         # We provide a `DefaultAsyncHttpxClient` class that you can pass to retain the default values we use for `limits`, `timeout` & `follow_redirects`.
         # See the [httpx documentation](https://www.python-httpx.org/api/#asyncclient) for more details.
@@ -462,7 +458,7 @@ def __init__(
             _strict_response_validation=_strict_response_validation,
         )
         self.browser_route_cache = _browser_route_cache or BrowserRouteCache()
-        self._browser_routing = browser_routing
+        self._browser_routing = browser_routing_config_from_env()
 
     @cached_property
     def deployments(self) -> AsyncDeploymentsResource:
@@ -597,7 +593,6 @@ def copy(
         set_default_headers: Mapping[str, str] | None = None,
         default_query: Mapping[str, object] | None = None,
         set_default_query: Mapping[str, object] | None = None,
-        browser_routing: BrowserRoutingConfig | None = None,
         _browser_route_cache: BrowserRouteCache | None = None,
         _extra_kwargs: Mapping[str, Any] = {},
     ) -> Self:
@@ -632,7 +627,6 @@ def copy(
             max_retries=max_retries if is_given(max_retries) else self.max_retries,
             default_headers=headers,
             default_query=params,
-            browser_routing=browser_routing if browser_routing is not None else self._browser_routing,
             _browser_route_cache=_browser_route_cache or self.browser_route_cache,
             **_extra_kwargs,
         )

src/kernel/lib/browser_routing/routing.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from typing import Any
 from dataclasses import field, dataclass
 
@@ -24,10 +25,19 @@ class BrowserRoute:
 
 @dataclass
 class BrowserRoutingConfig:
-    enabled: bool = False
     subresources: tuple[str, ...] = field(default_factory=tuple)
 
 
+def browser_routing_config_from_env() -> BrowserRoutingConfig:
+    raw = os.environ.get("KERNEL_BROWSER_ROUTING_SUBRESOURCES")
+    if raw is None:
+        return BrowserRoutingConfig(subresources=("curl",))
+    if raw.strip() == "":
+        return BrowserRoutingConfig()
+
+    return BrowserRoutingConfig(subresources=tuple(part.strip() for part in raw.split(",") if part.strip()))
+
+
 class BrowserRouteCache:
     def __init__(self) -> None:
         self._routes: dict[str, BrowserRoute] = {}
@@ -74,11 +84,8 @@ def rewrite_direct_vm_options(
     options: FinalRequestOptions,
     *,
     cache: BrowserRouteCache,
-    config: BrowserRoutingConfig | None,
+    config: BrowserRoutingConfig,
 ) -> FinalRequestOptions:
-    if config is None or not config.enabled:
-        return options
-
     match = match_direct_vm_path(options.url)
     if match is None:
         return options

tests/test_browser_routing.py

@@ -9,7 +9,7 @@
 
 from kernel import Kernel
 from kernel.lib.browser_routing.util import jwt_from_cdp_ws_url
-from kernel.lib.browser_routing.routing import BrowserRoutingConfig, browser_route_from_browser
+from kernel.lib.browser_routing.routing import browser_route_from_browser, browser_routing_config_from_env
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 api_key = "sk-123"
@@ -39,14 +39,14 @@ def test_jwt_from_cdp_ws_url() -> None:
 
 
 @respx.mock
-def test_routes_allowlisted_browser_subresources_directly_to_vm() -> None:
+def test_routes_allowlisted_browser_subresources_directly_to_vm(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("KERNEL_BROWSER_ROUTING_SUBRESOURCES", "process")
     route = respx.post("http://browser-session.test/browser/kernel/process/exec").mock(
         return_value=httpx.Response(200, json={"exit_code": 0, "stdout_b64": "", "stderr_b64": ""})
     )
     with Kernel(
         base_url=base_url,
         api_key=api_key,
-        browser_routing=BrowserRoutingConfig(enabled=True, subresources=("process",)),
         _strict_response_validation=True,
     ) as client:
         _cache_browser(client)
@@ -60,14 +60,14 @@ def test_routes_allowlisted_browser_subresources_directly_to_vm() -> None:
 
 
 @respx.mock
-def test_skips_direct_vm_routing_outside_allowlist() -> None:
+def test_skips_direct_vm_routing_outside_allowlist(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("KERNEL_BROWSER_ROUTING_SUBRESOURCES", "computer")
     route = respx.post(f"{base_url}/browsers/sess-1/process/exec").mock(
         return_value=httpx.Response(200, json={"exit_code": 0, "stdout_b64": "", "stderr_b64": ""})
     )
     with Kernel(
         base_url=base_url,
         api_key=api_key,
-        browser_routing=BrowserRoutingConfig(enabled=True, subresources=("computer",)),
         _strict_response_validation=True,
     ) as client:
         _cache_browser(client)
@@ -123,3 +123,13 @@ def test_browser_request_requires_cached_route() -> None:
 def test_browser_route_from_browser_requires_base_url_and_jwt() -> None:
     assert browser_route_from_browser({**_fake_browser(), "base_url": None}) is None
     assert browser_route_from_browser({**_fake_browser(), "cdp_ws_url": None}) is None
+
+
+def test_browser_routing_config_from_env_defaults_to_curl(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("KERNEL_BROWSER_ROUTING_SUBRESOURCES", raising=False)
+    assert browser_routing_config_from_env().subresources == ("curl",)
+
+
+def test_browser_routing_config_from_env_empty_string_disables_routing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("KERNEL_BROWSER_ROUTING_SUBRESOURCES", "")
+    assert browser_routing_config_from_env().subresources == ()