Merge branch 'main' into hypeship/isp-proxy-ip-address

Author: dprevoznik

auth/profiles.mdx

@@ -127,6 +127,68 @@ _ = kernelBrowser
 ```
 </CodeGroup>
 
+### Prevent concurrent profile writes
+
+Saving replaces the profile's entire stored browser state; it doesn't merge cookies or local storage from multiple sessions. If more than one browser uses the same profile with `save_changes: true`, the browser that ends last overwrites the profile with its state.
+
+Before starting a writer, call `GET /browsers?status=active&query=<profileId>` and check `profile_save_changes` to find active sessions that can save to that profile. The `query` parameter can match fields other than the profile ID, so filter the results by the exact `profile.id` too.
+
+<CodeGroup>
+```typescript TypeScript
+const profileId = kernelBrowser.profile!.id;
+const activeWriters = [];
+
+for await (const browser of kernel.browsers.list({
+  status: 'active',
+  query: profileId,
+})) {
+  if (browser.profile?.id === profileId && browser.profile_save_changes) {
+    activeWriters.push(browser);
+  }
+}
+
+if (activeWriters.length > 0) {
+  throw new Error(`Profile already has an active writer: ${activeWriters[0].session_id}`);
+}
+```
+
+```python Python
+profile_id = kernel_browser.profile.id
+active_writers = [
+    browser
+    for browser in kernel.browsers.list(status="active", query=profile_id)
+    if browser.profile
+    and browser.profile.id == profile_id
+    and browser.profile_save_changes
+]
+
+if active_writers:
+    raise RuntimeError(
+        f"Profile already has an active writer: {active_writers[0].session_id}"
+    )
+```
+
+```go Go
+profileID := kernelBrowser.Profile.ID
+pager := client.Browsers.ListAutoPaging(ctx, kernel.BrowserListParams{
+	Status: kernel.BrowserListParamsStatusActive,
+	Query:  kernel.String(profileID),
+})
+
+for pager.Next() {
+	browser := pager.Current()
+	if browser.Profile.ID == profileID && browser.ProfileSaveChanges {
+		panic(fmt.Sprintf("profile already has an active writer: %s", browser.SessionID))
+	}
+}
+if err := pager.Err(); err != nil {
+	panic(err)
+}
+```
+</CodeGroup>
+
+This check and browser creation are separate requests. If multiple workers can start sessions concurrently, use your own lock or lease around both operations so two workers can't pass the check at the same time.
+
 ## 3. Use the browser, then close it to persist the state
 
 After using a browser with `save_changes: true`, closing the browser will save cookies and local storage into the profile.
@@ -513,6 +575,6 @@ _ = browser
 - A profile's `name` must be unique within your [project](/info/projects). The same name can be reused across different projects in the same org.
 - Profiles store cookies and local storage. Start the session with `save_changes: true` to write changes back when the browser is closed.
 - To keep a profile immutable for a run, omit `save_changes` (default) when creating the browser.
-- Multiple browsers in parallel can use the same profile, but only one browser should write (`save_changes: true`) to it at a time. Parallel browsers with `save_changes: true` may cause profile corruption and unpredictable behavior.
-- `save_changes` applies to a profile attached to a single browser — either at creation (`kernel.browsers.create()`) or loaded afterward with `kernel.browsers.update()`. A profile set on a [browser pool's](/browsers/pools) config is loaded read-only and never persisted; `save_changes` sent on a pool's profile is silently ignored. To persist per-user state through a pool, attach the profile after acquiring the browser and release with `reuse: false` — see [Per-user profiles with pools](/browsers/pools#per-user-profiles-with-browser-pools).
+- Multiple browsers in parallel can use the same profile, but only one browser can safely write (`save_changes: true`) to it at a time. Each save overwrites the whole profile, so the browser that ends last wins.
+- `save_changes` applies to a profile attached to a single browser — either at creation (`kernel.browsers.create()`) or loaded afterward with `kernel.browsers.update()`. A profile set on a [browser pool's](/browsers/pools) config is loaded read-only and never persisted; `save_changes` sent on a pool's profile is silently ignored. To persist per-user state through a pool, attach the profile with `save_changes: true` after acquiring the browser and release with `reuse: false` — see [Per-user profiles with pools](/browsers/pools#per-user-profiles-with-browser-pools).
 - Profile data is encrypted end to end using a per-organization key.

browsers/pools.mdx

@@ -29,7 +29,7 @@ A few constraints to weigh before moving a workload onto a browser pool:
 
 - **No GPU browsers.** GPU-accelerated browsers are on-demand only. Use `browsers.create()` for WebGL, video, or canvas-heavy work.
 - **One fixed configuration per browser pool**, with `start_url` the only setting you can override per acquisition — see [Create a browser pool](#create-a-browser-pool).
-- **Profiles load read-only**, and a browser pool holds one at a time — see [Profiles with browser pools](#profiles-with-browser-pools) for how to persist state per user.
+- **A profile set on the browser pool loads read-only**, and a browser pool holds one at a time — see [Per-user profiles with browser pools](#per-user-profiles-with-browser-pools) for how to persist state per user.
 - **Browser pool capacity counts against your [concurrency limit](/info/pricing#concurrency-limits)** whether or not its browsers are acquired, though idle pooled browsers aren't billed.
 - **Plan-gated.** Browser pools are available on the Start-Up and Enterprise plans.
 
@@ -208,7 +208,68 @@ A profile attached to the pool is loaded **read-only**. Every browser in the poo
 
 ### Per-user profiles with browser pools
 
-Because that profile is shared and read-only, it can't hold per-user login state for many users at once. To serve many users from one browser pool, create it with no profile — stealth, proxies, extensions, and viewport still live on the pool — then attach each user's profile to the browser *after* you acquire it, and release with `reuse: false` so the browser is destroyed. Destroying it both persists that user's profile changes and keeps their state from reaching the next acquirer.
+Because that profile is shared and read-only, it can't hold per-user login state for many users at once. To serve many users from one browser pool, create it with no profile — stealth, proxies, extensions, and viewport still live on the pool — then attach each user's profile to the browser *after* you acquire it, and release with `reuse: false` so the browser is destroyed. Destroying it keeps that user's state from reaching the next acquirer.
+
+The read-only rule covers the pool's own profile, not one attached after acquiring: that profile belongs to the browser, so `save_changes` applies as it does on any other browser. Pass `save_changes: true` when you attach it — it defaults to `false`, and without it the browser is destroyed on release without writing the user's session back.
+
+<CodeGroup>
+```typescript Typescript/Javascript
+const browser = await kernel.browserPools.acquire("my-pool");
+
+await kernel.browsers.update(browser.session_id, {
+  profile: { name: "user-8f21c3", save_changes: true }
+});
+
+// ... drive the browser as that user ...
+
+await kernel.browserPools.release("my-pool", {
+  session_id: browser.session_id,
+  reuse: false,
+});
+```
+
+```python Python
+browser = kernel.browser_pools.acquire("my-pool")
+
+kernel.browsers.update(
+    browser.session_id,
+    profile={"name": "user-8f21c3", "save_changes": True},
+)
+
+# ... drive the browser as that user ...
+
+kernel.browser_pools.release(
+    "my-pool",
+    session_id=browser.session_id,
+    reuse=False,
+)
+```
+
+```go Go
+browser, err := client.BrowserPools.Acquire(ctx, "my-pool", kernel.BrowserPoolAcquireParams{})
+if err != nil {
+	panic(err)
+}
+
+if _, err := client.Browsers.Update(ctx, browser.SessionID, kernel.BrowserUpdateParams{
+	Profile: shared.BrowserProfileParam{
+		Name:        kernel.String("user-8f21c3"),
+		SaveChanges: kernel.Bool(true),
+	},
+}); err != nil {
+	panic(err)
+}
+
+// ... drive the browser as that user ...
+
+if err := client.BrowserPools.Release(ctx, "my-pool", kernel.BrowserPoolReleaseParams{
+	SessionID: browser.SessionID,
+	Reuse:     kernel.Bool(false),
+}); err != nil {
+	panic(err)
+}
+```
+</CodeGroup>
 
 A profile can only be loaded into a browser that was created without one, which is why the pool itself has to stay profile-free.