@rezkam/browser-tools 1.1.0 → 1.1.1

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.
@@ -20,6 +20,7 @@ import {
20
20
  requiredOptionValue,
21
21
  } from './browser-control.mjs';
22
22
  import { privateOutputPath, withPageCdpSession } from './cdp-common.mjs';
23
+ import { createRecordingLifecycle } from './recording-lifecycle.mjs';
23
24
  import {
24
25
  CDP_CAPTURE_STOP_TIMEOUT_MS,
25
26
  assertCdpRecordingOwner,
@@ -188,23 +189,18 @@ async function runWorker(args) {
188
189
  const output = requiredOptionValue(args, '--output', null);
189
190
  const options = decodeOptions(requiredOptionValue(args, '--worker-options', null));
190
191
  const startedAt = new Date().toISOString();
191
- let state = {
192
+ const metadata = {
192
193
  managedBy: 'browser-tools-cdp-recorder',
193
194
  kind: CAPTURE_KIND,
194
195
  pid: process.pid,
195
196
  port,
196
197
  output,
197
198
  ownerTokenHash: ownerTokenHash(ownerToken),
198
- status: 'starting',
199
- phase: 'starting',
200
199
  startedAt,
201
200
  options,
202
201
  };
203
- const update = (changes) => {
204
- state = { ...state, ...changes };
205
- updateCdpRecordingState(CAPTURE_KIND, port, state);
206
- };
207
- update({});
202
+ const lifecycle = createRecordingLifecycle(CAPTURE_KIND, metadata,
203
+ (state) => updateCdpRecordingState(CAPTURE_KIND, port, state));
208
204
 
209
205
  try {
210
206
  const result = await withPageCdpSession(port, ownerToken, async ({ page, session }) => runHarCapture({
@@ -212,28 +208,12 @@ async function runWorker(args) {
212
208
  page,
213
209
  options,
214
210
  shouldStop: () => existsSync(cdpRecordingStopFile(CAPTURE_KIND, port)),
215
- onPhase: (phase, reason = null) => update({
216
- status: phase === 'recording' ? 'recording' : state.status,
217
- phase,
218
- reason: reason ?? state.reason,
219
- readyAt: phase === 'recording' ? new Date().toISOString() : state.readyAt,
220
- }),
211
+ onPhase: (phase, reason) => lifecycle.transition(phase, reason ? { reason } : {}),
221
212
  }));
222
213
  writeHar(output, result.har);
223
- update({
224
- status: 'completed',
225
- phase: 'completed',
226
- reason: result.reason,
227
- eventCount: result.eventCount,
228
- completedAt: new Date().toISOString(),
229
- });
214
+ lifecycle.transition('completed', { reason: result.reason, eventCount: result.eventCount });
230
215
  } catch (error) {
231
- update({
232
- status: 'failed',
233
- phase: 'failed',
234
- error: error.message,
235
- completedAt: new Date().toISOString(),
236
- });
216
+ lifecycle.transition('failed', { error: error.message });
237
217
  throw error;
238
218
  }
239
219
  }
@@ -0,0 +1,33 @@
1
+ // Each recording owns its phase. The legacy status field is a projection, never another state.
2
+ const PATHS = {
3
+ gif: ['starting', 'pre-roll', 'recording', 'post-roll', 'completed'],
4
+ har: ['starting', 'recording', 'draining', 'completed'],
5
+ cdp: ['starting', 'recording', 'post-wait', 'completed'],
6
+ };
7
+
8
+ export function createRecordingLifecycle(kind, metadata = {}, persist = () => {}) {
9
+ const path = PATHS[kind];
10
+ if (!path) throw new Error(`Unknown recording kind: ${kind}`);
11
+ let state = { ...metadata, phase: 'starting', status: 'starting' };
12
+ persist({ ...state });
13
+
14
+ return {
15
+ get phase() { return state.phase; },
16
+ snapshot() { return { ...state }; },
17
+ transition(phase, details = {}) {
18
+ const current = path.indexOf(state.phase);
19
+ const terminal = state.phase === 'completed' || state.phase === 'failed';
20
+ if (terminal || (phase !== 'failed' && path[current + 1] !== phase)) {
21
+ throw new Error(`Invalid ${kind} recording transition: ${state.phase} -> ${phase}`);
22
+ }
23
+ const status = ['completed', 'failed'].includes(phase) ? phase
24
+ : path.indexOf(phase) >= path.indexOf('recording') ? 'recording' : 'starting';
25
+ const next = { ...state, ...details, phase, status };
26
+ if (phase === 'recording') next.readyAt = new Date().toISOString();
27
+ if (phase === 'completed' || phase === 'failed') next.completedAt = new Date().toISOString();
28
+ persist({ ...next });
29
+ state = next;
30
+ return { ...state };
31
+ },
32
+ };
33
+ }
@@ -65,10 +65,10 @@ function normalizePageResult(pageResult, closePage) {
65
65
  if (pageResult && typeof pageResult === 'object' && Object.hasOwn(pageResult, 'page')) {
66
66
  return {
67
67
  page: pageResult.page,
68
- closePage: Object.hasOwn(pageResult, 'closePage') ? Boolean(pageResult.closePage) : closePage,
68
+ ownership: (Object.hasOwn(pageResult, 'closePage') ? pageResult.closePage : closePage) ? 'owned' : 'borrowed',
69
69
  };
70
70
  }
71
- return { page: pageResult, closePage };
71
+ return { page: pageResult, ownership: closePage ? 'owned' : 'borrowed' };
72
72
  }
73
73
 
74
74
  export async function runBrowserResource({
@@ -82,16 +82,14 @@ export async function runBrowserResource({
82
82
  if (typeof run !== 'function') throw new Error('Missing Resource Helper run function');
83
83
 
84
84
  const browser = await connect(port, connectOptionsForOwner(ownerToken));
85
- let page = null;
86
- let shouldClosePage = closePage;
87
-
88
85
  try {
89
- const normalized = normalizePageResult(getPage ? await getPage(browser) : null, closePage);
90
- page = normalized.page;
91
- shouldClosePage = normalized.closePage;
92
- return await run({ browser, page });
86
+ const resource = normalizePageResult(getPage ? await getPage(browser) : null, closePage);
87
+ try {
88
+ return await run({ browser, page: resource.page });
89
+ } finally {
90
+ if (resource.ownership === 'owned') await closeResourcePage(resource.page);
91
+ }
93
92
  } finally {
94
- if (shouldClosePage) await closeResourcePage(page);
95
93
  if (browser && typeof browser.disconnect === 'function') browser.disconnect();
96
94
  }
97
95
  }
package/scripts/serve.mjs CHANGED
@@ -25,12 +25,12 @@ const served = await serveTabs({
25
25
  });
26
26
  process.stdout.write(`${JSON.stringify({ url: served.url })}\n`);
27
27
 
28
- let stopping = false;
29
- async function stop() {
30
- if (stopping) return;
31
- stopping = true;
32
- await served.close();
33
- process.exit(0);
28
+ function stop() {
29
+ // The served instance owns idempotent shutdown, not a second CLI-local stopping flag.
30
+ void served.close().then(() => process.exit(0), (error) => {
31
+ console.error(error.message);
32
+ process.exit(1);
33
+ });
34
34
  }
35
35
  process.on('SIGTERM', stop);
36
36
  process.on('SIGINT', stop);
@@ -8,12 +8,12 @@
8
8
  */
9
9
 
10
10
  import { spawn } from 'node:child_process';
11
- import { randomUUID } from 'node:crypto';
12
11
  import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
13
12
  import { createServer, get as httpGet } from 'node:http';
14
13
  import { tmpdir } from 'node:os';
15
14
  import { join } from 'node:path';
16
15
  import { connectOwnBrowser } from './browser-control.mjs';
16
+ import { createTabPool } from './tab-pool.mjs';
17
17
 
18
18
  export const DEFAULT_MAX_TABS = 4;
19
19
  export const DEFAULT_TAB_SECONDS = 120;
@@ -65,11 +65,6 @@ export async function serveTabs({
65
65
  if (!Number.isInteger(maxTabs) || maxTabs < 1) throw new Error('maxTabs must be a positive integer');
66
66
  if (!(tabSeconds > 0)) throw new Error('tabSeconds must be positive');
67
67
 
68
- const waiting = [];
69
- const held = new Set();
70
- let chrome = null;
71
- let starting = null;
72
- let closed = false;
73
68
 
74
69
  async function launchChrome() {
75
70
  const profile = mkdtempSync(join(tmpdir(), 'browser-tools-tabs-'));
@@ -86,125 +81,65 @@ export async function serveTabs({
86
81
  child.stderr.on('data', (chunk) => {
87
82
  stderr = (stderr + chunk).slice(-2000);
88
83
  });
89
- const exited = new Promise((resolve) => child.once('exit', (code, signal) => resolve({ code, signal })));
90
- const portFile = join(profile, 'DevToolsActivePort');
91
- const deadline = Date.now() + CHROME_START_TIMEOUT_MS;
92
- let exit = null;
93
- exited.then((value) => {
94
- exit = value;
95
- });
96
- while (!existsSync(portFile) || readFileSync(portFile, 'utf8').split('\n').length < 2) {
97
- if (exit) throw new Error(`Chrome exited while starting (${exit.signal ?? exit.code}): ${stderr.trim().slice(-500)}`);
98
- if (Date.now() > deadline) {
99
- child.kill('SIGKILL');
100
- throw new Error(`Chrome did not start within ${CHROME_START_TIMEOUT_MS}ms`);
101
- }
102
- await new Promise((resolve) => setTimeout(resolve, 50));
103
- }
104
- const [cdpPort, path] = readFileSync(portFile, 'utf8').split('\n');
105
- const cdpUrl = `ws://127.0.0.1:${cdpPort}${path}`;
106
- const browser = await connectOwnBrowser(cdpUrl, { targetFilter: () => false });
107
- const session = await browser.target().createCDPSession();
108
- const started = { child, browser, session, cdpUrl, cdpPort: Number(cdpPort), profile, exited };
109
- exited.then(({ code, signal }) => {
110
- if (chrome === started) chrome = null;
84
+ let processState = { phase: 'starting' };
85
+ child.once('error', (error) => { processState = { phase: 'failed', error }; });
86
+ const exited = new Promise((resolve) => child.once('close', (code, signal) => {
87
+ const previous = processState.phase;
88
+ if (previous !== 'failed') processState = { phase: 'exited', code, signal };
111
89
  rmSync(profile, { recursive: true, force: true });
112
- if (!closed) log({ event: 'browser_exit', code, signal });
113
- });
114
- log({ event: 'browser_start', pid: child.pid });
115
- return started;
116
- }
117
-
118
- async function ensureChrome() {
119
- if (chrome && chrome.browser.connected && chrome.child.exitCode === null && chrome.child.signalCode === null) return chrome;
120
- chrome = null;
121
- starting ??= launchChrome().finally(() => {
122
- starting = null;
123
- });
124
- chrome = await starting;
125
- return chrome;
126
- }
127
-
128
- function pump() {
129
- while (!closed && held.size < maxTabs && waiting.length > 0) {
130
- const lease = waiting.shift();
131
- held.add(lease);
132
- void grant(lease);
133
- }
134
- }
135
-
136
- function write(lease, line) {
137
- if (!lease.response.writableEnded && !lease.response.destroyed) lease.response.write(`${JSON.stringify(line)}\n`);
138
- }
139
-
140
- function end(lease, ended) {
141
- if (lease.ended) return;
142
- lease.ended = ended;
143
- clearTimeout(lease.timer);
144
- held.delete(lease);
145
- if (lease.context && lease.chrome) {
146
- lease.chrome.session.send('Target.disposeBrowserContext', { browserContextId: lease.context }).catch(() => {});
147
- }
148
- log({
149
- event: 'tab_lease',
150
- client: lease.client,
151
- waited_ms: (lease.granted ?? Date.now()) - lease.asked,
152
- held_ms: lease.granted ? Date.now() - lease.granted : 0,
153
- ended,
154
- tabs: held.size,
155
- waiting: waiting.length,
156
- });
157
- if (ended !== 'released') {
158
- write(lease, ended === 'error' ? { error: lease.error } : { ended });
159
- lease.response.end();
160
- }
161
- pump();
162
- }
163
-
164
- async function grant(lease) {
90
+ if (previous === 'running') log({ event: 'browser_exit', code, signal });
91
+ resolve({ code, signal });
92
+ }));
93
+ let browser;
165
94
  try {
166
- const running = await ensureChrome();
167
- lease.chrome = running;
168
- const { browserContextId } = await running.session.send('Target.createBrowserContext', {
169
- disposeOnDetach: false,
170
- ...(proxyServer ? { proxyServer, proxyBypassList: '<-loopback>' } : {}),
171
- });
172
- lease.context = browserContextId;
173
- await running.session.send('Browser.setDownloadBehavior', { behavior: 'deny', browserContextId });
174
- // The tab opens on an address of its own, which is how a client finds it among the browser's targets.
175
- const tabUrl = `about:blank#${randomUUID()}`;
176
- const { targetId } = await running.session.send('Target.createTarget', { url: tabUrl, browserContextId });
177
- if (lease.gone) return end(lease, 'released');
178
- lease.granted = Date.now();
179
- lease.timer = setTimeout(() => end(lease, 'expired'), tabSeconds * 1000);
180
- write(lease, { cdp_url: running.cdpUrl, target_id: targetId, tab_url: tabUrl, deadline: lease.granted + tabSeconds * 1000 });
95
+ const portFile = join(profile, 'DevToolsActivePort');
96
+ const deadline = Date.now() + CHROME_START_TIMEOUT_MS;
97
+ while (!existsSync(portFile) || readFileSync(portFile, 'utf8').split('\n').length < 2) {
98
+ if (processState.phase === 'failed') throw processState.error;
99
+ if (processState.phase === 'exited') throw new Error(`Chrome exited while starting (${processState.signal ?? processState.code}): ${stderr.trim().slice(-500)}`);
100
+ if (Date.now() > deadline) throw new Error(`Chrome did not start within ${CHROME_START_TIMEOUT_MS}ms`);
101
+ await new Promise((resolve) => setTimeout(resolve, 50));
102
+ }
103
+ const [cdpPort, path] = readFileSync(portFile, 'utf8').split('\n');
104
+ const cdpUrl = `ws://127.0.0.1:${cdpPort}${path}`;
105
+ browser = await connectOwnBrowser(cdpUrl, { targetFilter: () => false });
106
+ const session = await browser.target().createCDPSession();
107
+ processState = { phase: 'running' };
108
+ log({ event: 'browser_start', pid: child.pid });
109
+ return {
110
+ child, browser, session, cdpUrl, cdpPort: Number(cdpPort), exited,
111
+ async close() {
112
+ if (processState.phase === 'exited' || processState.phase === 'failed') return;
113
+ processState = { phase: 'stopping' };
114
+ // Do not let an unresponsive CDP connection prevent the bounded process shutdown.
115
+ void session.send('Browser.close').catch(() => {});
116
+ let timer;
117
+ const stopped = await Promise.race([
118
+ exited.then(() => true),
119
+ new Promise((resolve) => { timer = setTimeout(() => resolve(false), CHROME_STOP_TIMEOUT_MS); }),
120
+ ]);
121
+ clearTimeout(timer);
122
+ if (!stopped) { child.kill('SIGKILL'); await exited; }
123
+ await browser.disconnect().catch(() => {});
124
+ },
125
+ };
181
126
  } catch (error) {
182
- lease.error = error instanceof Error ? error.message : String(error);
183
- end(lease, 'error');
127
+ await browser?.disconnect().catch(() => {});
128
+ if (processState.phase !== 'exited' && processState.phase !== 'failed') child.kill('SIGKILL');
129
+ await exited;
130
+ throw error;
184
131
  }
185
132
  }
186
133
 
134
+ const pool = createTabPool({ launchChrome, maxTabs, tabSeconds, proxyServer, log });
135
+
187
136
  const server = createServer((request, response) => {
188
137
  const url = new URL(request.url, 'http://broker');
189
138
  if (request.method !== 'GET' || url.pathname !== '/lease') {
190
139
  response.writeHead(404).end();
191
140
  return;
192
141
  }
193
- if (closed) {
194
- response.writeHead(503).end();
195
- return;
196
- }
197
- const lease = { client: url.searchParams.get('client') || 'unnamed', asked: Date.now(), response, gone: false };
198
- response.writeHead(200, { 'content-type': 'application/x-ndjson', 'cache-control': 'no-store' });
199
- response.flushHeaders();
200
- response.on('close', () => {
201
- lease.gone = true;
202
- const queued = waiting.indexOf(lease);
203
- if (queued >= 0) waiting.splice(queued, 1);
204
- else if (lease.granted) end(lease, 'released');
205
- });
206
- waiting.push(lease);
207
- pump();
142
+ pool.add(response, url.searchParams.get('client') || 'unnamed');
208
143
  });
209
144
  server.requestTimeout = 0;
210
145
  await new Promise((resolve, reject) => {
@@ -215,9 +150,9 @@ export async function serveTabs({
215
150
  const sampler =
216
151
  process.platform === 'linux'
217
152
  ? setInterval(() => {
218
- if (!chrome) return;
219
- const sample = chromeMemory(chrome.child.pid);
220
- if (sample) log({ event: 'browser_memory', ...sample, tabs: held.size, waiting: waiting.length });
153
+ if (!pool.running) return;
154
+ const sample = chromeMemory(pool.running.child.pid);
155
+ if (sample) log({ event: 'browser_memory', ...sample, ...pool.counts });
221
156
  }, sampleSeconds * 1000)
222
157
  : null;
223
158
  sampler?.unref();
@@ -226,27 +161,14 @@ export async function serveTabs({
226
161
  return {
227
162
  url: `http://${host}:${address.port}`,
228
163
  get cdpPort() {
229
- return chrome?.cdpPort ?? null;
164
+ return pool.running?.cdpPort ?? null;
230
165
  },
231
166
  async close() {
232
- closed = true;
233
167
  if (sampler) clearInterval(sampler);
234
- for (const lease of [...held]) end(lease, 'closed');
235
- for (const lease of waiting.splice(0)) lease.response.writeHead?.(503) && lease.response.end();
168
+ const closing = pool.close();
169
+ const transportClosed = new Promise((resolve) => server.close(resolve));
236
170
  server.closeAllConnections();
237
- await new Promise((resolve) => server.close(resolve));
238
- const running = chrome ?? (await starting?.catch(() => null));
239
- if (!running) return;
240
- await running.session.send('Browser.close').catch(() => {});
241
- running.browser.disconnect().catch?.(() => {});
242
- const stopped = await Promise.race([
243
- running.exited.then(() => true),
244
- new Promise((resolve) => setTimeout(() => resolve(false), CHROME_STOP_TIMEOUT_MS)),
245
- ]);
246
- if (!stopped) {
247
- running.child.kill('SIGKILL');
248
- await running.exited;
249
- }
171
+ await Promise.all([transportClosed, closing]);
250
172
  },
251
173
  };
252
174
  }
@@ -303,15 +225,20 @@ export function chromeMemory(rootPid) {
303
225
  */
304
226
  export function leaseTab(brokerUrl, { client = 'unnamed' } = {}) {
305
227
  return new Promise((resolve, reject) => {
306
- let granted = null;
307
- let finish;
308
- const ended = new Promise((resolveEnded) => {
309
- finish = resolveEnded;
310
- });
228
+ let state = { phase: 'waiting' };
229
+ let resolveEnded;
230
+ const ended = new Promise((resolve) => { resolveEnded = resolve; });
231
+ const finish = (reason, error = null) => {
232
+ if (state.phase === 'ended') return;
233
+ if (state.phase === 'waiting') reject(error ?? new Error(`the tab broker ${reason} the lease before granting a tab`));
234
+ state = { phase: 'ended', reason };
235
+ resolveEnded(reason);
236
+ };
311
237
  const request = httpGet(`${brokerUrl}/lease?client=${encodeURIComponent(client)}`, { agent: false }, (response) => {
312
238
  if (response.statusCode !== 200) {
313
239
  response.resume();
314
- reject(new Error(`the tab broker refused the lease with HTTP ${response.statusCode}`));
240
+ finish('error', new Error(`the tab broker refused the lease with HTTP ${response.statusCode}`));
241
+ request.destroy();
315
242
  return;
316
243
  }
317
244
  response.setEncoding('utf8');
@@ -319,33 +246,39 @@ export function leaseTab(brokerUrl, { client = 'unnamed' } = {}) {
319
246
  response.on('data', (chunk) => {
320
247
  buffer += chunk;
321
248
  for (let index = buffer.indexOf('\n'); index >= 0; index = buffer.indexOf('\n')) {
322
- const line = JSON.parse(buffer.slice(0, index));
323
- buffer = buffer.slice(index + 1);
324
- if (line.error) {
325
- reject(new Error(`the tab broker could not open a tab: ${line.error}`));
326
- } else if (!granted) {
327
- granted = {
328
- cdpUrl: line.cdp_url,
329
- targetId: line.target_id,
330
- tabUrl: line.tab_url,
331
- deadline: line.deadline,
332
- ended,
333
- release: () => request.destroy(),
334
- };
335
- resolve(granted);
336
- } else if (line.ended) {
337
- finish(line.ended);
249
+ if (state.phase === 'ended') return;
250
+ try {
251
+ const line = JSON.parse(buffer.slice(0, index));
252
+ buffer = buffer.slice(index + 1);
253
+ if (line.error) {
254
+ finish('error', new Error(`the tab broker could not open a tab: ${line.error}`));
255
+ request.destroy();
256
+ } else if (line.ended) {
257
+ finish(line.ended);
258
+ request.destroy();
259
+ } else if (state.phase === 'waiting') {
260
+ if (!line.cdp_url || !line.target_id || !line.tab_url || !Number.isFinite(line.deadline)) {
261
+ throw new Error('the tab broker sent an invalid lease grant');
262
+ }
263
+ state = { phase: 'active' };
264
+ resolve({
265
+ cdpUrl: line.cdp_url,
266
+ targetId: line.target_id,
267
+ tabUrl: line.tab_url,
268
+ deadline: line.deadline,
269
+ ended,
270
+ release: () => { finish('released'); request.destroy(); },
271
+ });
272
+ }
273
+ } catch (error) {
274
+ finish('error', error);
275
+ request.destroy();
338
276
  }
339
277
  }
340
278
  });
341
- response.on('close', () => {
342
- if (!granted) reject(new Error('the tab broker closed the lease before granting a tab'));
343
- finish('released');
344
- });
345
- });
346
- request.on('error', (error) => {
347
- if (!granted) reject(error);
348
- finish('released');
279
+ response.on('error', (error) => finish('released', error));
280
+ response.on('close', () => finish('released', new Error('the tab broker closed the lease before granting a tab')));
349
281
  });
282
+ request.on('error', (error) => finish('released', error));
350
283
  });
351
284
  }