@parcha/pi-browser 0.1.0-beta.14 → 0.1.0-beta.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,12 @@
1
1
  import { execFile, spawn } from "node:child_process";
2
- import { readFileSync } from "node:fs";
3
- import { mkdir, mkdtemp, open, readdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
2
+ import { createReadStream, createWriteStream, readFileSync } from "node:fs";
3
+ import { lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rm, stat, symlink, writeFile } from "node:fs/promises";
4
4
  import os from "node:os";
5
+ import { pipeline } from "node:stream/promises";
5
6
  import path from "node:path";
6
- import { BrowserFailureError } from "../core/custody.js";
7
+ import { BrowserFailureError, PROFILE_NAME } from "../core/custody.js";
7
8
  import { cdpCall } from "./cdp-call.js";
9
+ import { claimWriter, freeWriter, noteWriter } from "./profiles.js";
8
10
  /** Stagehand 4.1.0's DEFAULT_CHROME_FLAGS (packages/sdk-ts/src/browser/localBrowser.ts, MIT, see NOTICE). Without them
9
11
  * Stagehand.create takes about 24 s on a local Chrome instead of under 100 ms. */
10
12
  const CHROME_FLAGS = [
@@ -34,7 +36,7 @@ const CHROME_FLAGS = [
34
36
  "--remote-allow-origins=*",
35
37
  "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
36
38
  ];
37
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, extension: "loaded-locally", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
39
+ const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, profiles: false, extension: "loaded-locally", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
38
40
  const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
39
41
  const READY_MS = 20_000;
40
42
  /** The browser is gone and directories it used are not: a profile left behind holds the session's cookies, so a release that cannot remove
@@ -103,7 +105,8 @@ async function ownDebugger(profile) {
103
105
  const [port, browser] = (await readFile(path.join(profile, "DevToolsActivePort"), "utf8").catch(() => "")).split("\n");
104
106
  return /^\d+$/.test(port ?? "") && browser?.startsWith("/devtools/browser/") ? { port: Number(port), path: browser.trim() } : null;
105
107
  }
106
- const answeringPath = async (port) => debuggerUrl(`http://127.0.0.1:${port}`).then((url) => new URL(url).pathname, () => null);
108
+ /** Bounded: a Chrome that takes the connection and never answers must not hold a start past its deadline. */
109
+ const answeringPath = async (port) => debuggerUrl(`http://127.0.0.1:${port}`, AbortSignal.timeout(2_000)).then((url) => new URL(url).pathname, () => null);
107
110
  /** A port that takes the probe and does not answer within this may still be a live browser's. */
108
111
  const PROBE_MS = 2_000;
109
112
  /** A release that does not own the lease's browser left its profile: the port the profile names took the probe and did
@@ -129,6 +132,71 @@ const profileDir = (root, tag) => {
129
132
  throw new Error("a cdp lease tag is one path segment of [A-Za-z0-9_.-]");
130
133
  return path.join(root, tag);
131
134
  };
135
+ const savedDir = (root, name) => path.join(root, ".profiles", name);
136
+ const refusal = (message) => new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message });
137
+ /** A copy of a profile another Chrome is writing: that Chrome renames, truncates and deletes its journals and temp files
138
+ * all the time. A file gone by the time it is reached is skipped. `fs.cp` fails the whole copy on it, and `fs.copyFile`
139
+ * never returns for a file truncated while it copies (libuv's sendfile loop makes no progress and does not stop), so
140
+ * files go through streams, which end where the file ends. A cancelled `signal` stops the copy at the next file or chunk. */
141
+ export async function copyProfile(from, to, signal) {
142
+ signal?.throwIfAborted();
143
+ await mkdir(to, { recursive: true });
144
+ const entries = await readdir(from, { withFileTypes: true }).catch((error) => { if (error.code === "ENOENT")
145
+ return []; throw error; });
146
+ for (const entry of entries) {
147
+ signal?.throwIfAborted();
148
+ if (/^(Singleton|DevToolsActivePort|lockfile)/.test(entry.name) || entry.name === TMP_MARKER)
149
+ continue;
150
+ const source = path.join(from, entry.name);
151
+ const target = path.join(to, entry.name);
152
+ try {
153
+ if (entry.isDirectory())
154
+ await copyProfile(source, target, signal);
155
+ else if (entry.isSymbolicLink())
156
+ await symlink(await readlink(source), target);
157
+ else if (entry.isFile())
158
+ await pipeline(createReadStream(source), createWriteStream(target, { mode: (await stat(source)).mode & 0o777 }), signal ? { signal } : {});
159
+ }
160
+ catch (error) {
161
+ if (error.code !== "ENOENT" || signal?.aborted)
162
+ throw error;
163
+ }
164
+ }
165
+ }
166
+ /** A saved profile lives in `.profiles/<name>`, which no lease tag can name. Saving, the lease's own directory is a link to
167
+ * it, so release removes the link and never the profile; not saving, it is a copy that leaves the profile as it was. */
168
+ async function prepareProfile(root, dir, profile, tag, owner, signal, remove) {
169
+ if (!PROFILE_NAME.test(profile.name))
170
+ throw refusal("browser profile: a profile name is 1 to 64 characters of letters, digits, dot, underscore and dash, starting with a letter or digit. No session was started.");
171
+ const saved = savedDir(root, profile.name);
172
+ await rm(dir, { recursive: true, force: true });
173
+ if (!profile.save) {
174
+ const exists = await stat(saved).then((s) => s.isDirectory(), () => false);
175
+ if (exists) {
176
+ // A copy cut short (cancelled, a full disk) is no lease: nothing else knows this directory, so it goes here, and is said if it stays.
177
+ try {
178
+ await copyProfile(saved, dir, signal);
179
+ }
180
+ catch (error) {
181
+ const left = await removeAll([dir], remove);
182
+ throw left ? new ProfileNotRemovedError(left.dirs, left.error, error) : error;
183
+ }
184
+ }
185
+ return;
186
+ }
187
+ await claimWriter(`${path.resolve(root)}|${profile.name}`, profile.name, tag, owner, signal);
188
+ try {
189
+ const lock = await readlink(path.join(saved, "SingletonLock")).then((value) => /^(.*)-(\d+)$/.exec(value), () => null);
190
+ if (lock && lock[1] === os.hostname() && alive(Number(lock[2])))
191
+ throw refusal(`browser profile "${profile.name}": a Chrome process (${lock[2]}) is using this profile. No session was started.`);
192
+ await mkdir(path.join(saved, "Default"), { recursive: true });
193
+ await symlink(path.resolve(saved), dir, "dir");
194
+ }
195
+ catch (error) {
196
+ freeWriter(tag);
197
+ throw error;
198
+ }
199
+ }
132
200
  /** Chrome writes temp entries under its TMPDIR (its singleton socket directory, its url_fetcher entries) and a Chrome that is killed removes none of
133
201
  * them, so each lease's Chrome gets a TMPDIR of its own, made under the host's, named in the profile (`.pib-tmpdir`) and removed with the lease: what
134
202
  * Chrome writes there never lands in the host's TMPDIR. The directory carries an owner file naming the lease's tag, and only a directory that names the
@@ -206,6 +274,19 @@ function leadsOwnGroup(pid) {
206
274
  return false;
207
275
  }
208
276
  }
277
+ export async function closeGracefully(port, pid, children) {
278
+ try {
279
+ const session = await cdpCall(await debuggerUrl(`http://127.0.0.1:${port}`, AbortSignal.timeout(2_000)), "Browser.close", {}, 2_000);
280
+ session.close();
281
+ }
282
+ catch { /* the browser may close its socket before it answers */ }
283
+ const child = children.get(pid);
284
+ for (const deadline = Date.now() + 8_000; Date.now() < deadline;) {
285
+ if (child ? child.exitCode !== null || child.signalCode !== null : !alive(pid))
286
+ return;
287
+ await sleep(50);
288
+ }
289
+ }
209
290
  /** A pid reaches here from a ref's id, which a restart reads back from a record: `kill(-1)` signals every process the user can,
210
291
  * `kill(0)` this process's own group, so neither a pid below 2 nor our own is ever signalled, and a negative pid (a whole group)
211
292
  * only for a process that leads one. */
