@rezkam/browser-tools 1.0.3 → 1.1.0
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/CHANGELOG.md +14 -0
- package/README.md +95 -48
- package/bin/browser-tools.mjs +2 -0
- package/package.json +4 -2
- package/scripts/browser-control.mjs +265 -39
- package/scripts/browser-platform.mjs +96 -0
- package/scripts/serve.mjs +42 -0
- package/scripts/stop.mjs +3 -3
- package/scripts/tab-broker.mjs +351 -0
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { createHash, randomUUID } from 'node:crypto';
|
|
2
2
|
import { spawn, spawnSync } from 'node:child_process';
|
|
3
|
+
import { createConnection } from 'node:net';
|
|
3
4
|
import {
|
|
4
5
|
accessSync,
|
|
5
6
|
chmodSync,
|
|
@@ -16,13 +17,16 @@ import { homedir, tmpdir } from 'node:os';
|
|
|
16
17
|
import { delimiter, dirname, join, resolve } from 'node:path';
|
|
17
18
|
import { fileURLToPath } from 'node:url';
|
|
18
19
|
import puppeteer from 'puppeteer-core';
|
|
20
|
+
import WebSocket from 'ws';
|
|
21
|
+
import { discoverChromeBinary, discoverChromeSourceDir, chromePlatformToken } from './browser-platform.mjs';
|
|
19
22
|
|
|
20
23
|
export const DEFAULT_PORT = 9222;
|
|
21
24
|
export const CONNECT_PROBE_TIMEOUT_MS = 3000;
|
|
25
|
+
export const PORT_OCCUPANCY_PROBE_TIMEOUT_MS = 250;
|
|
22
26
|
export const CHROME_READY_TIMEOUT_MS = 15000;
|
|
23
27
|
export const CHROME_READY_PROBE_TIMEOUT_MS = 250;
|
|
24
|
-
export const DEFAULT_CHROME_BIN = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
|
|
25
|
-
export const DEFAULT_CHROME_SRC = join(homedir(), '
|
|
28
|
+
export const DEFAULT_CHROME_BIN = discoverChromeBinary() || (process.platform === 'linux' ? 'google-chrome' : '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome');
|
|
29
|
+
export const DEFAULT_CHROME_SRC = discoverChromeSourceDir({ chromeBin: DEFAULT_CHROME_BIN }) || join(homedir(), '.config', 'google-chrome');
|
|
26
30
|
export const DEFAULT_CACHE_DIR = join(homedir(), '.cache', 'pi-browser-tools');
|
|
27
31
|
export const DEFAULT_ARTIFACT_DIR = tmpdir();
|
|
28
32
|
|
|
@@ -49,7 +53,7 @@ export const MAX_BROWSERS_ENV = 'BROWSER_TOOLS_MAX_BROWSERS';
|
|
|
49
53
|
// A managed browser older than this is almost certainly a leftover from a finished agent session.
|
|
50
54
|
export const STALE_BROWSER_AGE_MS = 2 * 60 * 60 * 1000;
|
|
51
55
|
export const PENDING_BROWSER_STATE_MAX_AGE_MS = 5000;
|
|
52
|
-
export const REAP_HINT = 'Run scripts/stop.mjs --reap to sweep managed browsers
|
|
56
|
+
export const REAP_HINT = 'Run scripts/stop.mjs --reap to sweep reclaimable managed browsers whose lifecycle tracking or launcher lease has expired.';
|
|
53
57
|
|
|
54
58
|
export function agentConfigRoot() {
|
|
55
59
|
return process.env.AGENT_CONFIG_DIR || join(homedir(), '.agents');
|
|
@@ -82,11 +86,12 @@ export function expandHomePath(value) {
|
|
|
82
86
|
export function browserToolsRuntimeConfig({ configDir = browserToolsConfigDir() } = {}) {
|
|
83
87
|
const effectiveConfigDir = resolveBrowserToolsConfigDir(configDir);
|
|
84
88
|
const config = safeReadJson(browserToolsConfigFile(effectiveConfigDir)) || {};
|
|
89
|
+
const chromeBin = expandHomePath(process.env.BROWSER_TOOLS_CHROME_BIN || config.browser?.chromeBin || config.chromeBin || discoverChromeBinary() || DEFAULT_CHROME_BIN);
|
|
85
90
|
return {
|
|
86
91
|
configDir: effectiveConfigDir,
|
|
87
92
|
configFile: browserToolsConfigFile(effectiveConfigDir),
|
|
88
|
-
chromeBin
|
|
89
|
-
chromeSourceDir: expandHomePath(process.env.BROWSER_TOOLS_CHROME_SOURCE_DIR || config.directories?.chromeSourceDir || config.sourceDir || DEFAULT_CHROME_SRC),
|
|
93
|
+
chromeBin,
|
|
94
|
+
chromeSourceDir: expandHomePath(process.env.BROWSER_TOOLS_CHROME_SOURCE_DIR || config.directories?.chromeSourceDir || config.sourceDir || discoverChromeSourceDir({ chromeBin }) || DEFAULT_CHROME_SRC),
|
|
90
95
|
cacheDir: expandHomePath(process.env.BROWSER_TOOLS_CACHE_DIR || config.directories?.cacheDir || DEFAULT_CACHE_DIR),
|
|
91
96
|
artifactDir: expandHomePath(process.env.BROWSER_TOOLS_ARTIFACT_DIR || config.directories?.artifactDir || DEFAULT_ARTIFACT_DIR),
|
|
92
97
|
maxBrowsers: config.browser?.maxBrowsers ?? config.maxBrowsers ?? null,
|
|
@@ -377,7 +382,7 @@ export async function browserWSEndpoint(port = DEFAULT_PORT, timeoutMs = CONNECT
|
|
|
377
382
|
const controller = new AbortController();
|
|
378
383
|
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
379
384
|
try {
|
|
380
|
-
const res = await fetch(`http://
|
|
385
|
+
const res = await fetch(`http://127.0.0.1:${normalizedPort}/json/version`, { signal: controller.signal });
|
|
381
386
|
if (!res.ok) return null;
|
|
382
387
|
const data = await res.json();
|
|
383
388
|
return data.webSocketDebuggerUrl ?? null;
|
|
@@ -388,18 +393,114 @@ export async function browserWSEndpoint(port = DEFAULT_PORT, timeoutMs = CONNECT
|
|
|
388
393
|
}
|
|
389
394
|
}
|
|
390
395
|
|
|
391
|
-
|
|
396
|
+
/**
|
|
397
|
+
* Detect any local listener, not just a responsive CDP endpoint. A normal Chrome
|
|
398
|
+
* can occupy the preferred debugging port without exposing a usable
|
|
399
|
+
* /json/version response, and launching against that port otherwise fails only
|
|
400
|
+
* after the full readiness timeout. Unexpected probe errors are treated as
|
|
401
|
+
* occupied so an uncertain port is never handed to Chrome.
|
|
402
|
+
*/
|
|
403
|
+
function tcpListenerOnHost(port, host, timeoutMs) {
|
|
404
|
+
return new Promise((resolvePromise) => {
|
|
405
|
+
const socket = createConnection({ host, port });
|
|
406
|
+
let settled = false;
|
|
407
|
+
const finish = (occupied) => {
|
|
408
|
+
if (settled) return;
|
|
409
|
+
settled = true;
|
|
410
|
+
socket.destroy();
|
|
411
|
+
resolvePromise(occupied);
|
|
412
|
+
};
|
|
413
|
+
socket.once('connect', () => finish(true));
|
|
414
|
+
socket.once('error', (error) => {
|
|
415
|
+
const code = error && typeof error === 'object' ? error.code : undefined;
|
|
416
|
+
finish(!['ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL', 'EAFNOSUPPORT', 'EPROTONOSUPPORT', 'ENOTSUP'].includes(code));
|
|
417
|
+
});
|
|
418
|
+
socket.setTimeout(timeoutMs, () => finish(true));
|
|
419
|
+
});
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
export async function isPortOccupied(port = DEFAULT_PORT, timeoutMs = PORT_OCCUPANCY_PROBE_TIMEOUT_MS) {
|
|
423
|
+
const normalizedPort = normalizePort(port);
|
|
424
|
+
const [ipv4, ipv6] = await Promise.all([
|
|
425
|
+
tcpListenerOnHost(normalizedPort, '127.0.0.1', timeoutMs),
|
|
426
|
+
tcpListenerOnHost(normalizedPort, '::1', timeoutMs),
|
|
427
|
+
]);
|
|
428
|
+
return ipv4 || ipv6;
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
export function devToolsActivePortMatches(userDataDir, endpoint) {
|
|
432
|
+
if (!userDataDir || !endpoint) return false;
|
|
433
|
+
try {
|
|
434
|
+
const url = new URL(endpoint);
|
|
435
|
+
const activePortFile = readFileSync(join(userDataDir, 'DevToolsActivePort'), 'utf8').trim().split(/\r?\n/);
|
|
436
|
+
const endpointPort = url.port || (url.protocol === 'ws:' ? '80' : url.protocol === 'wss:' ? '443' : '');
|
|
437
|
+
return activePortFile[0] === endpointPort && activePortFile[1] === url.pathname;
|
|
438
|
+
} catch {
|
|
439
|
+
return false;
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
// Fixed-port Chromium need not write DevToolsActivePort. A loopback URL alone is
|
|
444
|
+
// not ownership proof: ask the endpoint for its actual browser launch arguments.
|
|
445
|
+
export async function launchedEndpointMatches({ port, endpoint, state, timeoutMs = 3000 }) {
|
|
446
|
+
let url;
|
|
447
|
+
try { url = new URL(endpoint); } catch { return false; }
|
|
448
|
+
if (url.hash || url.username || url.password || url.protocol !== 'ws:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
|
|
449
|
+
|| Number(url.port) !== Number(port) || !url.pathname.startsWith('/devtools/browser/')) return false;
|
|
450
|
+
if (devToolsActivePortMatches(state?.userDataDir, endpoint)) return true;
|
|
451
|
+
if (!state?.managedToken || !state?.userDataDir) return false;
|
|
452
|
+
return new Promise((resolve) => {
|
|
453
|
+
let socket;
|
|
454
|
+
try { socket = new WebSocket(endpoint, { followRedirects: false, handshakeTimeout: timeoutMs, maxPayload: 1024 * 1024 }); }
|
|
455
|
+
catch { resolve(false); return; }
|
|
456
|
+
let settled = false;
|
|
457
|
+
const finish = (ok) => {
|
|
458
|
+
if (settled) return;
|
|
459
|
+
settled = true;
|
|
460
|
+
clearTimeout(timer);
|
|
461
|
+
socket.terminate();
|
|
462
|
+
resolve(ok);
|
|
463
|
+
};
|
|
464
|
+
const timer = setTimeout(() => finish(false), timeoutMs);
|
|
465
|
+
socket.on('error', () => finish(false));
|
|
466
|
+
socket.on('close', () => finish(false));
|
|
467
|
+
socket.on('open', () => socket.send(JSON.stringify({ id: 1, method: 'Browser.getBrowserCommandLine' })));
|
|
468
|
+
socket.on('message', (data) => {
|
|
469
|
+
try {
|
|
470
|
+
const message = JSON.parse(data.toString());
|
|
471
|
+
if (message.id !== 1) return;
|
|
472
|
+
const args = message.result?.arguments;
|
|
473
|
+
finish(Array.isArray(args) && [
|
|
474
|
+
'--enable-automation',
|
|
475
|
+
'--remote-debugging-port=' + port,
|
|
476
|
+
'--user-data-dir=' + state.userDataDir,
|
|
477
|
+
'--pi-browser-tools-managed=' + state.managedToken,
|
|
478
|
+
].every(arg => args.includes(arg)));
|
|
479
|
+
} catch { finish(false); }
|
|
480
|
+
});
|
|
481
|
+
});
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
export async function waitForChromeEndpoint(
|
|
392
485
|
port = DEFAULT_PORT,
|
|
393
486
|
{ timeoutMs = CHROME_READY_TIMEOUT_MS, intervalMs = 250, probeTimeoutMs = CHROME_READY_PROBE_TIMEOUT_MS } = {},
|
|
394
487
|
) {
|
|
395
488
|
const deadline = Date.now() + timeoutMs;
|
|
396
489
|
while (Date.now() < deadline) {
|
|
397
490
|
const remainingMs = Math.max(1, deadline - Date.now());
|
|
398
|
-
|
|
491
|
+
const endpoint = await browserWSEndpoint(port, Math.min(probeTimeoutMs, remainingMs));
|
|
492
|
+
if (endpoint) return endpoint;
|
|
399
493
|
const sleepMs = Math.min(intervalMs, Math.max(0, deadline - Date.now()));
|
|
400
494
|
if (sleepMs > 0) await sleep(sleepMs);
|
|
401
495
|
}
|
|
402
|
-
return
|
|
496
|
+
return null;
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
export async function waitForChromeReady(
|
|
500
|
+
port = DEFAULT_PORT,
|
|
501
|
+
options = {},
|
|
502
|
+
) {
|
|
503
|
+
return Boolean(await waitForChromeEndpoint(port, options));
|
|
403
504
|
}
|
|
404
505
|
|
|
405
506
|
export function profileCopyReady(profileName, profileDataDir = profileDataDirForPort()) {
|
|
@@ -764,6 +865,7 @@ export function syncChromeProfile(profileName, { force = false, port = DEFAULT_P
|
|
|
764
865
|
const cachedMatches = cachedState
|
|
765
866
|
&& typeof cachedState.includeGoogle === 'boolean'
|
|
766
867
|
&& cachedState.includeGoogle === includeGoogle
|
|
868
|
+
&& cachedState.sourceDir && resolve(cachedState.sourceDir) === resolve(sourceDir)
|
|
767
869
|
&& (includeGoogle || cachedState.googleStripOk === true);
|
|
768
870
|
if (!force && cachedMatches && profileCopyReady(profileName, destDir)) {
|
|
769
871
|
removeChromeProfileLocks(destDir);
|
|
@@ -773,11 +875,12 @@ export function syncChromeProfile(profileName, { force = false, port = DEFAULT_P
|
|
|
773
875
|
const commands = profileSyncRsyncCommands(profileName, { sourceDir, destDir, checkExists: true });
|
|
774
876
|
|
|
775
877
|
rmSync(destDir, { recursive: true, force: true });
|
|
776
|
-
mkdirSync(destDir, { recursive: true });
|
|
878
|
+
mkdirSync(destDir, { recursive: true, mode: 0o700 });
|
|
879
|
+
chmodSync(destDir, 0o700);
|
|
777
880
|
const results = [];
|
|
778
881
|
const copiedItems = [];
|
|
779
882
|
for (const command of commands) {
|
|
780
|
-
mkdirSync(command.dest, { recursive: true });
|
|
883
|
+
mkdirSync(command.dest, { recursive: true, mode: 0o700 });
|
|
781
884
|
const result = spawnSync('rsync', command.args, { stdio: 'inherit' });
|
|
782
885
|
if (result.error) throw result.error;
|
|
783
886
|
if (result.signal) throw new Error(`rsync failed for ${command.item}: terminated by signal ${result.signal}`);
|
|
@@ -911,6 +1014,8 @@ export function chromeLaunchArgs({ port = DEFAULT_PORT, profileName = null, mana
|
|
|
911
1014
|
const args = [
|
|
912
1015
|
`--remote-debugging-port=${normalizedPort}`,
|
|
913
1016
|
`--user-data-dir=${launchUserDataDir}`,
|
|
1017
|
+
'--remote-debugging-address=127.0.0.1',
|
|
1018
|
+
'--enable-automation',
|
|
914
1019
|
'--no-first-run',
|
|
915
1020
|
'--no-default-browser-check',
|
|
916
1021
|
'--disable-sync',
|
|
@@ -943,7 +1048,7 @@ export function detectChromeMajorVersion(chromeBin = browserToolsChromeBin()) {
|
|
|
943
1048
|
// so this matches what a windowed macOS Chrome sends. It carries no machine-specific data.
|
|
944
1049
|
export function chromeUserAgentForMajor(major) {
|
|
945
1050
|
if (!Number.isInteger(major) || major < 1) return null;
|
|
946
|
-
return `Mozilla/5.0 (
|
|
1051
|
+
return `Mozilla/5.0 (${chromePlatformToken()}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36`;
|
|
947
1052
|
}
|
|
948
1053
|
|
|
949
1054
|
export function headlessUserAgent(chromeBin = browserToolsChromeBin()) {
|
|
@@ -1077,7 +1182,7 @@ export function managedBrowserIdentityMatches(expected, current) {
|
|
|
1077
1182
|
export function verifyManagedChromePid(pid, { cacheDir = browserToolsCacheDir(), chromeBin = browserToolsChromeBin() } = {}) {
|
|
1078
1183
|
const command = commandForPid(pid);
|
|
1079
1184
|
if (!command) return null;
|
|
1080
|
-
return managedChromeProcessFromCommand({ pid, command, cacheDir, chromeBin });
|
|
1185
|
+
return managedChromeProcessFromCommand({ pid, command: command.replaceAll('\0', ' ').trim(), cacheDir, chromeBin });
|
|
1081
1186
|
}
|
|
1082
1187
|
|
|
1083
1188
|
// The live inventory of managed browsers. This reads the process table rather than the lifecycle
|
|
@@ -1212,6 +1317,21 @@ export function staleManagedBrowsers(processes = listManagedChromeProcesses(), {
|
|
|
1212
1317
|
return processes.filter((entry) => Number.isFinite(entry.ageMs) && entry.ageMs >= maxAgeMs);
|
|
1213
1318
|
}
|
|
1214
1319
|
|
|
1320
|
+
function managedBrowserLauncherIsActive(state) {
|
|
1321
|
+
const launcherPid = Number(state?.launchedByPid);
|
|
1322
|
+
if (!Number.isInteger(launcherPid) || launcherPid < 1) return false;
|
|
1323
|
+
const recordedIdentity = typeof state?.launchedByProcessStartIdentity === 'string'
|
|
1324
|
+
? state.launchedByProcessStartIdentity
|
|
1325
|
+
: null;
|
|
1326
|
+
if (!recordedIdentity) return processExists(launcherPid);
|
|
1327
|
+
|
|
1328
|
+
const currentIdentity = processStartIdentity(launcherPid);
|
|
1329
|
+
if (currentIdentity) return currentIdentity === recordedIdentity;
|
|
1330
|
+
// A transient process-table read failure must fail closed. Only consider the launcher gone when
|
|
1331
|
+
// the independent process existence check agrees that the PID no longer exists.
|
|
1332
|
+
return processExists(launcherPid);
|
|
1333
|
+
}
|
|
1334
|
+
|
|
1215
1335
|
function readManagedPid(pidFile) {
|
|
1216
1336
|
try {
|
|
1217
1337
|
const pid = Number.parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
|
|
@@ -1221,8 +1341,8 @@ function readManagedPid(pidFile) {
|
|
|
1221
1341
|
}
|
|
1222
1342
|
}
|
|
1223
1343
|
|
|
1224
|
-
//
|
|
1225
|
-
//
|
|
1344
|
+
// Managed browsers the reaper may safely reclaim. This includes browsers whose lifecycle files no
|
|
1345
|
+
// longer describe them, unowned browsers, and old browsers whose recorded launcher has exited.
|
|
1226
1346
|
export function orphanedManagedBrowsers(processes = listManagedChromeProcesses()) {
|
|
1227
1347
|
return processes.filter((entry) => {
|
|
1228
1348
|
// A concurrent start holds the port lock from before the spawn until the readiness probe passes,
|
|
@@ -1245,6 +1365,13 @@ export function orphanedManagedBrowsers(processes = listManagedChromeProcesses()
|
|
|
1245
1365
|
// An unowned browser is tracked but unreachable: its owner token lives only in the caller that
|
|
1246
1366
|
// started it, so once that process exits nothing can adopt or stop it. Reclaim it as garbage.
|
|
1247
1367
|
if (!normalizeOwnerValue(state.ownerId)) return true;
|
|
1368
|
+
// Ownership cannot make a leaked browser immortal. Once the browser is old enough to be stale
|
|
1369
|
+
// and the process that launched it is gone, no live owner process remains to close it.
|
|
1370
|
+
if (
|
|
1371
|
+
Number.isFinite(entry.ageMs) &&
|
|
1372
|
+
entry.ageMs >= STALE_BROWSER_AGE_MS &&
|
|
1373
|
+
!managedBrowserLauncherIsActive(state)
|
|
1374
|
+
) return true;
|
|
1248
1375
|
return false;
|
|
1249
1376
|
});
|
|
1250
1377
|
}
|
|
@@ -1253,9 +1380,9 @@ export function forcedKillStatus(exited) {
|
|
|
1253
1380
|
return exited ? 'killed' : 'failed';
|
|
1254
1381
|
}
|
|
1255
1382
|
|
|
1256
|
-
// Kill managed browsers
|
|
1257
|
-
//
|
|
1258
|
-
//
|
|
1383
|
+
// Kill reclaimable managed browsers. Safe by construction: every target came from
|
|
1384
|
+
// parseManagedChromeProcesses, so it carries our managed token and a user-data-dir inside our cache
|
|
1385
|
+
// dir. Old tracked browsers are eligible only after their launcher exits and the grace period ends.
|
|
1259
1386
|
export function reapOrphanedChromes({ dryRun = false, processes = listManagedChromeProcesses() } = {}) {
|
|
1260
1387
|
const orphans = orphanedManagedBrowsers(processes);
|
|
1261
1388
|
const reaped = [];
|
|
@@ -1312,7 +1439,7 @@ function describeBrowserInventory(processes, { limit = 10, staleMaxAgeMs = STALE
|
|
|
1312
1439
|
const lines = processes.slice(0, limit).map((entry) => {
|
|
1313
1440
|
const stale = Number.isFinite(entry.ageMs) && entry.ageMs >= staleMaxAgeMs;
|
|
1314
1441
|
const pid = Number.isInteger(Number(entry.pid)) ? `PID ${entry.pid}` : 'PID unknown';
|
|
1315
|
-
return ` :${entry.port} ${pid} up ${formatBrowserAge(entry.ageMs)}${stale ? ' <-
|
|
1442
|
+
return ` :${entry.port} ${pid} up ${formatBrowserAge(entry.ageMs)}${stale ? ' <- running over 2h, likely a leftover' : ''}`;
|
|
1316
1443
|
});
|
|
1317
1444
|
if (processes.length > limit) lines.push(` ... and ${processes.length - limit} more`);
|
|
1318
1445
|
return lines.join('\n');
|
|
@@ -1335,7 +1462,7 @@ export function assertManagedBrowserCapacity({ processes = listManagedChromeProc
|
|
|
1335
1462
|
staleLine +
|
|
1336
1463
|
`\n To continue, do one of these:\n` +
|
|
1337
1464
|
` scripts/stop.mjs --status see this list again at any time\n` +
|
|
1338
|
-
` scripts/stop.mjs --reap --dry-run preview
|
|
1465
|
+
` scripts/stop.mjs --reap --dry-run preview reclaimable leaked browsers\n` +
|
|
1339
1466
|
` scripts/stop.mjs --prune reap those, then drop their unused clones\n` +
|
|
1340
1467
|
` scripts/stop.mjs --port <n> --owner-token "$${OWNER_TOKEN_ENV}" stop one you own\n\n` +
|
|
1341
1468
|
` Best fix if these are yours: export ${OWNER_TOKEN_ENV} from the first start, and later\n` +
|
|
@@ -1366,7 +1493,8 @@ export function managedBrowserStartupWarnings({
|
|
|
1366
1493
|
`${stale.length} managed browser${stale.length === 1 ? '' : 's'} ${stale.length === 1 ? 'has' : 'have'} been running over ${hours}h ` +
|
|
1367
1494
|
`(${describePorts(stale)}), likely left over from a finished session. ` +
|
|
1368
1495
|
`Stop a tracked browser with scripts/stop.mjs --port <n> --owner-token "$${OWNER_TOKEN_ENV}". ` +
|
|
1369
|
-
`
|
|
1496
|
+
`Old sessions whose launcher has exited are reclaimed automatically by the next start. ` +
|
|
1497
|
+
`Use scripts/stop.mjs --reap --dry-run to preview all reclaimable sessions.`,
|
|
1370
1498
|
);
|
|
1371
1499
|
}
|
|
1372
1500
|
return warnings;
|
|
@@ -1397,6 +1525,7 @@ export function managedBrowserReuseDecision({
|
|
|
1397
1525
|
// Adopting a browser built from a different profile (or a fresh, signed-out clone) would run the
|
|
1398
1526
|
// caller's automation against the wrong account.
|
|
1399
1527
|
if ((state?.profileName || null) !== (profileName || null)) return fail('profile-mismatch');
|
|
1528
|
+
if (profileName && (!state.profileSourceDir || resolve(state.profileSourceDir) !== resolve(browserToolsChromeSourceDir()))) return fail('profile-source-mismatch');
|
|
1400
1529
|
// Headless is fixed at launch, so a windowed request cannot be served by a headless browser.
|
|
1401
1530
|
if (Boolean(state?.headless) !== Boolean(headless)) return fail('headless-mismatch');
|
|
1402
1531
|
return { ok: true, ownerId: ownership.ownerId, state };
|
|
@@ -1496,7 +1625,14 @@ export function launchChrome({ port = DEFAULT_PORT, profileName = null, userData
|
|
|
1496
1625
|
const chromeBin = browserToolsChromeBin();
|
|
1497
1626
|
const userAgent = headless ? headlessUserAgent(chromeBin) : null;
|
|
1498
1627
|
const args = chromeLaunchArgs({ port: normalizedPort, profileName, managedToken, userDataDir: launchUserDataDir, headless, userAgent });
|
|
1628
|
+
// A stale marker must not make a later launch appear to own a competing endpoint.
|
|
1629
|
+
rmSync(join(launchUserDataDir, 'DevToolsActivePort'), { force: true });
|
|
1499
1630
|
assertChromeBinaryLaunchable(chromeBin);
|
|
1631
|
+
if (process.platform === 'linux' && !headless && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
|
|
1632
|
+
throw new Error('No Linux display found. Pass --headless (API: headless: true), or provide a working DISPLAY/WAYLAND_DISPLAY.');
|
|
1633
|
+
}
|
|
1634
|
+
mkdirSync(launchUserDataDir, { recursive: true, mode: 0o700 });
|
|
1635
|
+
chmodSync(launchUserDataDir, 0o700);
|
|
1500
1636
|
const pidFile = pidFileForPort(normalizedPort);
|
|
1501
1637
|
const stateFile = stateFileForPort(normalizedPort);
|
|
1502
1638
|
let proc = headless ? launchHeadlessChromeApp({ chromeBin, args }) : null;
|
|
@@ -1521,6 +1657,7 @@ export function launchChrome({ port = DEFAULT_PORT, profileName = null, userData
|
|
|
1521
1657
|
pid: proc.pid,
|
|
1522
1658
|
port: normalizedPort,
|
|
1523
1659
|
profileName: profileName || null,
|
|
1660
|
+
profileSourceDir: profileName ? browserToolsChromeSourceDir() : null,
|
|
1524
1661
|
userDataDir: launchUserDataDir,
|
|
1525
1662
|
headless: Boolean(headless),
|
|
1526
1663
|
includeGoogle: Boolean(includeGoogle),
|
|
@@ -1528,6 +1665,9 @@ export function launchChrome({ port = DEFAULT_PORT, profileName = null, userData
|
|
|
1528
1665
|
...buildOwnerState({ ownerToken: effectiveOwnerToken, ownerId }),
|
|
1529
1666
|
// Who launched this browser, so a leaked one is attributable instead of anonymous.
|
|
1530
1667
|
launchedByPid: process.pid,
|
|
1668
|
+
// The PID can be reused after the launcher exits. Record its start identity so a different
|
|
1669
|
+
// process inheriting the same number cannot keep an expired browser lease alive.
|
|
1670
|
+
launchedByProcessStartIdentity: processStartIdentity(process.pid),
|
|
1531
1671
|
args,
|
|
1532
1672
|
startedAt: new Date().toISOString(),
|
|
1533
1673
|
}, null, 2));
|
|
@@ -1544,6 +1684,7 @@ export async function findAvailablePort(startPort = DEFAULT_PORT, { maxAttempts
|
|
|
1544
1684
|
cleanupStaleManagedStateForPort(port);
|
|
1545
1685
|
if (
|
|
1546
1686
|
!(await browserWSEndpoint(port)) &&
|
|
1687
|
+
!(await isPortOccupied(port)) &&
|
|
1547
1688
|
!existsSync(stateFileForPort(port)) &&
|
|
1548
1689
|
!existsSync(pidFileForPort(port))
|
|
1549
1690
|
) return port;
|
|
@@ -1580,11 +1721,11 @@ export async function startChrome({
|
|
|
1580
1721
|
const { requestedProfileName, resolvedProfileName } = resolveStartProfileName({ profileName, taskName, defaultProfileName });
|
|
1581
1722
|
ensureCacheDir();
|
|
1582
1723
|
|
|
1583
|
-
// Clean up before counting, so the cap reflects browsers that are
|
|
1584
|
-
// browsers
|
|
1724
|
+
// Clean up before counting, so the cap reflects browsers that are still actively owned. Untracked
|
|
1725
|
+
// browsers and old browsers whose launcher has exited are safe to reclaim before reserving a slot.
|
|
1585
1726
|
const reaped = reapOrphanedChromes();
|
|
1586
1727
|
if (reaped.reaped.length) {
|
|
1587
|
-
console.error(`⟳ Reaped ${reaped.reaped.length}
|
|
1728
|
+
console.error(`⟳ Reaped ${reaped.reaped.length} reclaimable managed browser${reaped.reaped.length === 1 ? '' : 's'} (${describePorts(reaped.reaped)})`);
|
|
1588
1729
|
try {
|
|
1589
1730
|
pruneChromeClones({ keepPorts: [normalizedPort] });
|
|
1590
1731
|
} catch {
|
|
@@ -1606,7 +1747,8 @@ export async function startChrome({
|
|
|
1606
1747
|
ownerToken: providedOwnerToken, includeGoogle, processes: candidates,
|
|
1607
1748
|
profileName: resolvedProfileName, headless, forceProfileSync,
|
|
1608
1749
|
});
|
|
1609
|
-
|
|
1750
|
+
const foundEndpoint = found ? await browserWSEndpoint(found.port) : null;
|
|
1751
|
+
if (found && foundEndpoint) {
|
|
1610
1752
|
reusable = found;
|
|
1611
1753
|
normalizedPort = found.port;
|
|
1612
1754
|
}
|
|
@@ -1627,7 +1769,21 @@ export async function startChrome({
|
|
|
1627
1769
|
try {
|
|
1628
1770
|
cleanupStaleManagedStateForPort(normalizedPort);
|
|
1629
1771
|
|
|
1630
|
-
|
|
1772
|
+
const endpoint = await browserWSEndpoint(normalizedPort);
|
|
1773
|
+
const occupied = !endpoint && await isPortOccupied(normalizedPort);
|
|
1774
|
+
if (endpoint || occupied) {
|
|
1775
|
+
// A non-CDP listener is never an adoption candidate, even if stale
|
|
1776
|
+
// managed state happens to match this port and owner token.
|
|
1777
|
+
if (occupied) {
|
|
1778
|
+
if (!autoAllocatePort) {
|
|
1779
|
+
throw new Error(
|
|
1780
|
+
`Port :${normalizedPort} is already in use, but it is not a Browser Tools managed browser. Use a different --port or stop that listener manually.`,
|
|
1781
|
+
);
|
|
1782
|
+
}
|
|
1783
|
+
assertManagedBrowserCapacity();
|
|
1784
|
+
normalizedPort = await findAvailablePort(normalizedPort + 1);
|
|
1785
|
+
continue;
|
|
1786
|
+
}
|
|
1631
1787
|
const safety = managedBrowserSafetyForPort(normalizedPort);
|
|
1632
1788
|
const state = readManagedStateForPort(normalizedPort);
|
|
1633
1789
|
const reuse = managedBrowserReuseDecision({
|
|
@@ -1660,6 +1816,9 @@ export async function startChrome({
|
|
|
1660
1816
|
}
|
|
1661
1817
|
// A configuration mismatch is not an ownership problem: the caller owns this browser, it
|
|
1662
1818
|
// was just built differently. Say so, rather than sending them to look for a token.
|
|
1819
|
+
if (reuse.reason === 'profile-source-mismatch') {
|
|
1820
|
+
throw new Error('Managed Chrome profile source differs or was not recorded by this version. Stop it with the owner token and --clean, then restart for the requested source profile.');
|
|
1821
|
+
}
|
|
1663
1822
|
if (reuse.reason === 'profile-mismatch') {
|
|
1664
1823
|
throw new Error(
|
|
1665
1824
|
`Chrome on :${normalizedPort} was started with profile ${state?.profileName ? `"${state.profileName}"` : '(fresh, no profile)'}, but this start requested ${resolvedProfileName ? `"${resolvedProfileName}"` : '(fresh, no profile)'}. Reusing it would run against the wrong account. Stop it with scripts/stop.mjs --clean and start again, or pick a different --port.`,
|
|
@@ -1812,10 +1971,18 @@ export async function startChrome({
|
|
|
1812
1971
|
ownerTokenGenerated: false,
|
|
1813
1972
|
};
|
|
1814
1973
|
}
|
|
1815
|
-
const
|
|
1816
|
-
if (!
|
|
1974
|
+
const launchedEndpoint = await waitForChromeEndpoint(normalizedPort, { timeoutMs: CHROME_READY_TIMEOUT_MS });
|
|
1975
|
+
if (!launchedEndpoint) {
|
|
1817
1976
|
stopChrome({ port: normalizedPort, ownerToken: effectiveOwnerToken, ignorePortLock: true });
|
|
1818
|
-
throw new Error(`Failed to connect to Chrome after ${Math.round(CHROME_READY_TIMEOUT_MS / 1000)}s
|
|
1977
|
+
throw new Error(`Failed to connect to Chrome after ${Math.round(CHROME_READY_TIMEOUT_MS / 1000)}s. Check the executable, Linux sandbox/user-namespace policy, display (or --headless), and profile permissions. Snap confinement may require BROWSER_TOOLS_CACHE_DIR and BROWSER_TOOLS_ARTIFACT_DIR inside its accessible directories. Browser Tools never disables the sandbox automatically.`);
|
|
1978
|
+
}
|
|
1979
|
+
const launchedState = readManagedStateForPort(normalizedPort);
|
|
1980
|
+
const launchedSafety = managedBrowserSafetyForPort(normalizedPort);
|
|
1981
|
+
if (!launchedSafety.ok || Number(launchedState?.pid) !== Number(proc?.pid) || !await launchedEndpointMatches({ port: normalizedPort, endpoint: launchedEndpoint, state: launchedState })) {
|
|
1982
|
+
stopChrome({ port: normalizedPort, ownerToken: effectiveOwnerToken, ignorePortLock: true });
|
|
1983
|
+
throw new Error(
|
|
1984
|
+
`Chrome reported ready on :${normalizedPort}, but the responding process was not verified as the managed launch (${launchedSafety.reason || 'pid-mismatch'}).`,
|
|
1985
|
+
);
|
|
1819
1986
|
}
|
|
1820
1987
|
return {
|
|
1821
1988
|
status: 'started',
|
|
@@ -1878,7 +2045,7 @@ export function stopChrome({ port = DEFAULT_PORT, clean = false, dryRun = false,
|
|
|
1878
2045
|
rmSync(paths.stateFile, { force: true });
|
|
1879
2046
|
let cleaned = false;
|
|
1880
2047
|
if (clean && isBrowserToolsUserDataDir(state?.userDataDir)) {
|
|
1881
|
-
rmSync(state.userDataDir, { recursive: true, force: true });
|
|
2048
|
+
rmSync(state.userDataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
|
|
1882
2049
|
rmSync(profileSyncStateFileForPort(normalizedPort), { force: true });
|
|
1883
2050
|
cleaned = true;
|
|
1884
2051
|
}
|
|
@@ -1970,7 +2137,7 @@ export function stopChrome({ port = DEFAULT_PORT, clean = false, dryRun = false,
|
|
|
1970
2137
|
rmSync(paths.stateFile, { force: true });
|
|
1971
2138
|
let cleaned = false;
|
|
1972
2139
|
if (clean && isBrowserToolsUserDataDir(state?.userDataDir)) {
|
|
1973
|
-
rmSync(state.userDataDir, { recursive: true, force: true });
|
|
2140
|
+
rmSync(state.userDataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
|
|
1974
2141
|
rmSync(profileSyncStateFileForPort(normalizedPort), { force: true });
|
|
1975
2142
|
cleaned = true;
|
|
1976
2143
|
}
|
|
@@ -2056,6 +2223,19 @@ function readManagedState(stateFile) {
|
|
|
2056
2223
|
}
|
|
2057
2224
|
|
|
2058
2225
|
function commandForPid(pid) {
|
|
2226
|
+
if (process.platform === 'linux') {
|
|
2227
|
+
try {
|
|
2228
|
+
const command = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
|
|
2229
|
+
// Chromium rewrites its process title into argv[0], leaving only trailing NULs.
|
|
2230
|
+
// Retain exact boundaries for ordinary argv; parse the rewritten title as ps does.
|
|
2231
|
+
if (command) return command.split('\0').filter(Boolean).length === 1 ? command.replaceAll('\0', '').trim() : command;
|
|
2232
|
+
if (!processExists(pid)) return null;
|
|
2233
|
+
throw new Error(`Cannot inspect live browser process ${pid}`);
|
|
2234
|
+
} catch (error) {
|
|
2235
|
+
if (error.code === 'ENOENT' || error.code === 'ESRCH') return null;
|
|
2236
|
+
throw error;
|
|
2237
|
+
}
|
|
2238
|
+
}
|
|
2059
2239
|
const result = spawnSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf-8' });
|
|
2060
2240
|
if (result.error || result.status !== 0) return null;
|
|
2061
2241
|
const command = result.stdout.trim();
|
|
@@ -2067,16 +2247,30 @@ function processStartIdentity(pid) {
|
|
|
2067
2247
|
if (!Number.isInteger(normalizedPid) || normalizedPid < 1) return null;
|
|
2068
2248
|
const result = spawnSync(
|
|
2069
2249
|
'ps',
|
|
2070
|
-
['-p', String(normalizedPid), '-o', 'lstart='
|
|
2071
|
-
{
|
|
2250
|
+
['-p', String(normalizedPid), '-o', 'lstart='],
|
|
2251
|
+
{
|
|
2252
|
+
encoding: 'utf-8',
|
|
2253
|
+
// BSD ps formats lstart through the caller's locale and timezone. Canonicalize both so two
|
|
2254
|
+
// processes observing the same live launcher hash the same immutable start metadata.
|
|
2255
|
+
env: { ...process.env, LC_ALL: 'C', LANG: 'C', LC_TIME: 'C', TZ: 'UTC' },
|
|
2256
|
+
},
|
|
2072
2257
|
);
|
|
2073
2258
|
if (result.error || result.status !== 0) return null;
|
|
2074
|
-
const
|
|
2075
|
-
if (!
|
|
2259
|
+
const startedAt = result.stdout.trim();
|
|
2260
|
+
if (!startedAt) return null;
|
|
2261
|
+
// PID and kernel-reported start time stay fixed for the process lifetime. Command and argv do not:
|
|
2262
|
+
// process.title can rewrite them while the same live process continues owning the browser.
|
|
2263
|
+
const identity = `${normalizedPid}\n${startedAt}`;
|
|
2076
2264
|
return createHash('sha256').update(identity, 'utf8').digest('hex');
|
|
2077
2265
|
}
|
|
2078
2266
|
|
|
2079
2267
|
function processIsZombie(pid) {
|
|
2268
|
+
if (process.platform === 'linux') {
|
|
2269
|
+
try {
|
|
2270
|
+
const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
|
|
2271
|
+
return stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z');
|
|
2272
|
+
} catch { return false; }
|
|
2273
|
+
}
|
|
2080
2274
|
const result = spawnSync('ps', ['-p', String(pid), '-o', 'state='], { encoding: 'utf-8' });
|
|
2081
2275
|
if (result.error || result.status !== 0) return false;
|
|
2082
2276
|
return result.stdout.trim().startsWith('Z');
|
|
@@ -2155,9 +2349,18 @@ export function managedChromeCommandSafety({ pid, port, state, command }) {
|
|
|
2155
2349
|
const expectedToken = `--pi-browser-tools-managed=${state.managedToken}`;
|
|
2156
2350
|
const expectedUserDataDir = `--user-data-dir=${state.userDataDir}`;
|
|
2157
2351
|
|
|
2158
|
-
|
|
2159
|
-
|
|
2160
|
-
|
|
2352
|
+
const argv = command.includes('\0') ? command.split('\0') : null;
|
|
2353
|
+
const hasArgument = (arg) => {
|
|
2354
|
+
if (argv) return argv.includes(arg);
|
|
2355
|
+
const start = command.indexOf(arg);
|
|
2356
|
+
if (start < 0) return false;
|
|
2357
|
+
const end = start + arg.length;
|
|
2358
|
+
return (start === 0 || /\s/.test(command[start - 1]))
|
|
2359
|
+
&& (end === command.length || /\s/.test(command[end]));
|
|
2360
|
+
};
|
|
2361
|
+
if (!hasArgument(expectedDebugPort)) return { ok: false, reason: 'debug-port-mismatch', command };
|
|
2362
|
+
if (!hasArgument(expectedUserDataDir)) return { ok: false, reason: 'user-data-dir-mismatch', command };
|
|
2363
|
+
if (!hasArgument(expectedToken)) return { ok: false, reason: 'managed-token-mismatch', command };
|
|
2161
2364
|
|
|
2162
2365
|
return { ok: true, command };
|
|
2163
2366
|
}
|
|
@@ -2175,12 +2378,35 @@ export async function connectBrowser(port = DEFAULT_PORT, options = {}) {
|
|
|
2175
2378
|
throw new Error(`Refusing to connect to Browser Tools Chrome on :${normalizedPort}: ${ownership.reason}`);
|
|
2176
2379
|
}
|
|
2177
2380
|
return puppeteer.connect({
|
|
2178
|
-
browserURL: `http://
|
|
2381
|
+
browserURL: `http://127.0.0.1:${normalizedPort}`,
|
|
2179
2382
|
defaultViewport: null,
|
|
2180
2383
|
...puppeteerOptions,
|
|
2181
2384
|
});
|
|
2182
2385
|
}
|
|
2183
2386
|
|
|
2387
|
+
/** Connects to a browser this process started itself, which needs no managed-browser ownership check. */
|
|
2388
|
+
export async function connectOwnBrowser(browserWSEndpoint, options = {}) {
|
|
2389
|
+
return puppeteer.connect({ browserWSEndpoint, defaultViewport: null, ...options });
|
|
2390
|
+
}
|
|
2391
|
+
|
|
2392
|
+
/** Connects to the one tab a tab broker leased (see tab-broker.mjs), seeing no other tab of the browser. */
|
|
2393
|
+
export async function connectLeasedTab({ cdpUrl, tabUrl }, options = {}) {
|
|
2394
|
+
if (typeof cdpUrl !== 'string' || !cdpUrl.startsWith('ws://')) throw new Error('cdpUrl must be a ws:// address');
|
|
2395
|
+
if (typeof tabUrl !== 'string' || !tabUrl.startsWith('about:blank#')) throw new Error('tabUrl must be a leased tab address');
|
|
2396
|
+
const browser = await puppeteer.connect({
|
|
2397
|
+
browserWSEndpoint: cdpUrl,
|
|
2398
|
+
defaultViewport: null,
|
|
2399
|
+
...options,
|
|
2400
|
+
targetFilter: (target) => target.url() === tabUrl,
|
|
2401
|
+
});
|
|
2402
|
+
const [page] = await browser.pages();
|
|
2403
|
+
if (!page) {
|
|
2404
|
+
await browser.disconnect();
|
|
2405
|
+
throw new Error('The leased tab is gone');
|
|
2406
|
+
}
|
|
2407
|
+
return { browser, page };
|
|
2408
|
+
}
|
|
2409
|
+
|
|
2184
2410
|
export async function withBrowser(port, callback, options = {}) {
|
|
2185
2411
|
const browser = await connectBrowser(port, options);
|
|
2186
2412
|
try {
|