diff --git a/browsers/pools/faq.mdx b/browsers/pools/faq.mdx index 961a641..7a22d87 100644 --- a/browsers/pools/faq.mdx +++ b/browsers/pools/faq.mdx @@ -22,11 +22,11 @@ When a browser from a pool is set to be destroyed (by reaching its specified `ti ### Can I update a pool's configuration without recreating it? -Yes, use `kernel.browserPools.update()`. By default, idle browsers are discarded and rebuilt with new configuration. Set `discard_all_idle: false` to only apply changes to newly created browsers. +Yes, use `kernel.browserPools.update()`. By default (`discard_all_idle: false`), existing idle browsers keep their current configuration and only newly created browsers use the new one. Pass `discard_all_idle: true` to discard all idle browsers and rebuild them immediately with the new configuration. ### If I update a pool, do browsers that are currently in use pick up the new configuration? -No. A pool update only rebuilds the browsers that are idle at the time of the update (the default `discard_all_idle: true` behavior). A browser that's acquired during the update keeps its original configuration, and if you release it with `reuse: true` (the default) it returns to the pool still running the old configuration and keeps getting handed out that way. +No. A plain `update()` doesn't rebuild any existing browsers — it only changes the configuration used for future ones. Even the idle browsers keep their old config unless you pass `discard_all_idle: true` (or flush the pool). Browsers that are acquired during the update are never touched regardless: an in-use browser keeps its original configuration, and if you release it with `reuse: true` (the default) it returns to the pool still running the old configuration and keeps getting handed out that way. You have three ways to get it onto the new configuration: release it with `reuse: false` so it's destroyed and rebuilt on release instead of the old one returning to the pool; let the acquired browser reach its `timeout_seconds` while idle so it's destroyed and the pool refills automatically; or flush it after the fact with `kernel.browserPools.flush()` (or a later `kernel.browserPools.update()` with `discard_all_idle: true`) once the in-use browsers have been released. @@ -50,7 +50,7 @@ The pool's `timeout_seconds` only applies while the browser is acquired. If your ### Can I use different browser configurations within the same pool? -All browsers in a pool initialize with the same configuration. Calling `kernel.browserPools.update()` updates the configuration for all idle browsers in the pool. +All browsers in a pool initialize with the same configuration. Calling `kernel.browserPools.update()` changes the pool's configuration for browsers created after the update; existing idle browsers keep their original configuration unless you pass `discard_all_idle: true` (or flush the pool). Once you've acquired a browser, you can apply certain [hot swap configurations](https://www.kernel.sh/docs/api-reference/browsers/update-browser-session) to that browser instance using `kernel.browsers.update()`. ### How do I handle rate limiting from target websites? diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index cf6a2ba..b494069 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -200,7 +200,7 @@ if err := client.BrowserPools.Release(ctx, "my-pool", kernel.BrowserPoolReleaseP ## Update a pool -Update the pool configuration. By default, all idle browsers are discarded and rebuilt with the new configuration. +Update the pool configuration. By default, existing idle browsers keep their current configuration and only newly created browsers use the new one. Pass `discard_all_idle: true` to discard all idle browsers and rebuild them immediately with the new configuration. ```typescript Typescript/Javascript @@ -234,10 +234,10 @@ _ = updatedPool The `size` parameter is always required when updating a pool, even if you only want to change other settings. -By default, updating a pool discards all idle browsers and rebuilds them with the new configuration. Set `discard_all_idle: false` to keep existing idle browsers and only apply the new configuration to newly created browsers. +By default (`discard_all_idle: false`), updating a pool leaves existing idle browsers untouched — they keep their original configuration, and only browsers created after the update use the new configuration. Set `discard_all_idle: true` to discard all idle browsers and rebuild them immediately with the new configuration. -Reused browsers keep the configuration they were created with. A pool update only rebuilds the browsers that are idle at the time of the update (the default `discard_all_idle: true` behavior). A browser that's acquired during an update keeps its original configuration, and if you then release it with `reuse: true` (the default) it re-enters the pool still carrying that stale configuration and keeps getting handed out that way. +Reused browsers keep the configuration they were created with. A plain `update()` rebuilds nothing that already exists — it only changes the config used for future browsers. To rebuild the idle browsers too, pass `discard_all_idle: true` (or call [`flush()`](#flush-idle-browsers)). Either way, browsers that are acquired during an update are never touched: an in-use browser keeps its original configuration, and if you then release it with `reuse: true` (the default) it re-enters the pool still carrying that stale configuration and keeps getting handed out that way. You have three ways to get an in-use browser onto the new configuration: