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/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
- /** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
28
- export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
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
- const res = await fetch(`${BASE}${path}`);
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
- /** All targets (GET /json/list). */
203
- export function listTargets(): Promise<Target[]> {
204
- return httpJson<Target[]>("/json/list");
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
- /** Browser-level WebSocket URL (GET /json/version), for Target.* / Browser.*. */
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
- const v = await httpJson<{ webSocketDebuggerUrl: string }>("/json/version");
210
- return v.webSocketDebuggerUrl;
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("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
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("chrome", label, pages.map((t) => t.id));
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
- /** Open a connection to a page target. Returns the connection and the target. */
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: CdpConnection; target: Target }> {
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 = await new CdpConnection(target.webSocketDebuggerUrl, opts).connect();
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: CdpConnection, target: Target) => Promise<T>,
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);
@@ -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
+ }