cdp-toolkit 3.0.3 → 3.2.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 +28 -0
- package/CONTRACT.md +2 -2
- package/README.md +122 -1
- package/dist/bidi/mux-daemon.js +675 -130
- package/dist/cli.js +1432 -635
- package/dist/index.js +1110 -116
- package/dist/mcp.js +1474 -658
- package/package.json +3 -1
- package/src/bidi/snapshot.ts +123 -113
- package/src/cdp/driver.ts +55 -41
- package/src/cdp/endpoint.ts +200 -0
- package/src/cdp/session.ts +246 -0
- package/src/cli.ts +17 -4
- package/src/client.ts +140 -16
- package/src/endpoints.ts +428 -0
- package/src/leases-tools.ts +6 -3
- package/src/leases.ts +28 -4
- package/src/manifest.ts +54 -42
- package/src/mcp.ts +52 -8
- package/src/origins.ts +5 -2
- package/src/policy.ts +163 -0
- package/src/reap.ts +14 -0
- package/src/shared-tools.ts +164 -25
- package/src/toolDocs.ts +41 -38
- package/src/tools/browser-session.ts +26 -12
- package/src/tools/dispatch-mouse.ts +2 -1
- package/src/tools/evaluate.ts +3 -3
- package/src/tools/focus-emulation.ts +5 -3
- package/src/tools/lighthouse.ts +4 -2
- package/src/tools/navigation.ts +3 -3
- package/src/tools/network_mock.ts +2 -2
- package/src/tools/performance.ts +5 -5
- package/src/tools/recorder.ts +3 -3
- package/src/tools/screencast.ts +46 -6
- package/src/tools/snapshot.ts +2 -2
- package/src/version.ts +1 -1
package/src/client.ts
CHANGED
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
* the primitives exported here. See CONTRACT.md.
|
|
5
5
|
*/
|
|
6
6
|
import type { CdpResponse, Target, TargetSelector } from "./types.ts";
|
|
7
|
-
import { assertLeaseOk } from "./leases.ts";
|
|
7
|
+
import { assertLeaseOk, chromeLeaseBackend } from "./leases.ts";
|
|
8
8
|
import { resolveLiveLabel } from "./origins.ts";
|
|
9
|
+
import { currentEndpoint, defaultEndpoint, DEFAULT_CDP_BASE } from "./endpoints.ts";
|
|
9
10
|
import {
|
|
10
11
|
isWorkerSelector,
|
|
11
12
|
isWorkerTargetType,
|
|
@@ -24,8 +25,24 @@ import {
|
|
|
24
25
|
FRAME_EMPTY_NEEDLE_MESSAGE,
|
|
25
26
|
} from "./frames.ts";
|
|
26
27
|
|
|
27
|
-
|
|
28
|
-
|
|
28
|
+
import { detectEndpoint, resetEndpointCache, type CdpTransport } from "./cdp/endpoint.ts";
|
|
29
|
+
import { openSession, withBrowserSocket, type PageConnection } from "./cdp/session.ts";
|
|
30
|
+
export { SessionConnection, withBrowserSocket, type PageConnection } from "./cdp/session.ts";
|
|
31
|
+
/**
|
|
32
|
+
* Base HTTP origin of the DEFAULT DevTools endpoint, fixed at import (CDP_BASE, else
|
|
33
|
+
* http://127.0.0.1:9222, or the default named by CDP_ENDPOINTS / CDP_ENDPOINTS_FILE).
|
|
34
|
+
* Kept for library callers; nothing in this package reads it to build a URL any more:
|
|
35
|
+
* every request resolves its base per call through currentEndpoint() (src/endpoints.ts).
|
|
36
|
+
* A malformed endpoint config must not crash the import, so this falls back to the old
|
|
37
|
+
* expression and the config error surfaces on first use (or at MCP/CLI startup).
|
|
38
|
+
*/
|
|
39
|
+
export const BASE: string = (() => {
|
|
40
|
+
try {
|
|
41
|
+
return defaultEndpoint().base;
|
|
42
|
+
} catch {
|
|
43
|
+
return process.env.CDP_BASE ?? DEFAULT_CDP_BASE;
|
|
44
|
+
}
|
|
45
|
+
})();
|
|
29
46
|
|
|
30
47
|
/** Default per-command timeout (ms). Override with CDP_TIMEOUT_MS. */
|
|
31
48
|
export const DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15_000);
|
|
@@ -193,21 +210,116 @@ export class CdpConnection {
|
|
|
193
210
|
|
|
194
211
|
/* ----------------------------- endpoint discovery ----------------------------- */
|
|
195
212
|
|
|
213
|
+
/**
|
|
214
|
+
* Which transport each endpoint turned out to serve, learned from its first
|
|
215
|
+
* listing that succeeded, keyed by endpoint base. Absent until then.
|
|
216
|
+
*/
|
|
217
|
+
const knownTransports = new Map<string, CdpTransport>();
|
|
218
|
+
|
|
219
|
+
/** Test seam: forget the learned transport. */
|
|
220
|
+
export function resetTransportCache(): void {
|
|
221
|
+
knownTransports.clear();
|
|
222
|
+
resetEndpointCache();
|
|
223
|
+
}
|
|
224
|
+
|
|
196
225
|
async function httpJson<T>(path: string): Promise<T> {
|
|
197
|
-
|
|
226
|
+
// Resolved PER CALL, never cached: the endpoint comes from the dispatch scope, and an
|
|
227
|
+
// endpoint that was down a moment ago is simply tried again.
|
|
228
|
+
const res = await fetch(`${currentEndpoint().base}${path}`);
|
|
198
229
|
if (!res.ok) throw new CdpError(`${path} -> HTTP ${res.status}`);
|
|
199
230
|
return (await res.json()) as T;
|
|
200
231
|
}
|
|
201
232
|
|
|
202
|
-
/**
|
|
203
|
-
|
|
204
|
-
|
|
233
|
+
/**
|
|
234
|
+
* `Target.getTargets` reshaped into the `/json/list` record every caller
|
|
235
|
+
* already reads.
|
|
236
|
+
*
|
|
237
|
+
* TWO DIFFERENCES from the HTTP listing, both deliberate:
|
|
238
|
+
*
|
|
239
|
+
* `filter: [{}]` is passed because the DEFAULT filter is not "everything" — it
|
|
240
|
+
* omits types the empty filter includes. Measured on Chrome 153: default
|
|
241
|
+
* returned 4 targets (page, browser_ui), `[{}]` returned 6, and the missing
|
|
242
|
+
* ones were exactly the iframe/worker types that the `frame:` and `worker:`
|
|
243
|
+
* selector arms resolve against. Taking the default would silently delete two
|
|
244
|
+
* documented features.
|
|
245
|
+
*
|
|
246
|
+
* `webSocketDebuggerUrl` is EMPTY, and it has to be: on this transport there is
|
|
247
|
+
* no per-target socket to name, and inventing the `/devtools/page/<id>` URL
|
|
248
|
+
* would hand callers a string that 403s. Nothing reads the field on this path —
|
|
249
|
+
* `openPage` branches on transport before it would — and the emptiness is what
|
|
250
|
+
* makes a caller that ignored the branch fail loudly instead of hanging.
|
|
251
|
+
*/
|
|
252
|
+
async function getTargetsOverBrowserWs(): Promise<Target[]> {
|
|
253
|
+
const { targetInfos } = await withBrowserSocket((conn) =>
|
|
254
|
+
conn.send<{ targetInfos: Array<{ targetId: string; type: string; title: string; url: string; openerId?: string }> }>(
|
|
255
|
+
"Target.getTargets",
|
|
256
|
+
{ filter: [{}] },
|
|
257
|
+
),
|
|
258
|
+
);
|
|
259
|
+
return targetInfos.map((t) => ({
|
|
260
|
+
id: t.targetId,
|
|
261
|
+
type: t.type,
|
|
262
|
+
title: t.title,
|
|
263
|
+
url: t.url,
|
|
264
|
+
webSocketDebuggerUrl: "",
|
|
265
|
+
...(t.openerId ? { parentId: t.openerId } : {}),
|
|
266
|
+
}));
|
|
205
267
|
}
|
|
206
268
|
|
|
207
|
-
/**
|
|
269
|
+
/**
|
|
270
|
+
* All targets: `GET /json/list`, falling back to `Target.getTargets` on the
|
|
271
|
+
* browser socket when this Chrome does not serve it.
|
|
272
|
+
*
|
|
273
|
+
* THE HTTP REQUEST GOES FIRST AND UNCONDITIONALLY, which is the whole
|
|
274
|
+
* no-regression story: against a Chrome that serves `/json/list` this function
|
|
275
|
+
* does exactly what it did before the fallback existed, and the fallback is
|
|
276
|
+
* unreachable. Only a request that failed opens a socket.
|
|
277
|
+
*
|
|
278
|
+
* Once a transport is known it is cached, so the 404 is paid once per process
|
|
279
|
+
* rather than on every listing.
|
|
280
|
+
*/
|
|
281
|
+
export async function listTargets(): Promise<Target[]> {
|
|
282
|
+
const base = currentEndpoint().base;
|
|
283
|
+
if (knownTransports.get(base) === "browser-ws") return getTargetsOverBrowserWs();
|
|
284
|
+
try {
|
|
285
|
+
const listing = await httpJson<Target[]>("/json/list");
|
|
286
|
+
knownTransports.set(base, "http");
|
|
287
|
+
return listing;
|
|
288
|
+
} catch (httpError) {
|
|
289
|
+
// Switch only when detection says this endpoint really serves no `/json`.
|
|
290
|
+
// A Chrome that does serve it can still fail one `/json/list` (restarting,
|
|
291
|
+
// a timeout); its `/json/version` then answers, detection says "http", and
|
|
292
|
+
// pinning browser-ws here would move every later call off the per-target
|
|
293
|
+
// sockets for the rest of the process. Rethrow instead, so the next call
|
|
294
|
+
// tries HTTP again.
|
|
295
|
+
const detected = await detectEndpoint().catch(() => undefined);
|
|
296
|
+
if (detected?.transport !== "browser-ws") throw httpError;
|
|
297
|
+
const targets = await getTargetsOverBrowserWs().catch(() => {
|
|
298
|
+
// The HTTP failure is the one worth reporting: it names the endpoint the
|
|
299
|
+
// user configured, where the fallback's failure only says a profile
|
|
300
|
+
// lookup came up empty.
|
|
301
|
+
throw httpError;
|
|
302
|
+
});
|
|
303
|
+
knownTransports.set(base, "browser-ws");
|
|
304
|
+
return targets;
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* Browser-level WebSocket URL, for Target.* / Browser.*.
|
|
310
|
+
*
|
|
311
|
+
* `GET /json/version` first and on every call, as before the browser-ws
|
|
312
|
+
* transport existed: its uuid changes on every Chrome start, so a URL kept
|
|
313
|
+
* across calls goes stale after a restart. Only an endpoint already known to
|
|
314
|
+
* serve no `/json`, or one whose `/json/version` did not answer, goes through
|
|
315
|
+
* detection.
|
|
316
|
+
*/
|
|
208
317
|
export async function browserWsUrl(): Promise<string> {
|
|
209
|
-
|
|
210
|
-
|
|
318
|
+
if (knownTransports.get(currentEndpoint().base) !== "browser-ws") {
|
|
319
|
+
const version = await httpJson<{ webSocketDebuggerUrl: string }>("/json/version").catch(() => undefined);
|
|
320
|
+
if (version?.webSocketDebuggerUrl) return version.webSocketDebuggerUrl;
|
|
321
|
+
}
|
|
322
|
+
return (await detectEndpoint()).browserWsUrl;
|
|
211
323
|
}
|
|
212
324
|
|
|
213
325
|
/** Resolve a TargetSelector to a concrete page target. See types.ts for grammar.
|
|
@@ -237,7 +349,7 @@ export async function resolveTarget(selector: TargetSelector, opts: { lease?: st
|
|
|
237
349
|
// target we just resolved. Passing it would only suggest a check is happening
|
|
238
350
|
// that is not. target-gone earns its keep on claim, and on a list_leases
|
|
239
351
|
// reap, where a record's id may genuinely be absent from the browser.
|
|
240
|
-
await assertLeaseOk(
|
|
352
|
+
await assertLeaseOk(chromeLeaseBackend(), hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
|
|
241
353
|
return hit;
|
|
242
354
|
}
|
|
243
355
|
|
|
@@ -266,7 +378,7 @@ async function pickTarget(targets: Target[], selector: TargetSelector): Promise<
|
|
|
266
378
|
}
|
|
267
379
|
if (selector.startsWith("label:")) {
|
|
268
380
|
const label = selector.slice(6);
|
|
269
|
-
const { matchIds, knownLabels } = await resolveLiveLabel(
|
|
381
|
+
const { matchIds, knownLabels } = await resolveLiveLabel(chromeLeaseBackend(), label, pages.map((t) => t.id));
|
|
270
382
|
if (matchIds.length > 1) {
|
|
271
383
|
throw new CdpError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
|
|
272
384
|
}
|
|
@@ -317,13 +429,25 @@ export async function openBrowser(opts: { timeoutMs?: number } = {}): Promise<Cd
|
|
|
317
429
|
return new CdpConnection(await browserWsUrl(), opts).connect();
|
|
318
430
|
}
|
|
319
431
|
|
|
320
|
-
/**
|
|
432
|
+
/**
|
|
433
|
+
* Open a connection to a page target. Returns the connection and the target.
|
|
434
|
+
*
|
|
435
|
+
* The one place the two transports diverge for a tool author: a per-target
|
|
436
|
+
* socket where Chrome serves one, an attached session on the shared browser
|
|
437
|
+
* socket where it does not. Both are closed by the caller the same way, and
|
|
438
|
+
* both carry the same per-command timeout, so no tool module branches on this.
|
|
439
|
+
*/
|
|
321
440
|
export async function openPage(
|
|
322
441
|
selector: TargetSelector,
|
|
323
442
|
opts: { timeoutMs?: number; lease?: string } = {},
|
|
324
|
-
): Promise<{ conn:
|
|
443
|
+
): Promise<{ conn: PageConnection; target: Target }> {
|
|
444
|
+
// resolveTarget listed first, so the transport is already known here: an
|
|
445
|
+
// empty webSocketDebuggerUrl is the browser-ws listing's own marker that this
|
|
446
|
+
// target has no socket to dial (see getTargetsOverBrowserWs).
|
|
325
447
|
const target = await resolveTarget(selector, { lease: opts.lease });
|
|
326
|
-
const conn =
|
|
448
|
+
const conn = target.webSocketDebuggerUrl
|
|
449
|
+
? await new CdpConnection(target.webSocketDebuggerUrl, opts).connect()
|
|
450
|
+
: await openSession(target.id, opts);
|
|
327
451
|
return { conn, target };
|
|
328
452
|
}
|
|
329
453
|
|
|
@@ -333,7 +457,7 @@ export async function openPage(
|
|
|
333
457
|
*/
|
|
334
458
|
export async function withPage<T>(
|
|
335
459
|
selector: TargetSelector,
|
|
336
|
-
fn: (conn:
|
|
460
|
+
fn: (conn: PageConnection, target: Target) => Promise<T>,
|
|
337
461
|
opts: { timeoutMs?: number; lease?: string } = {},
|
|
338
462
|
): Promise<T> {
|
|
339
463
|
const { conn, target } = await openPage(selector, opts);
|
package/src/endpoints.ts
ADDED
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Named CDP endpoints (issue #15): one process, several DevTools ports.
|
|
3
|
+
*
|
|
4
|
+
* A LEAF MODULE ON PURPOSE. client.ts, leases.ts and origins.ts all import it,
|
|
5
|
+
* so it imports nothing from this package, only node builtins.
|
|
6
|
+
*
|
|
7
|
+
* CONFIG SOURCES, all optional:
|
|
8
|
+
* CDP_BASE the single-endpoint shorthand. It is the endpoint named
|
|
9
|
+
* `default`, stored VERBATIM (no normalization, no
|
|
10
|
+
* validation), so `${base}${path}` is byte-for-byte what
|
|
11
|
+
* it was before this module existed.
|
|
12
|
+
* CDP_ENDPOINTS "browser=http://127.0.0.1:9222,teams=http://127.0.0.1:9333?mode=read"
|
|
13
|
+
* CDP_ENDPOINTS_FILE path to JSON:
|
|
14
|
+
* {"default":"browser","endpoints":{"browser":{"base":"http://127.0.0.1:9222"},
|
|
15
|
+
* "teams":{"base":"http://127.0.0.1:9333","readOnly":true}}}
|
|
16
|
+
* `"mode":"read"` is accepted as an alias of `"readOnly":true`.
|
|
17
|
+
*
|
|
18
|
+
* PRECEDENCE AND MERGING. The env string and the file are merged, never
|
|
19
|
+
* shadowed: a name both define must define it identically (same base, same
|
|
20
|
+
* mode), otherwise it is a config error, so precedence can never silently pick
|
|
21
|
+
* the wrong port. Order (which matters only for listing) is env string, then
|
|
22
|
+
* file. The DEFAULT endpoint is the file's `"default"` key if present, else the
|
|
23
|
+
* endpoint named `default`. When no source defines `default`, it is synthesized
|
|
24
|
+
* from CDP_BASE, else http://127.0.0.1:9222, exactly as before; it is NOT
|
|
25
|
+
* synthesized when the file names a different default and CDP_BASE is unset.
|
|
26
|
+
* When CDP_BASE is set and the config also defines `default`, both must agree on
|
|
27
|
+
* the base.
|
|
28
|
+
*
|
|
29
|
+
* NAMES are [A-Za-z0-9_]+ (no '-'): the name lands in lease and origin
|
|
30
|
+
* filenames as `lease-chrome@<name>-<targetId>.json`, and a '-' in it would make
|
|
31
|
+
* the name/id boundary unparseable.
|
|
32
|
+
*
|
|
33
|
+
* Malformed config throws EndpointConfigError naming the problem. Nothing here
|
|
34
|
+
* caches a failure: a bad file that gets fixed is picked up on the next call,
|
|
35
|
+
* and endpoint reachability is never consulted at all (connect-per-call already
|
|
36
|
+
* retries a port that was down at startup).
|
|
37
|
+
*/
|
|
38
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
39
|
+
import { readFileSync } from "node:fs";
|
|
40
|
+
|
|
41
|
+
export interface Endpoint {
|
|
42
|
+
name: string;
|
|
43
|
+
base: string;
|
|
44
|
+
readOnly: boolean;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export class EndpointConfigError extends Error {
|
|
48
|
+
constructor(message: string) {
|
|
49
|
+
super(message);
|
|
50
|
+
this.name = "EndpointConfigError";
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** The implicit base when nothing is configured; unchanged from client.ts's old const. */
|
|
55
|
+
export const DEFAULT_CDP_BASE = "http://127.0.0.1:9222";
|
|
56
|
+
|
|
57
|
+
/** The selector prefix, e.g. `endpoint:teams/title:Chat`. */
|
|
58
|
+
export const ENDPOINT_PREFIX = "endpoint:";
|
|
59
|
+
|
|
60
|
+
const NAME_RE = /^[A-Za-z0-9_]+$/;
|
|
61
|
+
|
|
62
|
+
export interface EndpointConfig {
|
|
63
|
+
default: Endpoint;
|
|
64
|
+
byName: Map<string, Endpoint>;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function checkName(name: string, where: string): void {
|
|
68
|
+
if (!NAME_RE.test(name)) {
|
|
69
|
+
throw new EndpointConfigError(
|
|
70
|
+
`${where}: endpoint name '${name}' is invalid; names are letters, digits and '_' only (no '-', '/', ':' or spaces)`,
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Compare bases on a trailing-slash-insensitive form. Never used to BUILD a URL. */
|
|
76
|
+
function sameBase(a: string, b: string): boolean {
|
|
77
|
+
return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Parse one configured base URL (from CDP_ENDPOINTS or the file), pulling out `?mode=`. */
|
|
81
|
+
function parseBase(raw: string, where: string): { base: string; mode?: "read" | "write" } {
|
|
82
|
+
let url: URL;
|
|
83
|
+
try {
|
|
84
|
+
url = new URL(raw);
|
|
85
|
+
} catch {
|
|
86
|
+
throw new EndpointConfigError(`${where}: '${raw}' is not a valid URL (expected e.g. http://127.0.0.1:9222)`);
|
|
87
|
+
}
|
|
88
|
+
if (url.protocol !== "http:" && url.protocol !== "https:") {
|
|
89
|
+
throw new EndpointConfigError(`${where}: '${raw}' must be an http:// or https:// DevTools origin, not ${url.protocol}`);
|
|
90
|
+
}
|
|
91
|
+
if (url.hash) throw new EndpointConfigError(`${where}: '${raw}' must not carry a #fragment`);
|
|
92
|
+
let mode: "read" | "write" | undefined;
|
|
93
|
+
for (const [key, value] of url.searchParams) {
|
|
94
|
+
if (key !== "mode") {
|
|
95
|
+
throw new EndpointConfigError(`${where}: unknown query parameter '${key}' in '${raw}' (only ?mode=read or ?mode=write is understood)`);
|
|
96
|
+
}
|
|
97
|
+
if (value !== "read" && value !== "write") {
|
|
98
|
+
throw new EndpointConfigError(`${where}: unknown mode '${value}' in '${raw}' (use mode=read or mode=write)`);
|
|
99
|
+
}
|
|
100
|
+
mode = value;
|
|
101
|
+
}
|
|
102
|
+
const path = url.pathname.replace(/\/+$/, "");
|
|
103
|
+
return { base: `${url.protocol}//${url.host}${path}`, mode };
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function parseEnvString(spec: string): Endpoint[] {
|
|
107
|
+
const out: Endpoint[] = [];
|
|
108
|
+
const seen = new Set<string>();
|
|
109
|
+
for (const part of spec.split(",")) {
|
|
110
|
+
const entry = part.trim();
|
|
111
|
+
if (!entry) continue;
|
|
112
|
+
const eq = entry.indexOf("=");
|
|
113
|
+
if (eq <= 0) {
|
|
114
|
+
throw new EndpointConfigError(`CDP_ENDPOINTS: entry '${entry}' is not name=url (e.g. teams=http://127.0.0.1:9333)`);
|
|
115
|
+
}
|
|
116
|
+
const name = entry.slice(0, eq).trim();
|
|
117
|
+
checkName(name, "CDP_ENDPOINTS");
|
|
118
|
+
if (seen.has(name)) throw new EndpointConfigError(`CDP_ENDPOINTS: duplicate endpoint name '${name}'`);
|
|
119
|
+
seen.add(name);
|
|
120
|
+
const { base, mode } = parseBase(entry.slice(eq + 1).trim(), `CDP_ENDPOINTS endpoint '${name}'`);
|
|
121
|
+
out.push({ name, base, readOnly: mode === "read" });
|
|
122
|
+
}
|
|
123
|
+
return out;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function parseFile(path: string): { endpoints: Endpoint[]; defaultName?: string } {
|
|
127
|
+
let text: string;
|
|
128
|
+
try {
|
|
129
|
+
text = readFileSync(path, "utf8");
|
|
130
|
+
} catch (err) {
|
|
131
|
+
const code = (err as NodeJS.ErrnoException).code ?? String(err);
|
|
132
|
+
throw new EndpointConfigError(`CDP_ENDPOINTS_FILE: cannot read '${path}' (${code})`);
|
|
133
|
+
}
|
|
134
|
+
let json: unknown;
|
|
135
|
+
try {
|
|
136
|
+
json = JSON.parse(text);
|
|
137
|
+
} catch (err) {
|
|
138
|
+
throw new EndpointConfigError(`CDP_ENDPOINTS_FILE: '${path}' is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
|
|
139
|
+
}
|
|
140
|
+
const where = `CDP_ENDPOINTS_FILE '${path}'`;
|
|
141
|
+
if (!json || typeof json !== "object" || Array.isArray(json)) {
|
|
142
|
+
throw new EndpointConfigError(`${where}: top level must be an object {"default"?, "endpoints": {...}}`);
|
|
143
|
+
}
|
|
144
|
+
const top = json as Record<string, unknown>;
|
|
145
|
+
for (const key of Object.keys(top)) {
|
|
146
|
+
if (key !== "default" && key !== "endpoints") throw new EndpointConfigError(`${where}: unknown top-level key '${key}'`);
|
|
147
|
+
}
|
|
148
|
+
if (top.default !== undefined && typeof top.default !== "string") {
|
|
149
|
+
throw new EndpointConfigError(`${where}: "default" must be an endpoint name string`);
|
|
150
|
+
}
|
|
151
|
+
const raw = top.endpoints ?? {};
|
|
152
|
+
if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
|
|
153
|
+
throw new EndpointConfigError(`${where}: "endpoints" must be an object keyed by endpoint name`);
|
|
154
|
+
}
|
|
155
|
+
const endpoints: Endpoint[] = [];
|
|
156
|
+
for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
|
|
157
|
+
checkName(name, where);
|
|
158
|
+
const at = `${where} endpoint '${name}'`;
|
|
159
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
160
|
+
throw new EndpointConfigError(`${at}: must be an object like {"base":"http://127.0.0.1:9333"}`);
|
|
161
|
+
}
|
|
162
|
+
const v = value as Record<string, unknown>;
|
|
163
|
+
for (const key of Object.keys(v)) {
|
|
164
|
+
if (key !== "base" && key !== "readOnly" && key !== "mode") {
|
|
165
|
+
throw new EndpointConfigError(`${at}: unknown key '${key}' (known: base, readOnly, mode)`);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
if (typeof v.base !== "string") throw new EndpointConfigError(`${at}: "base" is required and must be a URL string`);
|
|
169
|
+
if (v.readOnly !== undefined && typeof v.readOnly !== "boolean") throw new EndpointConfigError(`${at}: "readOnly" must be a boolean`);
|
|
170
|
+
if (v.mode !== undefined && v.mode !== "read" && v.mode !== "write") {
|
|
171
|
+
throw new EndpointConfigError(`${at}: unknown mode '${String(v.mode)}' (use "read" or "write")`);
|
|
172
|
+
}
|
|
173
|
+
const parsed = parseBase(v.base, at);
|
|
174
|
+
const votes = [parsed.mode, v.mode as string | undefined, v.readOnly === undefined ? undefined : v.readOnly ? "read" : "write"].filter(
|
|
175
|
+
(x): x is string => x !== undefined,
|
|
176
|
+
);
|
|
177
|
+
if (new Set(votes).size > 1) throw new EndpointConfigError(`${at}: readOnly / mode settings contradict each other`);
|
|
178
|
+
endpoints.push({ name, base: parsed.base, readOnly: votes[0] === "read" });
|
|
179
|
+
}
|
|
180
|
+
return { endpoints, defaultName: top.default as string | undefined };
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Parse the endpoint config out of `env`. Pure apart from reading
|
|
185
|
+
* CDP_ENDPOINTS_FILE; no caching (see the memoized accessors below).
|
|
186
|
+
*/
|
|
187
|
+
export function loadEndpoints(env: NodeJS.ProcessEnv = process.env): EndpointConfig {
|
|
188
|
+
const fromEnv = env.CDP_ENDPOINTS !== undefined ? parseEnvString(env.CDP_ENDPOINTS) : [];
|
|
189
|
+
const file = env.CDP_ENDPOINTS_FILE ? parseFile(env.CDP_ENDPOINTS_FILE) : { endpoints: [] as Endpoint[], defaultName: undefined };
|
|
190
|
+
|
|
191
|
+
const merged = new Map<string, Endpoint>();
|
|
192
|
+
for (const ep of fromEnv) merged.set(ep.name, ep);
|
|
193
|
+
for (const ep of file.endpoints) {
|
|
194
|
+
const prior = merged.get(ep.name);
|
|
195
|
+
if (prior && (prior.base !== ep.base || prior.readOnly !== ep.readOnly)) {
|
|
196
|
+
throw new EndpointConfigError(
|
|
197
|
+
`endpoint '${ep.name}' is defined differently in CDP_ENDPOINTS (${prior.base}${prior.readOnly ? " read-only" : ""}) and CDP_ENDPOINTS_FILE (${ep.base}${ep.readOnly ? " read-only" : ""})`,
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
if (!prior) merged.set(ep.name, ep);
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// CDP_BASE is the endpoint named `default`. Read with `!== undefined`, not
|
|
204
|
+
// truthiness, matching the old `process.env.CDP_BASE ?? ...` exactly.
|
|
205
|
+
const cdpBase = env.CDP_BASE;
|
|
206
|
+
if (cdpBase !== undefined) {
|
|
207
|
+
const configured = merged.get("default");
|
|
208
|
+
if (configured && !sameBase(configured.base, cdpBase)) {
|
|
209
|
+
throw new EndpointConfigError(
|
|
210
|
+
`CDP_BASE (${cdpBase}) and the configured endpoint 'default' (${configured.base}) disagree; drop one or make them match`,
|
|
211
|
+
);
|
|
212
|
+
}
|
|
213
|
+
// Verbatim string, never the normalized one, so a CDP_BASE-only setup builds byte-identical URLs.
|
|
214
|
+
merged.set("default", { name: "default", base: cdpBase, readOnly: configured?.readOnly ?? false });
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
const defaultName = file.defaultName ?? "default";
|
|
218
|
+
if (!merged.has(defaultName)) {
|
|
219
|
+
if (file.defaultName !== undefined) {
|
|
220
|
+
throw new EndpointConfigError(
|
|
221
|
+
`CDP_ENDPOINTS_FILE names default endpoint '${file.defaultName}', which is not defined (known: ${[...merged.keys()].join(", ") || "none"})`,
|
|
222
|
+
);
|
|
223
|
+
}
|
|
224
|
+
merged.set("default", { name: "default", base: DEFAULT_CDP_BASE, readOnly: false });
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// The default endpoint first, then config order: listing order and the lease
|
|
228
|
+
// namespace tie-break (see leaseNamespace) both read this order.
|
|
229
|
+
const def = merged.get(defaultName)!;
|
|
230
|
+
const byName = new Map<string, Endpoint>([[def.name, def]]);
|
|
231
|
+
for (const [name, ep] of merged) if (name !== def.name) byName.set(name, ep);
|
|
232
|
+
return { default: def, byName };
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/* ------------------------------ memoized accessors ------------------------------ */
|
|
236
|
+
|
|
237
|
+
let cache: { sig: string; config: EndpointConfig } | undefined;
|
|
238
|
+
|
|
239
|
+
function signature(env: NodeJS.ProcessEnv): string {
|
|
240
|
+
return JSON.stringify([env.CDP_BASE ?? null, env.CDP_ENDPOINTS ?? null, env.CDP_ENDPOINTS_FILE ?? null]);
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** The process config, re-parsed whenever the three env vars change. Errors are never cached. */
|
|
244
|
+
export function endpointConfig(): EndpointConfig {
|
|
245
|
+
const sig = signature(process.env);
|
|
246
|
+
if (cache?.sig === sig) return cache.config;
|
|
247
|
+
const config = loadEndpoints(process.env);
|
|
248
|
+
cache = { sig, config };
|
|
249
|
+
return config;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** Test hook: forget the memoized config (e.g. after rewriting the file in place). */
|
|
253
|
+
export function resetEndpointCache(): void {
|
|
254
|
+
cache = undefined;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
export function defaultEndpoint(): Endpoint {
|
|
258
|
+
return endpointConfig().default;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** Every configured endpoint, default first. */
|
|
262
|
+
export function allEndpoints(): Endpoint[] {
|
|
263
|
+
return [...endpointConfig().byName.values()];
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
export function getEndpoint(name: string): Endpoint {
|
|
267
|
+
const { byName } = endpointConfig();
|
|
268
|
+
const ep = byName.get(name);
|
|
269
|
+
if (!ep) {
|
|
270
|
+
throw new EndpointConfigError(
|
|
271
|
+
`unknown endpoint '${name}' (known: ${[...byName.keys()].join(", ")}). Configure it with CDP_ENDPOINTS or CDP_ENDPOINTS_FILE.`,
|
|
272
|
+
);
|
|
273
|
+
}
|
|
274
|
+
return ep;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* The lease/origin namespace of an endpoint: undefined means the legacy
|
|
279
|
+
* un-suffixed filenames (`lease-chrome-<id>.json`), shared with older
|
|
280
|
+
* processes. That is the default endpoint, and ANY endpoint whose base equals
|
|
281
|
+
* the default's: two names for one browser must share one lease space, or
|
|
282
|
+
* `endpoint:browser/` would walk straight past a lease held through the
|
|
283
|
+
* default. Two non-default names for one base share the namespace of the first
|
|
284
|
+
* declared.
|
|
285
|
+
*/
|
|
286
|
+
export function leaseNamespace(ep: Endpoint): string | undefined {
|
|
287
|
+
const { default: def, byName } = endpointConfig();
|
|
288
|
+
if (sameBase(ep.base, def.base)) return undefined;
|
|
289
|
+
for (const other of byName.values()) if (sameBase(other.base, ep.base)) return other.name;
|
|
290
|
+
return ep.name;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/* ---------------------------------- selectors ---------------------------------- */
|
|
294
|
+
|
|
295
|
+
/** True when `target` starts with the `endpoint:` prefix. `url:endpoint:x` is NOT a prefix. */
|
|
296
|
+
export function hasEndpointPrefix(target: unknown): target is string {
|
|
297
|
+
return typeof target === "string" && target.startsWith(ENDPOINT_PREFIX);
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* Split `endpoint:<name>/<rest>` into the endpoint and the remaining selector.
|
|
302
|
+
* No prefix: the default endpoint and the selector unchanged. `endpoint:teams`
|
|
303
|
+
* or `endpoint:teams/` alone: rest undefined (the endpoint's active page).
|
|
304
|
+
*/
|
|
305
|
+
export function splitEndpointSelector(target: string | undefined): { endpoint: Endpoint; rest: string | undefined } {
|
|
306
|
+
if (!hasEndpointPrefix(target)) return { endpoint: defaultEndpoint(), rest: target };
|
|
307
|
+
const body = target.slice(ENDPOINT_PREFIX.length);
|
|
308
|
+
const slash = body.indexOf("/");
|
|
309
|
+
const name = slash < 0 ? body : body.slice(0, slash);
|
|
310
|
+
if (!name) throw new EndpointConfigError(`selector '${target}' has an empty endpoint name; use endpoint:<name>/<selector>`);
|
|
311
|
+
const rest = slash < 0 ? undefined : body.slice(slash + 1);
|
|
312
|
+
return { endpoint: getEndpoint(name), rest: rest === "" ? undefined : rest };
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/** Args keys that carry a target selector: `target` everywhere, `targetId` on claim_page. */
|
|
316
|
+
export const SELECTOR_KEYS = ["target", "targetId"] as const;
|
|
317
|
+
|
|
318
|
+
/** The refusal for any endpoint feature under the Firefox backend (mcp.ts and cli.ts). */
|
|
319
|
+
export const ENDPOINTS_FIREFOX_MESSAGE =
|
|
320
|
+
"named CDP endpoints (an 'endpoint:<name>/' selector prefix, the endpoint arg, list_pages allEndpoints) need the Chrome backend; the Firefox BiDi backend has one session and no endpoints";
|
|
321
|
+
|
|
322
|
+
/** True when args ask for any endpoint feature at all (used to refuse them on Firefox, without loading config). */
|
|
323
|
+
export function usesEndpointArgs(args: unknown): boolean {
|
|
324
|
+
if (!args || typeof args !== "object") return false;
|
|
325
|
+
const a = args as Record<string, unknown>;
|
|
326
|
+
return SELECTOR_KEYS.some((k) => hasEndpointPrefix(a[k])) || a.endpoint !== undefined || a.allEndpoints === true;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Resolve the endpoint and strip the prefix: the one place dispatch rewrites
|
|
331
|
+
* args. With no prefix and no `endpoint` key the ORIGINAL object comes back
|
|
332
|
+
* untouched. A prefix that names nothing after the slash deletes the key (so
|
|
333
|
+
* the tool sees its own default, 'active'), and the `endpoint` key itself is
|
|
334
|
+
* removed so no tool's own arg checks ever see it.
|
|
335
|
+
*/
|
|
336
|
+
export function stripEndpointArgs(args: unknown): { endpoint: Endpoint; args: unknown } {
|
|
337
|
+
if (!args || typeof args !== "object" || Array.isArray(args)) return { endpoint: defaultEndpoint(), args };
|
|
338
|
+
const a = args as Record<string, unknown>;
|
|
339
|
+
const picks: Array<{ from: string; endpoint: Endpoint }> = [];
|
|
340
|
+
let out: Record<string, unknown> | undefined;
|
|
341
|
+
for (const key of SELECTOR_KEYS) {
|
|
342
|
+
const v = a[key];
|
|
343
|
+
if (!hasEndpointPrefix(v)) continue;
|
|
344
|
+
const { endpoint, rest } = splitEndpointSelector(v);
|
|
345
|
+
picks.push({ from: `${key} '${v}'`, endpoint });
|
|
346
|
+
out ??= { ...a };
|
|
347
|
+
if (rest === undefined) delete out[key];
|
|
348
|
+
else out[key] = rest;
|
|
349
|
+
}
|
|
350
|
+
if (a.endpoint !== undefined) {
|
|
351
|
+
if (typeof a.endpoint !== "string" || a.endpoint === "") {
|
|
352
|
+
throw new EndpointConfigError("`endpoint` must be a non-empty endpoint name string");
|
|
353
|
+
}
|
|
354
|
+
picks.push({ from: `endpoint '${a.endpoint}'`, endpoint: getEndpoint(a.endpoint) });
|
|
355
|
+
out ??= { ...a };
|
|
356
|
+
delete out.endpoint;
|
|
357
|
+
}
|
|
358
|
+
// A Chrome lease token names its endpoint too (`chrome@<ns>:<targetId>:<nonce>`), so
|
|
359
|
+
// `release_page {lease}` with no prefix acts on the endpoint the lease was taken on,
|
|
360
|
+
// not the default. The token stays in args: the lease scope still reads it.
|
|
361
|
+
const token = leaseTokenNamespace(a.lease);
|
|
362
|
+
if (!picks.length) {
|
|
363
|
+
if (token?.ns === undefined) return { endpoint: defaultEndpoint(), args };
|
|
364
|
+
return { endpoint: endpointForNamespace(token.ns), args };
|
|
365
|
+
}
|
|
366
|
+
const first = picks[0]!;
|
|
367
|
+
for (const p of picks.slice(1)) {
|
|
368
|
+
if (p.endpoint.name !== first.endpoint.name) {
|
|
369
|
+
throw new EndpointConfigError(`conflicting endpoints: ${first.from} vs ${p.from}; name one endpoint per call`);
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
// Compared by lease namespace, not name: two names for one base share one lease space.
|
|
373
|
+
if (token && leaseNamespace(first.endpoint) !== token.ns) {
|
|
374
|
+
throw new EndpointConfigError(
|
|
375
|
+
`conflicting endpoints: ${first.from} vs the lease token, which belongs to ${token.ns === undefined ? "the default endpoint" : `endpoint '${token.ns}'`}; name one endpoint per call`,
|
|
376
|
+
);
|
|
377
|
+
}
|
|
378
|
+
return { endpoint: first.endpoint, args: out ?? a };
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* The lease namespace a Chrome lease token was minted under (leases.ts mintToken:
|
|
383
|
+
* `<backend>:<targetId>:<nonce>`, backend `chrome` or `chrome@<ns>`). `{ns: undefined}`
|
|
384
|
+
* is the default namespace (plain `chrome`). null for anything else: no token, a
|
|
385
|
+
* Firefox token, or a malformed one, which the lease layer rejects on its own terms.
|
|
386
|
+
* Parsed here rather than via leases.ts's tokenParts because this module is a leaf.
|
|
387
|
+
*/
|
|
388
|
+
function leaseTokenNamespace(lease: unknown): { ns: string | undefined } | null {
|
|
389
|
+
if (typeof lease !== "string") return null;
|
|
390
|
+
const colon = lease.indexOf(":");
|
|
391
|
+
if (colon <= 0) return null;
|
|
392
|
+
const head = lease.slice(0, colon);
|
|
393
|
+
if (head === "chrome") return { ns: undefined };
|
|
394
|
+
if (!head.startsWith("chrome@")) return null;
|
|
395
|
+
const ns = head.slice("chrome@".length);
|
|
396
|
+
return NAME_RE.test(ns) ? { ns } : null;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/** The first configured endpoint whose lease namespace is `ns` (see leaseNamespace). */
|
|
400
|
+
function endpointForNamespace(ns: string): Endpoint {
|
|
401
|
+
for (const ep of endpointConfig().byName.values()) if (leaseNamespace(ep) === ns) return ep;
|
|
402
|
+
throw new EndpointConfigError(
|
|
403
|
+
`the lease token belongs to endpoint '${ns}', which is not configured (known: ${[...endpointConfig().byName.keys()].join(", ")})`,
|
|
404
|
+
);
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
/** The endpoint a call's args select (selector prefix, `endpoint` key, or a `chrome@<ns>` lease token), else the default. */
|
|
408
|
+
export function endpointForArgs(args: unknown): Endpoint {
|
|
409
|
+
return stripEndpointArgs(args).endpoint;
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/* ------------------------------------ scope ------------------------------------ */
|
|
413
|
+
|
|
414
|
+
const endpointScope = new AsyncLocalStorage<Endpoint>();
|
|
415
|
+
|
|
416
|
+
/** The endpoint of the enclosing withEndpointScope, else the default endpoint. */
|
|
417
|
+
export function currentEndpoint(): Endpoint {
|
|
418
|
+
return endpointScope.getStore() ?? defaultEndpoint();
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
/** True when the current scope is a non-default endpoint (used to tag output rows). */
|
|
422
|
+
export function isDefaultEndpoint(ep: Endpoint): boolean {
|
|
423
|
+
return ep.name === defaultEndpoint().name;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
export function withEndpointScope<T>(ep: Endpoint, fn: () => Promise<T>): Promise<T> {
|
|
427
|
+
return endpointScope.run(ep, fn);
|
|
428
|
+
}
|