@@ -248,65 +329,101 @@ export function cdpProvider(options, internals = {}) {
248
329
  };
249
330
  return {
250
331
  name: "cdp",
251
- caps: CAPS,
332
+ caps: { ...CAPS, profiles: "chrome" in options },
252
333
  ...(downloads ? { downloads } : {}),
253
- async create(spec) {
334
+ async create(spec, signal) {
254
335
  if ("endpoint" in options)
255
336
  return { id: `endpoint:${spec.tag}`, tag: spec.tag };
256
337
  const { executablePath, profileRoot, headless = true, args = [] } = options.chrome;
257
338
  const sandbox = options.chrome.sandbox ?? process.env.PI_BROWSER_NO_SANDBOX !== "1";
258
339
  const dir = profileDir(profileRoot, spec.tag);
259
- await mkdir(path.join(dir, "Default"), { recursive: true });
260
- await mkdir(downloadsDir(profileRoot, spec.tag), { recursive: true });
261
- await writeFile(path.join(dir, "Default", "Preferences"), JSON.stringify({ download: { default_directory: downloadsDir(profileRoot, spec.tag), prompt_for_download: false }, savefile: { default_directory: downloadsDir(profileRoot, spec.tag) } }));
262
- // A file left by an earlier Chrome on this profile names a browser that is not this one.
263
- await rm(path.join(dir, "DevToolsActivePort"), { force: true });
264
- const tmp = await makePrivateTmp(spec.tag, dir, remove);
265
- if (tmp)
266
- privateTmps.set(spec.tag, tmp);
267
- const child = spawn(executablePath, [
268
- ...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
269
- `--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
270
- ], { stdio: "ignore", detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
271
- // A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
272
- let failed = null;
273
- child.once("error", (error) => { failed = error; });
274
- child.once("exit", (code, signal) => {
275
- // A Chrome that cannot start its sandbox aborts (SIGABRT) before it opens a port: the signal is the fact, never
276
- // Chrome's words.
277
- failed ??= sandbox && signal === "SIGABRT"
278
- ? new BrowserFailureError({ ok: false, code: "browser_unavailable", retryable: false, effect: "none", message: `Chrome exited before it opened its debugging port (SIGABRT); on a system that cannot start Chrome's sandbox (root, a container, restricted user namespaces) start it with sandbox: false or PI_BROWSER_NO_SANDBOX=1` })
279
- : new Error(`Chrome exited before it opened its debugging port (${signal ?? code})`);
280
- });
281
- if (child.pid === undefined) {
282
- await sleep(0);
283
- const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
284
- privateTmps.delete(spec.tag);
285
- const why = failed ?? new Error("Chrome could not be started");
286
- throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
287
- }
288
- child.unref();
289
- children.set(child.pid, child);
290
- // The lease is that Chrome only once the browser answering on the port is the one its profile file names, so a
291
- // port another browser holds is never taken for it.
340
+ if (spec.profile)
341
+ await prepareProfile(profileRoot, dir, spec.profile, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal, remove);
292
342
  try {
293
- for (const deadline = Date.now() + READY_MS;; await sleep(100)) {
294
- if (failed)
295
- throw failed;
296
- const own = await ownDebugger(dir);
297
- if (own && (await answeringPath(own.port)) === own.path)
298
- return { id: `local:${child.pid}:${own.port}:${spec.tag}`, tag: spec.tag };
299
- if (Date.now() > deadline)
300
- throw new Error("Chrome did not open its debugging port");
343
+ signal?.throwIfAborted();
344
+ await mkdir(path.join(dir, "Default"), { recursive: true });
345
+ await mkdir(downloadsDir(profileRoot, spec.tag), { recursive: true });
346
+ const prefsFile = path.join(dir, "Default", "Preferences");
347
+ const prefs = await readFile(prefsFile, "utf8").then((text) => { try {
348
+ return JSON.parse(text);
349
+ }
350
+ catch {
351
+ return {};
352
+ } }, () => ({}));
353
+ // A saved profile is a browser the next session picks up. A session cookie (no Expires, like rack.session) survives a restart only when Chrome is told to
354
+ // "continue where you left off" (session.restore_on_startup = 1) before it starts, so a profile that is kept sets it; the other keys stay as they are.
355
+ const keeping = spec.profile ? { session: { ...prefs.session, restore_on_startup: 1 } } : {};
356
+ // "Continue where you left off" would also reopen the previous tabs, and each would load its old URL at launch, before the driver, its navigation policy or an
357
+ // egress guard is attached. The tab-restore files are removed before Chrome starts (the session cookies live in the cookie store, not in them), so only the
358
+ // startup page opens. Chrome writes them again as it closes, and they are removed again at the next start.
359
+ if (spec.profile) {
360
+ await rm(path.join(dir, "Default", "Sessions"), { recursive: true, force: true });
361
+ for (const legacy of ["Current Session", "Current Tabs", "Last Session", "Last Tabs"])
362
+ await rm(path.join(dir, "Default", legacy), { force: true });
363
+ }
364
+ await writeFile(prefsFile, JSON.stringify({ ...prefs, ...keeping, download: { ...prefs.download, default_directory: downloadsDir(profileRoot, spec.tag), prompt_for_download: false }, savefile: { ...prefs.savefile, default_directory: downloadsDir(profileRoot, spec.tag) } }));
365
+ // A file left by an earlier Chrome on this profile names a browser that is not this one.
366
+ await rm(path.join(dir, "DevToolsActivePort"), { force: true });
367
+ const tmp = await makePrivateTmp(spec.tag, dir, remove);
368
+ if (tmp)
369
+ privateTmps.set(spec.tag, tmp);
370
+ const child = spawn(executablePath, [
371
+ ...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
372
+ `--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
373
+ ], { stdio: "ignore", detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
374
+ // A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
375
+ let failed = null;
376
+ child.once("error", (error) => { failed = error; });
377
+ child.once("exit", (code, signal) => {
378
+ // A Chrome that cannot start its sandbox aborts (SIGABRT) before it opens a port: the signal is the fact, never
379
+ // Chrome's words.
380
+ failed ??= sandbox && signal === "SIGABRT"
381
+ ? new BrowserFailureError({ ok: false, code: "browser_unavailable", retryable: false, effect: "none", message: `Chrome exited before it opened its debugging port (SIGABRT); on a system that cannot start Chrome's sandbox (root, a container, restricted user namespaces) start it with sandbox: false or PI_BROWSER_NO_SANDBOX=1` })
382
+ : new Error(`Chrome exited before it opened its debugging port (${signal ?? code})`);
383
+ });
384
+ if (child.pid === undefined) {
385
+ await sleep(0);
386
+ const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
387
+ privateTmps.delete(spec.tag);
388
+ const why = failed ?? new Error("Chrome could not be started");
389
+ throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
390
+ }
391
+ child.unref();
392
+ children.set(child.pid, child);
393
+ // The lease is that Chrome only once the browser answering on the port is the one its profile file names, so a
394
+ // port another browser holds is never taken for it.
395
+ try {
396
+ for (const deadline = Date.now() + READY_MS;; await sleep(100)) {
397
+ if (failed)
398
+ throw failed;
399
+ const own = await ownDebugger(dir);
400
+ if (own && (await answeringPath(own.port)) === own.path) {
401
+ const pid = child.pid;
402
+ noteWriter(spec.tag, () => isOurs({ pid, port: own.port }));
403
+ return { id: `local:${pid}:${own.port}:${spec.tag}`, tag: spec.tag };
404
+ }
405
+ if (Date.now() > deadline)
406
+ throw new Error("Chrome did not open its debugging port");
407
+ }
408
+ }
409
+ catch (error) {
410
+ const kept = await this.release({ id: `local:${child.pid}:0:${spec.tag}`, tag: spec.tag }).then(() => null, (failure) => failure);
411
+ const left = await removeAll([downloadsDir(profileRoot, spec.tag)], remove);
412
+ if (kept && !(kept instanceof ProfileNotRemovedError))
413
+ throw kept;
414
+ const dirs = [...(kept instanceof ProfileNotRemovedError ? kept.dirs : []), ...(left?.dirs ?? [])];
415
+ throw dirs.length > 0 ? new ProfileNotRemovedError(dirs, kept instanceof ProfileNotRemovedError ? kept.cause : left.error, error) : error;
301
416
  }
302
417
  }
303
418
  catch (error) {
304
- const kept = await this.release({ id: `local:${child.pid}:0:${spec.tag}`, tag: spec.tag }).then(() => null, (failure) => failure);
305
- const left = await removeAll([downloadsDir(profileRoot, spec.tag)], remove);
306
- if (kept && !(kept instanceof ProfileNotRemovedError))
307
- throw kept;
308
- const dirs = [...(kept instanceof ProfileNotRemovedError ? kept.dirs : []), ...(left?.dirs ?? [])];
309
- throw dirs.length > 0 ? new ProfileNotRemovedError(dirs, kept instanceof ProfileNotRemovedError ? kept.cause : left.error, error) : error;
419
+ freeWriter(spec.tag);
420
+ if (spec.profile) {
421
+ // A reader's copy of the saved cookies stays on disk when this fails: the caller is told, with the start's own failure kept.
422
+ const left = await removeAll([dir], remove);
423
+ if (left)
424
+ throw new ProfileNotRemovedError(error instanceof ProfileNotRemovedError ? [...error.dirs, ...left.dirs] : left.dirs, left.error, error);
425
+ }
426
+ throw error;
310
427
  }
311
428
  },
312
429
  async findByTag() { return []; },
@@ -336,6 +453,7 @@ export function cdpProvider(options, internals = {}) {
336
453
  if (!local || local.tag !== ref.tag)
337
454
  return;
338
455
  const ours = await isOurs(local);
456
+ const saved = !("endpoint" in options) && SAFE_TAG.test(local.tag) && (await lstat(profileDir(options.chrome.profileRoot, local.tag)).then((info) => info.isSymbolicLink(), () => false));
339
457
  // A profile that a live browser this ref does not name still runs on is that browser's: nothing is removed. A port
340
458
  // that holds the probe past PROBE_MS cannot be ruled out, so the profile stays and the release says so.
341
459
  if (!ours && !("endpoint" in options) && SAFE_TAG.test(local.tag)) {
@@ -344,13 +462,28 @@ export function cdpProvider(options, internals = {}) {
344
462
  if (own) {
345
463
  const answer = await debuggerUrl(`http://127.0.0.1:${own.port}`, AbortSignal.timeout(PROBE_MS))
346
464
  .then((url) => new URL(url).pathname, (error) => (error instanceof Error && error.name === "TimeoutError" ? undefined : null));
347
- if (answer === own.path)
465
+ if (answer === own.path) {
466
+ if (!saved)
467
+ return;
468
+ // A saved lease's directory is a link to the profile the live browser runs on, so that browser is another lease's (a replacement
469
+ // for a crashed one): this lease's own link and private TMPDIR are still its to remove, and nothing the browser holds is.
470
+ freeWriter(local.tag);
471
+ const mine = privateTmps.get(local.tag);
472
+ const left = await removeAll([dir, ...(mine ? [mine] : [])], remove);
473
+ if (!mine || !left?.dirs.includes(mine))
474
+ privateTmps.delete(local.tag);
475
+ if (left)
476
+ throw new ProfileNotRemovedError(left.dirs, left.error);
348
477
  return;
478
+ }
349
479
  if (answer === undefined)
350
480
  throw new ProfileOwnershipUnclearError(dir, own.port);
351
481
  }
352
482
  }
353
483
  if (ours) {
484
+ // Chrome writes its cookies out on a timer and when it exits on its own: a saved profile gets the chance, then the kill.
485
+ if (saved)
486
+ await closeGracefully(local.port, local.pid, children);
354
487
  await killTree(local.pid);
355
488
  const child = children.get(local.pid);
356
489
  children.delete(local.pid);
@@ -364,6 +497,7 @@ export function cdpProvider(options, internals = {}) {
364
497
  }
365
498
  // The profile goes even after a crash; a tag that is not one path segment names nothing this provider made, so
366
499
  // nothing is removed.
500
+ freeWriter(local.tag);
367
501
  if (!("endpoint" in options) && SAFE_TAG.test(local.tag)) {
368
502
  const dir = profileDir(options.chrome.profileRoot, local.tag);
369
503
  const socketDir = await singletonDir(dir);
@@ -3,13 +3,14 @@
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
  import { readFile } from "node:fs/promises";
5
5
  import { directFetch } from "./http.js";
6
+ import { claimWriter, freeWriter, isWriter, noteWriter } from "./profiles.js";
6
7
  import { accountKey, assertTag, defaultSleep, DEFAULT_CONFIRM, extensionArchive, kernelHoldings, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
7
8
  export const KERNEL_BASE_URL = "https://api.onkernel.com";
8
9
  export const KERNEL_IDLE_MIN_S = 10;
9
10
  export const KERNEL_IDLE_MAX_S = 259_200;
10
11
  // Kernel ends a session after `timeout_seconds` with no CDP or live-view connection and sets no wall-clock limit, so
11
12
  // the lifetime cap is its largest idle timeout.
12
- const CAPS = { timeoutModel: "inactivity", maxLifetimeS: KERNEL_IDLE_MAX_S, survivesDisconnect: true, releaseIsAsync: false, extension: "uploaded-per-launch", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
13
+ const CAPS = { timeoutModel: "inactivity", maxLifetimeS: KERNEL_IDLE_MAX_S, survivesDisconnect: true, releaseIsAsync: false, profiles: true, extension: "uploaded-per-launch", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
13
14
  /** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
14
15
  * copied: an echo of the request could carry the key or a URL. */
15
16
  export class KernelError extends Error {
@@ -31,6 +32,7 @@ export function kernelCreateBody(spec, options = {}) {
31
32
  timeout_seconds: Math.min(KERNEL_IDLE_MAX_S, Math.max(KERNEL_IDLE_MIN_S, Math.round(spec.idleTimeoutS) || KERNEL_IDLE_MIN_S)),
32
33
  viewport: { width: spec.viewport.width, height: spec.viewport.height },
33
34
  tags: { ...tags, agentrun_tag: spec.tag },
35
+ ...(spec.profile ? { profile: { name: spec.profile.name, save_changes: spec.profile.save } } : {}),
34
36
  ...(options.extension ? { extensions: [options.extension] } : {}),
35
37
  };
36
38
  }
@@ -50,7 +52,7 @@ export function kernelProvider(options = {}) {
50
52
  async function call(method, route, init = {}) {
51
53
  if (!apiKey)
52
54
  throw new Error("the kernel provider needs KERNEL_API_KEY in the env it is given; none is set");
53
- const name = `${method} ${route.replace(/\/browsers\/[^/?]+/, "/browsers/{id}").replace(/\/extensions\/[^/?]+/, "/extensions/{name}")}`;
55
+ const name = `${method} ${route.replace(/\/browsers\/[^/?]+/, "/browsers/{id}").replace(/\/extensions\/[^/?]+/, "/extensions/{name}").replace(/\/profiles\/[^/?]+/, "/profiles/{name}")}`;
54
56
  const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
55
57
  let body;
56
58
  if (init.raw) {
@@ -152,6 +154,19 @@ export function kernelProvider(options = {}) {
152
154
  forget(ref.id);
153
155
  return state;
154
156
  };
157
+ const running = (ref) => async (signal) => { const now = await status(ref, signal); return now === "running" || now === "pending"; };
158
+ /** A browser can only name a profile Kernel knows. Creating it first is safe to race: a 409 means another process just did. */
159
+ const ensureProfile = async (name, signal) => {
160
+ if ((await call("GET", `/profiles/${encodeURIComponent(name)}`, { signal })).status !== 404)
161
+ return;
162
+ try {
163
+ await call("POST", "/profiles", { body: { name }, signal });
164
+ }
165
+ catch (error) {
166
+ if (error.status !== 409)
167
+ throw error;
168
+ }
169
+ };
155
170
  return {
156
171
  name: "kernel",
157
172
  caps: CAPS,
@@ -159,14 +174,27 @@ export function kernelProvider(options = {}) {
159
174
  // The upload is shared by every create on the account: a cancelled caller stops waiting, the upload goes on for
160
175
  // the rest.
161
176
  signal?.throwIfAborted();
162
- const body = kernelCreateBody(spec, { stealth: options.stealth, headless: options.headless, extension: await untilAborted(extension(), signal) });
163
- // At most once: a lost answer is found again by its tag (findByTag), never by a second create.
177
+ if (spec.profile?.save)
178
+ await claimWriter(`${account}|profile:${spec.profile.name}`, spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
179
+ let body;
180
+ try {
181
+ if (spec.profile)
182
+ await ensureProfile(spec.profile.name, signal);
183
+ body = kernelCreateBody(spec, { stealth: options.stealth, headless: options.headless, extension: await untilAborted(extension(), signal) });
184
+ }
185
+ catch (error) {
186
+ freeWriter(spec.tag);
187
+ throw error;
188
+ }
189
+ // At most once: a lost answer is found again by its tag (findByTag), never by a second create. A failed send keeps the
190
+ // profile's claim until findByTag has looked: the browser may exist.
164
191
  const created = await call("POST", "/browsers", { body, signal });
165
192
  const id = nonEmpty(created.json?.session_id);
166
193
  const url = nonEmpty(created.json?.cdp_ws_url);
167
194
  if (created.status === 404 || !id || !url)
168
195
  throw new KernelError("POST /browsers", created.status, "no_session");
169
196
  cdpUrls.set(held(id), url);
197
+ noteWriter(spec.tag, running({ id, tag: spec.tag }));
170
198
  const live = nonEmpty(created.json?.browser_live_view_url);
171
199
  if (live)
172
200
  liveUrls.set(held(id), live);
@@ -196,8 +224,14 @@ export function kernelProvider(options = {}) {
196
224
  }
197
225
  }
198
226
  // Kernel pages by headers: X-Has-More, and X-Next-Offset as the next page's absolute start.
199
- if (page.headers.get("x-has-more") !== "true")
227
+ if (page.headers.get("x-has-more") !== "true") {
228
+ if (!out.length)
229
+ freeWriter(tag);
230
+ for (const ref of out)
231
+ if (isWriter(ref.tag))
232
+ noteWriter(ref.tag, running(ref));
200
233
  return out;
234
+ }
201
235
  // More pages with no usable next offset would truncate the set custody releases: a failure, never a partial
202
236
  // answer.
203
237
  const next = Number(page.headers.get("x-next-offset"));
@@ -236,7 +270,7 @@ export function kernelProvider(options = {}) {
236
270
  await releaseAndConfirm({
237
271
  request: async () => ((await call("DELETE", `/browsers/${encodeURIComponent(ref.id)}`, { signal })).status === 404 ? "gone" : undefined),
238
272
  status: () => status(ref, signal),
239
- forget: () => forget(ref.id),
273
+ forget: () => { forget(ref.id); freeWriter(ref.tag); },
240
274
  confirm,
241
275
  sleep,
242
276
  stillRunning: `Kernel session ${ref.id} still running after its delete`,
@@ -0,0 +1,19 @@
1
+ /** Both vendors keep the last writer's state and neither locks, so within this process one session at a time may save to a
2
+ * profile. A holder that is no longer running is replaced; the same owner's successor (a relaunch asks for its replacement
3
+ * while the old session is still being released) waits for the release; anyone else is refused. */
4
+ export declare function claimWriter(key: string, name: string, tag: string, owner: string, signal?: AbortSignal): Promise<void>;
5
+ /** `running` says whether the session still runs (a probe that cannot answer in time counts as running); `settle` is what a new
6
+ * saver must wait out after finding it stopped, when the provider is still writing its state back. */
7
+ export declare function noteWriter(tag: string, running: (signal: AbortSignal) => Promise<boolean>, settle?: () => Promise<void>): void;
8
+ export declare function freeWriter(tag: string): void;
9
+ export declare function isWriter(tag: string): boolean;
10
+ /** Context ids are not secrets, and Browserbase has no way to look a context up by name, so the name to id map is the host's.
11
+ * `resolve` returns the name's context, calling `make` only when there is none, and no two callers may both make one. */
12
+ export type ProfileStore = {
13
+ resolve(key: string, make: (signal: AbortSignal) => Promise<string>): Promise<string>;
14
+ };
15
+ /** A JSON file, read, extended and written under one lock, so two processes' first uses of a name make one context; a file that is
16
+ * not this format, or cannot be read, is never overwritten. */
17
+ export declare function fileProfileStore(file?: string, options?: {
18
+ makeLimitMs?: number;
19
+ }): ProfileStore;
@@ -0,0 +1,124 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
3
+ import os from "node:os";
4
+ import path from "node:path";
5
+ import { BrowserFailureError } from "../core/custody.js";
6
+ import { withLock } from "../core/downloads.js";
7
+ const writers = new Map();
8
+ const WAIT_MS = 20_000;
9
+ const PROBE_MS = 2_000;
10
+ const refusal = (message) => new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message });
11
+ /** True when `work` finishes within `ms`; false at the deadline; rejects when `signal` aborts, leaving `work` to finish alone. */
12
+ async function waitFor(work, signal, ms) {
13
+ let timer;
14
+ let abort;
15
+ try {
16
+ return await Promise.race([
17
+ work.then(() => true),
18
+ new Promise((resolve) => { timer = setTimeout(() => resolve(false), Math.max(0, ms)); }),
19
+ new Promise((_, reject) => { if (signal) {
20
+ abort = () => reject(signal.reason);
21
+ if (signal.aborted)
22
+ abort();
23
+ else
24
+ signal.addEventListener("abort", abort, { once: true });
25
+ } }),
26
+ ]);
27
+ }
28
+ finally {
29
+ clearTimeout(timer);
30
+ if (abort)
31
+ signal?.removeEventListener("abort", abort);
32
+ }
33
+ }
34
+ /** Both vendors keep the last writer's state and neither locks, so within this process one session at a time may save to a
35
+ * profile. A holder that is no longer running is replaced; the same owner's successor (a relaunch asks for its replacement
36
+ * while the old session is still being released) waits for the release; anyone else is refused. */
37
+ export async function claimWriter(key, name, tag, owner, signal) {
38
+ for (const end = Date.now() + WAIT_MS;;) {
39
+ const held = writers.get(key);
40
+ if (!held || held.tag === tag) {
41
+ writers.set(key, { tag, owner });
42
+ return;
43
+ }
44
+ if (held.running && !(await held.running(AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(PROBE_MS)])).catch(() => true))) {
45
+ if (held.settle && !(await waitFor(held.settle(), signal, end - Date.now())))
46
+ throw refusal(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
47
+ if (writers.get(key) === held)
48
+ writers.delete(key);
49
+ continue;
50
+ }
51
+ if (held.owner !== owner)
52
+ throw refusal(`browser profile "${name}": one session at a time may save to a profile, and another session is saving to it now. Wait for it to end, or start without saving. No session was started.`);
53
+ if (Date.now() > end)
54
+ throw refusal(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
55
+ signal?.throwIfAborted();
56
+ await new Promise((resolve) => setTimeout(resolve, 100));
57
+ }
58
+ }
59
+ /** `running` says whether the session still runs (a probe that cannot answer in time counts as running); `settle` is what a new
60
+ * saver must wait out after finding it stopped, when the provider is still writing its state back. */
61
+ export function noteWriter(tag, running, settle) {
62
+ for (const held of writers.values())
63
+ if (held.tag === tag)
64
+ Object.assign(held, { running, ...(settle ? { settle } : {}) });
65
+ }
66
+ export function freeWriter(tag) {
67
+ for (const [key, held] of writers)
68
+ if (held.tag === tag)
69
+ writers.delete(key);
70
+ }
71
+ export function isWriter(tag) {
72
+ for (const held of writers.values())
73
+ if (held.tag === tag)
74
+ return true;
75
+ return false;
76
+ }
77
+ const SCHEMA = "pi-browser.profiles.v1";
78
+ const defaultProfilesFile = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "pi-browser", "profiles.json");
79
+ const notOurs = (file) => new Error(`the profiles file ${path.basename(file)} is not a pi-browser profiles file, so it was left as it is`);
80
+ async function readProfiles(file) {
81
+ let text;
82
+ try {
83
+ text = await readFile(file, "utf8");
84
+ }
85
+ catch (error) {
86
+ if (error.code === "ENOENT")
87
+ return { schema: SCHEMA, contexts: {} };
88
+ throw error;
89
+ }
90
+ try {
91
+ const parsed = JSON.parse(text);
92
+ const contexts = parsed?.contexts;
93
+ if (parsed?.schema === SCHEMA && contexts && typeof contexts === "object" && !Array.isArray(contexts) && Object.values(contexts).every((id) => typeof id === "string" && id !== ""))
94
+ return parsed;
95
+ }
96
+ catch { /* not JSON */ }
97
+ throw notOurs(file);
98
+ }
99
+ /** A JSON file, read, extended and written under one lock, so two processes' first uses of a name make one context; a file that is
100
+ * not this format, or cannot be read, is never overwritten. */
101
+ export function fileProfileStore(file = defaultProfilesFile(), options = {}) {
102
+ // The lock is taken over once it is 30 s old (core/downloads.ts's rule), so `make` must end well before: a slower one is cut here, never left
103
+ // to run past the lock that protects it.
104
+ const makeLimitMs = options.makeLimitMs ?? 20_000;
105
+ return {
106
+ async resolve(key, make) {
107
+ await mkdir(path.dirname(file), { recursive: true });
108
+ return withLock(`${file}.lock`, async () => {
109
+ const current = await readProfiles(file);
110
+ const known = current.contexts[key];
111
+ if (known)
112
+ return known;
113
+ const limit = AbortSignal.timeout(makeLimitMs);
114
+ // Listening before `make` does, so the cut's own words are what the caller hears.
115
+ const cut = new Promise((_, reject) => limit.addEventListener("abort", () => reject(new Error(`making the profile's context took longer than ${makeLimitMs} ms, so it was cut before the profiles file's lock could be taken over`)), { once: true }));
116
+ const id = await Promise.race([make(limit), cut]);
117
+ const next = `${file}.${randomBytes(4).toString("hex")}.tmp`;
118
+ await writeFile(next, `${JSON.stringify({ schema: SCHEMA, contexts: { ...current.contexts, [key]: id } }, null, 2)}\n`);
119
+ await rename(next, file);
120
+ return id;
121
+ }, "the profiles file");
122
+ },
123
+ };
124
+ }
@@ -20,7 +20,7 @@ export declare function uploadOnce<T>(uploads: Map<string, Promise<T>>, account:
20
20
  export declare function releaseAndConfirm(o: {
21
21
  request: () => Promise<"gone" | void>;
22
22
  status: () => Promise<ResourceStatus>;
23
- forget: () => void;
23
+ forget: () => void | Promise<void>;
24
24
  confirm: {
25
25
  polls: number;
26
26
  intervalMs: number;
@@ -121,9 +121,11 @@ export async function exportFrameTracks(options) {
121
121
  continue;
122
122
  let bytes;
123
123
  try {
124
- bytes = await options.readBlob(hash);
124
+ bytes = await bounded(async () => options.readBlob(hash), options, deadline);
125
125
  }
126
- catch {
126
+ catch (error) {
127
+ if (error instanceof TrackExportError)
128
+ throw error;
127
129
  bytes = null;
128
130
  }
129
131
  throwIfAborted(options.signal);
@@ -182,6 +184,25 @@ export async function exportFrameTracks(options) {
182
184
  }
183
185
  const throwIfAborted = (signal) => { if (signal?.aborted)
184
186
  throw new TrackExportError("aborted", "the export was aborted"); };
187
+ /** A read of a blob settles with the read, or fails at the session's deadline (`ffmpeg_timeout`) or at the signal (`aborted`), whichever is first: a store
188
+ * that never answers cannot hold the export past either. The read itself is not cancelled; its answer, if one ever comes, is dropped. */
189
+ function bounded(read, options, deadline) {
190
+ const { signal } = options;
191
+ return new Promise((resolve, reject) => {
192
+ if (signal?.aborted)
193
+ return reject(new TrackExportError("aborted", "the export was aborted"));
194
+ const left = deadline - Date.now();
195
+ if (left <= 0)
196
+ return reject(new TrackExportError("ffmpeg_timeout", `the export did not finish within ${options.timeoutMs ?? 120_000} ms`));
197
+ const timer = setTimeout(() => settle(() => reject(new TrackExportError("ffmpeg_timeout", `the export did not finish within ${options.timeoutMs ?? 120_000} ms`))), left);
198
+ const onAbort = () => settle(() => reject(new TrackExportError("aborted", "the export was aborted")));
199
+ let done = false;
200
+ const settle = (finish) => { if (done)
201
+ return; done = true; clearTimeout(timer); signal?.removeEventListener("abort", onAbort); finish(); };
202
+ signal?.addEventListener("abort", onAbort, { once: true });
203
+ read().then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
204
+ });
205
+ }
185
206
  const quote = (file) => `'${file.replaceAll("'", "'\\''")}'`;
186
207
  /** The layout a browser's JPEG has, and the one every picture is brought to: 4:2:0. */
187
208
  const COMMON_SAMPLING = "22,11,11";