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

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.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from "./core/contract.js";
2
+ export { BrowserFailureError, type AttachedSession, type BrowserDriver, type CustodyPort, type DriverFactory, type DriverOptions, type Overrides, type ToolOutput } from "./core/custody.js";
2
3
  export * from "./core/decisions.js";
3
4
  export * from "./core/downloads.js";
4
5
  export * from "./core/effects.js";
package/dist/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  // The host-neutral core: it imports no pi package and no host, only Node's builtins and the package's own dependencies.
2
2
  export * from "./core/contract.js";
3
+ export { BrowserFailureError } from "./core/custody.js";
3
4
  export * from "./core/decisions.js";
4
5
  export * from "./core/downloads.js";
5
6
  export * from "./core/effects.js";
@@ -11,7 +11,7 @@ export const SEARCH_QUERY_MAX = 200;
11
11
  export const SEARCH_RESULTS_MAX = 25;
12
12
  /** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
13
13
  export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
14
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, extension: "uploaded-per-launch" };
14
+ const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true } };
15
15
  const notFound = (e) => e?.status === 404;
16
16
  /** ISO alpha-2 country, US state abbreviation, upper-case city; no two-letter country, no geolocation. */
17
17
  export function browserbaseGeolocation(raw) {
@@ -41,6 +41,13 @@ export declare class ProfileOwnershipUnclearError extends Error {
41
41
  readonly code = "profile_ownership_unclear";
42
42
  constructor(dir: string, port: number);
43
43
  }
44
+ /** 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,
45
+ * `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)
46
+ * only for a process that leads one. */
47
+ export declare function killTree(pid: number, io?: {
48
+ kill?: (pid: number, signal: "SIGKILL") => void;
49
+ leadsGroup?: (pid: number) => boolean | null;
50
+ }): Promise<void>;
44
51
  /** `internals` is for tests: the removal a release uses. */
45
52
  export declare function cdpProvider(options: CdpOptions, internals?: {
46
53
  remove?: RemoveDir;
@@ -1,5 +1,7 @@
1
1
  import { execFile, spawn } from "node:child_process";
2
- import { mkdir, open, readdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
2
+ import { readFileSync } from "node:fs";
3
+ import { mkdir, mkdtemp, open, readdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
4
+ import os from "node:os";
3
5
  import path from "node:path";
4
6
  import { BrowserFailureError } from "../core/custody.js";
5
7
  import { cdpCall } from "./cdp-call.js";
@@ -32,7 +34,7 @@ const CHROME_FLAGS = [
32
34
  "--remote-allow-origins=*",
33
35
  "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
34
36
  ];
35
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, extension: "loaded-locally" };
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 } };
36
38
  const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
37
39
  const READY_MS = 20_000;
38
40
  /** 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
@@ -127,6 +129,42 @@ const profileDir = (root, tag) => {
127
129
  throw new Error("a cdp lease tag is one path segment of [A-Za-z0-9_.-]");
128
130
  return path.join(root, tag);
129
131
  };
132
+ /** 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
+ * 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
+ * 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
135
+ * tag asked for is ever removed, so a profile that names another path (a copied or hand-written one) removes nothing. Chrome aborts when its socket path
136
+ * passes 107 bytes, so a host TMPDIR too long to leave room for the private directory's name and the socket's is left as it is (Chrome inherits it). Not
137
+ * made on Windows, where Chrome's temp directory is not TMPDIR. */
138
+ const TMP_MARKER = ".pib-tmpdir";
139
+ const TMP_OWNER = ".pib-owner";
140
+ const TMP_NAME = /^pib-[A-Za-z0-9]{6}$/;
141
+ const SOCKET_PATH_MAX = 107;
142
+ const SOCKET_PATH_TAIL = "/.org.chromium.Chromium.XXXXXX/SingletonSocket".length;
143
+ async function makePrivateTmp(tag, profile, remove) {
144
+ if (process.platform === "win32")
145
+ return null;
146
+ const base = os.tmpdir();
147
+ if (Buffer.byteLength(path.join(base, "pib-XXXXXX")) + SOCKET_PATH_TAIL > SOCKET_PATH_MAX)
148
+ return null;
149
+ const dir = await mkdtemp(path.join(base, "pib-"));
150
+ try {
151
+ await writeFile(path.join(dir, TMP_OWNER), tag);
152
+ await writeFile(path.join(profile, TMP_MARKER), dir);
153
+ }
154
+ catch (error) {
155
+ // The directory is not recorded anywhere yet, so a setup that fails here removes it, and names it if it cannot.
156
+ const left = await removeTree(dir, remove);
157
+ throw left ? new ProfileNotRemovedError([dir], left.error, error) : error;
158
+ }
159
+ return dir;
160
+ }
161
+ /** The private directory the profile names, when it is one this provider made for this tag. */
162
+ async function ownedTmp(profile, tag) {
163
+ const named = (await readFile(path.join(profile, TMP_MARKER), "utf8").catch(() => "")).trim();
164
+ if (!named || !path.isAbsolute(named) || !TMP_NAME.test(path.basename(named)))
165
+ return null;
166
+ return (await readFile(path.join(named, TMP_OWNER), "utf8").catch(() => null)) === tag ? named : null;
167
+ }
130
168
  /** Signal 0 only asks; EPERM means the process exists under another user. */
131
169
  const alive = (pid) => { try {
132
170
  process.kill(pid, 0);
@@ -155,18 +193,38 @@ async function singletonDir(profile) {
155
193
  const dir = socket && path.basename(socket) === "SingletonSocket" ? path.dirname(socket) : null;
156
194
  return dir && /^\.?(org\.chromium\.Chromium|com\.google\.Chrome)\.[A-Za-z0-9]{6}$/.test(path.basename(dir)) ? dir : null;
157
195
  }
158
- async function killTree(pid) {
159
- if (process.platform === "win32")
160
- return void (await new Promise((resolve) => execFile("taskkill", ["/pid", String(pid), "/T", "/F"], () => resolve())));
196
+ /** Whether `pid` leads its own process group (Chrome is started detached, so it does); null where there is no /proc to ask. */
197
+ function leadsOwnGroup(pid) {
198
+ if (process.platform !== "linux")
199
+ return null;
161
200
  try {
162
- process.kill(-pid, "SIGKILL");
201
+ const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
202
+ // pid (comm) state ppid pgrp ...: the name may hold spaces and brackets, so the fields are counted from its last ")".
203
+ return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[2]) === pid;
163
204
  }
164
205
  catch {
206
+ return false;
207
+ }
208
+ }
209
+ /** 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
+ * `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
+ * only for a process that leads one. */
212
+ export async function killTree(pid, io = {}) {
213
+ if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid)
214
+ return;
215
+ if (process.platform === "win32")
216
+ return void (await new Promise((resolve) => execFile("taskkill", ["/pid", String(pid), "/T", "/F"], () => resolve())));
217
+ const kill = io.kill ?? ((target, signal) => process.kill(target, signal));
218
+ if ((io.leadsGroup ?? leadsOwnGroup)(pid) !== false) {
165
219
  try {
166
- process.kill(pid, "SIGKILL");
220
+ return kill(-pid, "SIGKILL");
167
221
  }
168
- catch { }
222
+ catch { /* no such group: the process alone */ }
223
+ }
224
+ try {
225
+ kill(pid, "SIGKILL");
169
226
  }
227
+ catch { /* already gone */ }
170
228
  }
171
229
  /** `internals` is for tests: the removal a release uses. */
172
230
  export function cdpProvider(options, internals = {}) {
@@ -174,9 +232,12 @@ export function cdpProvider(options, internals = {}) {
174
232
  const downloads = "chrome" in options ? localDownloads(options.chrome.profileRoot) : undefined;
175
233
  // So a release can wait for the exit it caused: an unreaped child still answers `kill 0`.
176
234
  const children = new Map();
177
- /** A socket directory a release could not remove: the profile's link that named it may go with the profile, so the next release of the
178
- * lease in this process is told it here. (A restarted process has the report's text.) */
179
- const socketsLeft = new Map();
235
+ /** Directories besides the profile (Chrome's socket directory, the lease's private TMPDIR) that a release could not remove: the profile that named
236
+ * them may go first, so the next release of the lease in this process is told them here. (A restarted process has the report's text.) */
237
+ const extrasLeft = new Map();
238
+ /** The private TMPDIR of each lease this provider started, by tag: the profile's marker is the only record a restarted process has, and a profile
239
+ * that something else removed first takes it along. */
240
+ const privateTmps = new Map();
180
241
  /** A spawned Chrome whose handle we hold is ours (a handle cannot name a recycled pid); after a restart, only while
181
242
  * the browser on the recorded port reports that pid. */
182
243
  const isOurs = async ({ pid, port }) => {
@@ -200,10 +261,13 @@ export function cdpProvider(options, internals = {}) {
200
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) } }));
201
262
  // A file left by an earlier Chrome on this profile names a browser that is not this one.
202
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);
203
267
  const child = spawn(executablePath, [
204
268
  ...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
205
269
  `--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
206
- ], { stdio: "ignore", detached: true });
270
+ ], { stdio: "ignore", detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
207
271
  // A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
208
272
  let failed = null;
209
273
  child.once("error", (error) => { failed = error; });
@@ -216,7 +280,8 @@ export function cdpProvider(options, internals = {}) {
216
280
  });
217
281
  if (child.pid === undefined) {
218
282
  await sleep(0);
219
- const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag)], remove);
283
+ const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
284
+ privateTmps.delete(spec.tag);
220
285
  const why = failed ?? new Error("Chrome could not be started");
221
286
  throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
222
287
  }
@@ -301,14 +366,19 @@ export function cdpProvider(options, internals = {}) {
301
366
  // nothing is removed.
302
367
  if (!("endpoint" in options) && SAFE_TAG.test(local.tag)) {
303
368
  const dir = profileDir(options.chrome.profileRoot, local.tag);
304
- const socketDir = (await singletonDir(dir)) ?? socketsLeft.get(local.tag) ?? null;
305
- // Both are always tried, the profile first named: the profile's link is the only place the socket directory's name is read, so it is
306
- // reported here with the profile's, not left for a later release to miss.
307
- const left = await removeAll([dir, ...(socketDir ? [socketDir] : [])], remove);
308
- if (socketDir && left?.dirs.includes(socketDir))
309
- socketsLeft.set(local.tag, socketDir);
369
+ const socketDir = await singletonDir(dir);
370
+ const tmp = privateTmps.get(local.tag) ?? await ownedTmp(dir, local.tag);
371
+ // All are always tried, the profile first named: the profile's link and marker are the only places the other directories' names are read, so
372
+ // they are reported here with the profile's, not left for a later release to miss.
373
+ const extras = [...new Set([...(socketDir ? [socketDir] : []), ...(tmp ? [tmp] : []), ...(extrasLeft.get(local.tag) ?? [])])];
374
+ const left = await removeAll([dir, ...extras], remove);
375
+ const stuck = extras.filter((extra) => left?.dirs.includes(extra));
376
+ if (stuck.length > 0)
377
+ extrasLeft.set(local.tag, stuck);
310
378
  else
311
- socketsLeft.delete(local.tag);
379
+ extrasLeft.delete(local.tag);
380
+ if (!tmp || !stuck.includes(tmp))
381
+ privateTmps.delete(local.tag);
312
382
  if (left)
313
383
  throw new ProfileNotRemovedError(left.dirs, left.error);
314
384
  }
@@ -9,7 +9,7 @@ export const KERNEL_IDLE_MIN_S = 10;
9
9
  export const KERNEL_IDLE_MAX_S = 259_200;
10
10
  // Kernel ends a session after `timeout_seconds` with no CDP or live-view connection and sets no wall-clock limit, so
11
11
  // 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" };
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
13
  /** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
14
14
  * copied: an echo of the request could carry the key or a URL. */
15
15
  export class KernelError extends Error {
@@ -1,3 +1,4 @@
1
1
  export { frameRecorder, type FrameData, type FrameGapData, type FrameLine, type FrameRecorder, type FrameRecorderOptions, type FrameSink } from "./frames.js";
2
2
  export { CREDENTIAL_PROBE } from "./credential.js";
3
3
  export { jpegSize } from "./jpeg.js";
4
+ export { exportFrameTracks, planTrack, TrackExportError, type FrameTrackData, type FrameTrackLine, type Track, type TrackFrame, type TrackGap, type TrackIndex, type TrackOptions, type TrackPlan, type TrackSegment } from "./track.js";
@@ -4,3 +4,4 @@
4
4
  export { frameRecorder } from "./frames.js";
5
5
  export { CREDENTIAL_PROBE } from "./credential.js";
6
6
  export { jpegSize } from "./jpeg.js";
7
+ export { exportFrameTracks, planTrack, TrackExportError } from "./track.js";
@@ -3,3 +3,6 @@ export declare function jpegSize(bytes: Uint8Array): {
3
3
  w: number;
4
4
  h: number;
5
5
  } | null;
6
+ /** The sampling factors the first start-of-frame segment states for each component, as hex pairs joined by commas ("22,11,11" is 4:2:0, the layout
7
+ * a browser's JPEG has; "11" is grayscale), or null when it states none. */
8
+ export declare function jpegSampling(bytes: Uint8Array): string | null;
@@ -32,3 +32,39 @@ export function jpegSize(bytes) {
32
32
  }
33
33
  return null;
34
34
  }
35
+ /** The sampling factors the first start-of-frame segment states for each component, as hex pairs joined by commas ("22,11,11" is 4:2:0, the layout
36
+ * a browser's JPEG has; "11" is grayscale), or null when it states none. */
37
+ export function jpegSampling(bytes) {
38
+ if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
39
+ return null;
40
+ let at = 2;
41
+ while (at + 4 <= bytes.length) {
42
+ if (bytes[at] !== 0xff) {
43
+ at += 1;
44
+ continue;
45
+ }
46
+ const marker = bytes[at + 1];
47
+ if (marker === 0xff) {
48
+ at += 1;
49
+ continue;
50
+ }
51
+ if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01) {
52
+ at += 2;
53
+ continue;
54
+ }
55
+ if (marker === 0xd9 || marker === 0xda)
56
+ return null;
57
+ const length = (bytes[at + 2] << 8) | bytes[at + 3];
58
+ if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
59
+ const count = bytes[at + 9];
60
+ if (count === undefined || count < 1 || at + 10 + count * 3 > bytes.length)
61
+ return null;
62
+ const factors = [];
63
+ for (let i = 0; i < count; i += 1)
64
+ factors.push(bytes[at + 10 + i * 3 + 1].toString(16).padStart(2, "0"));
65
+ return factors.join(",");
66
+ }
67
+ at += 2 + length;
68
+ }
69
+ return null;
70
+ }
@@ -0,0 +1,107 @@
1
+ /** `frame.track`: written at export, one per session. The blobs are the WebM and its index, in that order. */
2
+ export type FrameTrackData = {
3
+ session: string;
4
+ fps: number;
5
+ from: number;
6
+ to: number;
7
+ };
8
+ export type FrameTrackLine = {
9
+ channel: "live";
10
+ source: "browser";
11
+ kind: "frame.track";
12
+ t: number;
13
+ conv: number;
14
+ data: FrameTrackData;
15
+ blobs: [string, string];
16
+ };
17
+ /** One stretch of the track: a frame shown, or the slate (`sha256` null) while the session had no frame to show. Times are the recording's. */
18
+ export type TrackSegment = {
19
+ start: number;
20
+ end: number;
21
+ sha256: string | null;
22
+ reason?: string;
23
+ };
24
+ export type TrackFrame = {
25
+ t: number;
26
+ ms: number;
27
+ sha256: string;
28
+ w: number;
29
+ h: number;
30
+ };
31
+ export type TrackGap = {
32
+ from: number;
33
+ to: number;
34
+ reason: string;
35
+ detail?: string;
36
+ };
37
+ export type TrackPlan = {
38
+ session: string;
39
+ conv: number;
40
+ fps: number;
41
+ from: number;
42
+ to: number;
43
+ width: number;
44
+ height: number;
45
+ segments: TrackSegment[];
46
+ frames: TrackFrame[];
47
+ gaps: TrackGap[];
48
+ };
49
+ /** The index blob: where each frame and each gap is, so a viewer maps a time in the recording (`t`) to a time in the video (`t - from`). */
50
+ export type TrackIndex = {
51
+ version: 1;
52
+ session: string;
53
+ fps: number;
54
+ from: number;
55
+ to: number;
56
+ width: number;
57
+ height: number;
58
+ codec: "vp9";
59
+ frames: TrackFrame[];
60
+ gaps: TrackGap[];
61
+ };
62
+ export declare class TrackExportError extends Error {
63
+ readonly code: "ffmpeg_missing" | "ffmpeg_failed" | "ffmpeg_timeout" | "aborted";
64
+ constructor(code: TrackExportError["code"], message: string);
65
+ }
66
+ /** The timeline of one session's lines. Each frame is shown until the next one; a gap puts the slate up (from the moment it was written, except
67
+ * `process_killed`, which starts at the last frame the earlier process saved: nothing is known after it) until the next frame or the end.
68
+ * Null when the session has no frame. `skip` names frames whose picture could not be read: they show the slate and are not listed. */
69
+ export declare function planTrack(lines: Iterable<unknown>, options?: {
70
+ fps?: number;
71
+ endAt?: number;
72
+ skip?: ReadonlySet<string>;
73
+ }): TrackPlan | null;
74
+ export type TrackOptions = {
75
+ /** The recording's lines; `frame` and `frame.gap` of every session are read, anything else is ignored. */
76
+ lines: Iterable<unknown>;
77
+ /** The bytes of a blob by its sha256 (the JPEG a `frame` line names); null or a throw: not there. */
78
+ readBlob: (sha256: string) => Uint8Array | null | undefined | Promise<Uint8Array | null | undefined>;
79
+ fps?: number;
80
+ /** When the recording ended, in its own ms: the last frame or slate is shown until then. */
81
+ endAt?: number;
82
+ /** The program to start; default `ffmpeg` on the PATH. */
83
+ ffmpeg?: string;
84
+ /** For each session's encoding; default 120 s. */
85
+ timeoutMs?: number;
86
+ signal?: AbortSignal;
87
+ };
88
+ export type Track = {
89
+ line: FrameTrackLine;
90
+ /** The video and the index, by sha256: the host keeps the first as `blobs/<sha256>.webm` and the second as `blobs/<sha256>.json`. */
91
+ blobs: Record<string, Uint8Array>;
92
+ files: {
93
+ webm: string;
94
+ index: string;
95
+ };
96
+ index: TrackIndex;
97
+ /** Frames the track could not use, shown as the slate: `missing` (no such blob), `hash_mismatch`, `not_a_jpeg`. */
98
+ skipped: Array<{
99
+ sha256: string;
100
+ reason: "missing" | "hash_mismatch" | "not_a_jpeg";
101
+ }>;
102
+ };
103
+ /** One WebM (VP9) and one index per session that has a frame. A session's pictures are read one at a time and written straight to a private temporary
104
+ * directory made for the session and removed after, so memory holds one picture at a time (not every picture of the recording), and ffmpeg reads
105
+ * only files there: it is started with a short environment, not given a URL, and nothing it writes reaches the recording but the video. `readBlob`
106
+ * may be asked for the same blob again by another session. */
107
+ export declare function exportFrameTracks(options: TrackOptions): Promise<Track[]>;