feat: Support egress allowlists on browser pools

Stainless-Generated-From: 5799c8ad59001401cd999d6117d0a5733f3686a8

Author: kernel-internal[bot]

src/kernel/resources/browser_pools.py

@@ -123,9 +123,9 @@ def create(
 
           name: Optional name for the browser pool. Must be unique within the project.
 
-          network: Network configuration applied to browsers in this pool. Proxy routes require
-              proxy-v3; the pool will not provision browsers through Envoy if proxy-v3 is
-              unavailable.
+          network: Network configuration applied to browsers in this pool. Egress allowlists and
+              proxy routes require proxy-v3; the pool will not provision browsers through
+              Envoy if proxy-v3 is unavailable.
 
           profile: Profile configuration for browsers in a pool. Provide either id or name.
               Profiles must be created beforehand. Unlike single browser sessions, pools load
@@ -296,9 +296,11 @@ def update(
           discard_all_idle: Whether to discard all idle browsers and rebuild them immediately with the new
               configuration. Defaults to false. Only browsers that are idle when the update
               runs are rebuilt. A browser that is in use during the update keeps its original
-              configuration, and if it is later released with `reuse: true` it returns to the
-              pool with that stale configuration until it is discarded (by this flag on a
-              later update, or by flushing the pool).
+              configuration, except that its allowlist is reset to the current pool baseline
+              on release or the browser is replaced. For other configuration fields, if it is
+              later released with `reuse: true` it returns to the pool with that stale
+              configuration until it is discarded (by this flag on a later update, or by
+              flushing the pool).
 
           extensions: If provided, replaces the extension list. Empty array clears all
               previously-selected extensions. Omit this field to leave extensions unchanged.
@@ -321,10 +323,14 @@ def update(
           network: If provided, replaces the pool's network configuration. Omit to leave the
               existing configuration unchanged; an empty object ({}) removes it, while
               network: {private_hosts: []} or network: {proxy_routes: []} sets an explicit
-              empty list. Proxy routes require proxy-v3; the pool will not provision browsers
-              through Envoy if proxy-v3 is unavailable. Only applied to browsers created in
-              the pool after the update; browsers already in the pool keep their configuration
-              until discarded (see discard_all_idle).
+              empty list; allowed_hosts must be non-empty when supplied. Egress allowlists and
+              proxy routes require proxy-v3; the pool will not provision browsers through
+              Envoy if proxy-v3 is unavailable. Changing allowed_hosts automatically replaces
+              idle browsers. Leased browsers retain their allowlist until release, when it is
+              reset to the current pool baseline or the browser is replaced if it cannot
+              safely receive that baseline. Stale browsers cannot be acquired. Other network
+              fields only apply to browsers created after the update; existing browsers keep
+              those fields until discarded (see discard_all_idle).
 
           profile: Profile configuration for browsers in a pool. Provide either id or name.
               Profiles must be created beforehand. Unlike single browser sessions, pools load
@@ -774,9 +780,9 @@ async def create(
 
           name: Optional name for the browser pool. Must be unique within the project.
 
-          network: Network configuration applied to browsers in this pool. Proxy routes require
-              proxy-v3; the pool will not provision browsers through Envoy if proxy-v3 is
-              unavailable.
+          network: Network configuration applied to browsers in this pool. Egress allowlists and
+              proxy routes require proxy-v3; the pool will not provision browsers through
+              Envoy if proxy-v3 is unavailable.
 
           profile: Profile configuration for browsers in a pool. Provide either id or name.
               Profiles must be created beforehand. Unlike single browser sessions, pools load
@@ -947,9 +953,11 @@ async def update(
           discard_all_idle: Whether to discard all idle browsers and rebuild them immediately with the new
               configuration. Defaults to false. Only browsers that are idle when the update
               runs are rebuilt. A browser that is in use during the update keeps its original
-              configuration, and if it is later released with `reuse: true` it returns to the
-              pool with that stale configuration until it is discarded (by this flag on a
-              later update, or by flushing the pool).
+              configuration, except that its allowlist is reset to the current pool baseline
+              on release or the browser is replaced. For other configuration fields, if it is
+              later released with `reuse: true` it returns to the pool with that stale
+              configuration until it is discarded (by this flag on a later update, or by
+              flushing the pool).
 
           extensions: If provided, replaces the extension list. Empty array clears all
               previously-selected extensions. Omit this field to leave extensions unchanged.
@@ -972,10 +980,14 @@ async def update(
           network: If provided, replaces the pool's network configuration. Omit to leave the
               existing configuration unchanged; an empty object ({}) removes it, while
               network: {private_hosts: []} or network: {proxy_routes: []} sets an explicit
-              empty list. Proxy routes require proxy-v3; the pool will not provision browsers
-              through Envoy if proxy-v3 is unavailable. Only applied to browsers created in
-              the pool after the update; browsers already in the pool keep their configuration
-              until discarded (see discard_all_idle).
+              empty list; allowed_hosts must be non-empty when supplied. Egress allowlists and
+              proxy routes require proxy-v3; the pool will not provision browsers through
+              Envoy if proxy-v3 is unavailable. Changing allowed_hosts automatically replaces
+              idle browsers. Leased browsers retain their allowlist until release, when it is
+              reset to the current pool baseline or the browser is replaced if it cannot
+              safely receive that baseline. Stale browsers cannot be acquired. Other network
+              fields only apply to browsers created after the update; existing browsers keep
+              those fields until discarded (see discard_all_idle).
 
           profile: Profile configuration for browsers in a pool. Provide either id or name.
               Profiles must be created beforehand. Unlike single browser sessions, pools load

src/kernel/types/browser_network_config.py

@@ -52,8 +52,10 @@ class BrowserNetworkConfig(BaseModel):
     processes in the browser VM that do not use the browser's proxy, are not
     filtered, and Kernel's own control traffic is always allowed. Can be replaced or
     removed while the session runs with PATCH /browsers/{id_or_name}, but not added
-    to a browser created without one. Requires proxy v3. Not supported on browser
-    pools.
+    to a browser created without one. Supported on browser pools and their leased
+    browsers. Per-lease changes are reset to the pool's allowlist on release. If a
+    lessee removes the allowlist and the pool still requires one, the browser is
+    replaced on release rather than given an allowlist again. Requires proxy v3.
     """
 
     private_hosts: Optional[List[str]] = None

src/kernel/types/browser_network_config_param.py

@@ -55,8 +55,10 @@ class BrowserNetworkConfigParam(TypedDict, total=False):
     processes in the browser VM that do not use the browser's proxy, are not
     filtered, and Kernel's own control traffic is always allowed. Can be replaced or
     removed while the session runs with PATCH /browsers/{id_or_name}, but not added
-    to a browser created without one. Requires proxy v3. Not supported on browser
-    pools.
+    to a browser created without one. Supported on browser pools and their leased
+    browsers. Per-lease changes are reset to the pool's allowlist on release. If a
+    lessee removes the allowlist and the pool still requires one, the browser is
+    replaced on release rather than given an allowlist again. Requires proxy v3.
     """
 
     private_hosts: SequenceNotStr[str]

src/kernel/types/browser_network_update_param.py

@@ -29,6 +29,8 @@ class BrowserNetworkUpdateParam(TypedDict, total=False):
     minutes during a Kernel deploy. Connections to destinations it still allows,
     such as WebSockets, stay open. A start_url in the same request must be allowed
     by the updated list, and is loaded only after the list takes effect. Requires a
-    browser created with proxy v3, and not supported on pooled browsers. If the
-    request fails, retry it: the new list may already apply to some requests.
+    browser created with proxy v3. Supported on leased pooled browsers; the pool's
+    allowlist is restored before reuse, or the browser is destroyed if it cannot be
+    safely restored. If the request fails, retry it: the new list may already apply
+    to some requests.
     """

src/kernel/types/browser_pool_create_params.py

@@ -70,8 +70,8 @@ class BrowserPoolCreateParams(TypedDict, total=False):
     network: BrowserNetworkConfigParam
     """Network configuration applied to browsers in this pool.
 
-    Proxy routes require proxy-v3; the pool will not provision browsers through
-    Envoy if proxy-v3 is unavailable.
+    Egress allowlists and proxy routes require proxy-v3; the pool will not provision
+    browsers through Envoy if proxy-v3 is unavailable.
     """
 
     profile: Profile

src/kernel/types/browser_pool_update_params.py

@@ -37,9 +37,11 @@ class BrowserPoolUpdateParams(TypedDict, total=False):
     Whether to discard all idle browsers and rebuild them immediately with the new
     configuration. Defaults to false. Only browsers that are idle when the update
     runs are rebuilt. A browser that is in use during the update keeps its original
-    configuration, and if it is later released with `reuse: true` it returns to the
-    pool with that stale configuration until it is discarded (by this flag on a
-    later update, or by flushing the pool).
+    configuration, except that its allowlist is reset to the current pool baseline
+    on release or the browser is replaced. For other configuration fields, if it is
+    later released with `reuse: true` it returns to the pool with that stale
+    configuration until it is discarded (by this flag on a later update, or by
+    flushing the pool).
     """
 
     extensions: Iterable[BrowserExtension]
@@ -81,10 +83,14 @@ class BrowserPoolUpdateParams(TypedDict, total=False):
 
     Omit to leave the existing configuration unchanged; an empty object ({}) removes
     it, while network: {private_hosts: []} or network: {proxy_routes: []} sets an
-    explicit empty list. Proxy routes require proxy-v3; the pool will not provision
-    browsers through Envoy if proxy-v3 is unavailable. Only applied to browsers
-    created in the pool after the update; browsers already in the pool keep their
-    configuration until discarded (see discard_all_idle).
+    explicit empty list; allowed_hosts must be non-empty when supplied. Egress
+    allowlists and proxy routes require proxy-v3; the pool will not provision
+    browsers through Envoy if proxy-v3 is unavailable. Changing allowed_hosts
+    automatically replaces idle browsers. Leased browsers retain their allowlist
+    until release, when it is reset to the current pool baseline or the browser is
+    replaced if it cannot safely receive that baseline. Stale browsers cannot be
+    acquired. Other network fields only apply to browsers created after the update;
+    existing browsers keep those fields until discarded (see discard_all_idle).
     """
 
     profile: Profile