@storyshelf/core 0.6.2 → 0.8.0

package/dist/adapters/remote-browser.mjs

@@ -0,0 +1,201 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { TARGET_NAME_PATTERN, isBrowserName } from "./capture-target.mjs";
+// src/adapters/remote-browser.ts
+/**
+* Remote browsers (ADR 0007, decisions 1 and 3): one service a runner connects to instead of
+* launching a browser, expanding to one `<engine>@<name>` target per engine. Presets are plain
+* configuration over {@link defineRemote}; the runners add only what they can drive.
+*/
+/** Default bound on measuring a connected remote browser's environment (`timeouts.probeMs`). */
+const DEFAULT_PROBE_MS = 15e3;
+const CDP_ENGINES = /* @__PURE__ */ new Set(["chromium", "chrome"]);
+const SCHEMES = {
+	playwright: ["ws:", "wss:"],
+	cdp: [
+		"ws:",
+		"wss:",
+		"http:",
+		"https:"
+	]
+};
+/** Options 0.7 took that 0.8 renamed or removed, with what replaces them (a loud migration error). */
+const MOVED = {
+	acquire: "merge it into `connect` (a function that receives a context)",
+	exposeNetwork: "declare `reach: \"loopback\"` on the service instead",
+	connectRetries: "use `retry: { attempts }`",
+	connectBackoffMs: "use `retry: { backoffMs }`",
+	connectTimeoutMs: "use `timeouts: { connectMs }`",
+	acquireTimeoutMs: "use `timeouts: { acquireMs }`"
+};
+const KNOWN = /* @__PURE__ */ new Set([
+	"name",
+	"engines",
+	"sessions",
+	"maxPagesPerConnection",
+	"maxConnections",
+	"protocol",
+	"reach",
+	"connect",
+	"release",
+	"platform",
+	"retry",
+	"timeouts"
+]);
+/**
+* Validate a remote service eagerly, so a mistake fails when the runner is created and not when the
+* first build runs: unknown or moved options, the name, the sessions, the engines against what the
+* runner drives, the protocol, the reach, and a fixed connection (endpoint scheme).
+*/
+function defineRemote(options, support) {
+	const plain = options;
+	checkOptions(plain, support);
+	checkEngines(plain, support);
+	checkProtocol(plain, support);
+	return {
+		kind: "remote",
+		name: options.name,
+		engines: [...options.engines],
+		sessions: options.sessions,
+		maxPagesPerConnection: options.maxPagesPerConnection,
+		maxConnections: options.maxConnections,
+		protocol: options.protocol,
+		reach: options.reach,
+		connect: options.connect,
+		release: options.release,
+		platform: options.platform,
+		retry: {
+			attempts: options.retry?.attempts ?? 3,
+			backoffMs: options.retry?.backoffMs ?? 500
+		},
+		timeouts: {
+			acquireMs: options.timeouts?.acquireMs ?? 3e4,
+			connectMs: options.timeouts?.connectMs ?? 3e4,
+			releaseMs: options.timeouts?.releaseMs ?? 3e4,
+			probeMs: options.timeouts?.probeMs ?? 15e3
+		}
+	};
+}
+/** The targets a service offers, in the order of its `engines`. */
+function remoteTargetsOf(remote) {
+	return remote.engines.map((engine) => ({
+		kind: "remote",
+		target: `${engine}@${remote.name}`,
+		engine,
+		remote,
+		reach: remote.reach
+	}));
+}
+/** Whether a value is a remote service entry. */
+function isRemoteBrowser(value) {
+	return typeof value === "object" && value !== null && value.kind === "remote";
+}
+/** Whether `endpoint` has a scheme `protocol` can open. */
+function hasSchemeFor(protocol, endpoint) {
+	try {
+		return SCHEMES[protocol].includes(new URL(endpoint).protocol);
+	} catch {
+		return false;
+	}
+}
+/** The schemes `protocol` accepts, for messages. */
+function schemesOf(protocol) {
+	return SCHEMES[protocol].join(" or ");
+}
+/**
+* Remove what identifies the connection from text surfaced to operators: the endpoint (it can carry
+* a key in its path or query), its host and path, its query values, every header value and every
+* value inside the lease (non-strings are stringified).
+*/
+function scrubConnection(text, connection) {
+	const secrets = [
+		connection.endpoint,
+		...Object.values(connection.headers ?? {}),
+		...leaseSecrets(connection.lease)
+	];
+	try {
+		const url = new URL(connection.endpoint);
+		secrets.push(url.password, ...url.searchParams.values(), decodeURIComponent(url.search), `${url.protocol}//${url.host}${url.pathname}`, url.host, url.pathname);
+	} catch {}
+	let scrubbed = text;
+	for (const secret of secrets.filter((value) => value.length >= 4).toSorted((a, b) => b.length - a.length)) scrubbed = scrubbed.replaceAll(secret, "[redacted]");
+	return scrubbed;
+}
+/** Every value of a lease, as text: a string whole, anything else stringified, objects walked. */
+function leaseSecrets(lease, depth = 0) {
+	if (lease === void 0 || lease === null) return [];
+	if (typeof lease === "object") return depth > 3 ? [] : Object.values(lease).flatMap((value) => leaseSecrets(value, depth + 1));
+	return typeof lease === "string" || typeof lease === "number" || typeof lease === "boolean" ? [String(lease)] : [];
+}
+function checkKnownKeys(options, where) {
+	for (const key of Object.keys(options)) if (!KNOWN.has(key)) {
+		const moved = MOVED[key];
+		throw new Error(moved === void 0 ? `${where}: unknown option "${key}"` : `${where}: option "${key}" is gone in 0.8: ${moved}`);
+	}
+}
+function checkOptions(options, { label }) {
+	const where = `${label} "${options.name}"`;
+	checkKnownKeys(options, where);
+	if (!TARGET_NAME_PATTERN.test(options.name)) throw new Error(`${label}: name "${options.name}" must be lowercase letters, digits and hyphens, start with a letter or digit and be at most 32 characters`);
+	checkSessions(options.sessions, where);
+	checkPositiveInteger("maxPagesPerConnection", options.maxPagesPerConnection, where);
+	checkPositiveInteger("maxConnections", options.maxConnections, where);
+	checkNumbers(options, where);
+	if (options.release !== void 0 && typeof options.connect !== "function") throw new Error(`${where}: release needs a function connect (a fixed connection has no lease)`);
+}
+/** An optional limit: absent, or a whole number of at least 1. */
+function checkPositiveInteger(name, value, where) {
+	if (value !== void 0 && (!Number.isInteger(value) || value < 1)) throw new Error(`${where}: ${name} must be a positive integer`);
+}
+function checkSessions(sessions, where) {
+	const value = typeof sessions === "function" ? sessions() : sessions;
+	if (!Number.isInteger(value) || value < 1) throw new Error(`${where}: sessions must be a positive integer`);
+}
+function checkNumbers(options, where) {
+	const entries = [
+		["retry.attempts", options.retry?.attempts],
+		["timeouts.acquireMs", options.timeouts?.acquireMs],
+		["timeouts.connectMs", options.timeouts?.connectMs],
+		["timeouts.releaseMs", options.timeouts?.releaseMs],
+		["timeouts.probeMs", options.timeouts?.probeMs],
+		["retry.backoffMs", options.retry?.backoffMs]
+	];
+	for (const [name, value] of entries) {
+		const allowed = name === "retry.attempts" || name === "retry.backoffMs" ? 0 : 1;
+		if (value !== void 0 && (!Number.isInteger(value) || value < allowed)) throw new Error(`${where}: ${name} must be an integer of at least ${allowed}`);
+	}
+}
+function checkEngines(options, support) {
+	const where = `${support.label} "${options.name}"`;
+	if (options.engines.length === 0) throw new Error(`${where}: engines must list at least one engine`);
+	for (const [index, engine] of options.engines.entries()) {
+		if (!isBrowserName(engine)) throw new Error(`${where}: unknown engine "${String(engine)}"`);
+		if (!support.engines.includes(engine)) throw new Error(`${where}: this runner cannot drive "${engine}" (it drives ${support.engines.join(", ")})`);
+		if (options.engines.indexOf(engine) !== index) throw new Error(`${where}: engine "${engine}" is listed twice`);
+	}
+}
+function checkProtocol(options, support) {
+	const where = `${support.label} "${options.name}"`;
+	checkDeclared(options, support, where);
+	if (options.protocol === "cdp") checkCdp(options, where);
+	if (typeof options.connect !== "function") checkFixedConnection(options.connect, options.protocol, where);
+}
+function checkDeclared(options, support, where) {
+	if (options.protocol === void 0 || options.reach === void 0) throw new Error(`${where}: "protocol" and "reach" are required in 0.8 (declare how the runner talks to the service and whether its browser can reach this host)`);
+	if (!support.protocols.includes(options.protocol)) throw new Error(`${where}: protocol "${options.protocol}" is not supported by this runner (it speaks ${support.protocols.join(", ")})`);
+	if (options.reach !== "loopback" && options.reach !== "url") throw new Error(`${where}: reach must be "loopback" or "url"`);
+}
+function checkCdp(options, where) {
+	const bad = options.engines.find((engine) => !CDP_ENGINES.has(engine));
+	if (bad !== void 0) throw new Error(`${where}: the CDP protocol drives Chromium only, not "${bad}"`);
+	if (options.reach === "loopback") throw new Error(`${where}: reach "loopback" needs the "playwright" protocol`);
+}
+function checkFixedConnection(connection, protocol, where) {
+	const extra = Object.keys(connection).filter((key) => key !== "endpoint" && key !== "headers");
+	if (extra.length > 0) throw new Error(`${where}: connect has unknown field(s) ${extra.join(", ")}`);
+	if (!hasSchemeFor(protocol, connection.endpoint)) throw new Error(`${where}: the endpoint must be a ${schemesOf(protocol)} URL`);
+}
+export { DEFAULT_PROBE_MS, defineRemote, hasSchemeFor, isRemoteBrowser, remoteTargetsOf, schemesOf, scrubConnection };
+
+//# sourceMappingURL=remote-browser.mjs.map

package/dist/adapters/remote-browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-browser.mjs","names":[],"sources":["../../src/adapters/remote-browser.ts"],"sourcesContent":["/**\n * Remote browsers (ADR 0007, decisions 1 and 3): one service a runner connects to instead of\n * launching a browser, expanding to one `<engine>@<name>` target per engine. Presets are plain\n * configuration over {@link defineRemote}; the runners add only what they can drive.\n */\nimport {\n  TARGET_NAME_PATTERN,\n  isBrowserName,\n  type BrowserName,\n  type CaptureTarget,\n  type TargetReach,\n} from \"./capture-target.ts\";\n\n/** Default bound on measuring a connected remote browser's environment (`timeouts.probeMs`). */\nexport const DEFAULT_PROBE_MS = 15_000;\n\n/** How a runner talks to the service: Playwright's own protocol, or the Chrome DevTools Protocol. */\nexport type RemoteProtocol = \"playwright\" | \"cdp\";\n\n/** Where and how to connect. A function `connect` is called per connection, so a token can be fresh. */\nexport interface RemoteConnection {\n  /** `ws(s)://…` (CDP also accepts `http(s)://…`). May carry credentials: it is never logged. */\n  endpoint: string;\n  /** Request headers for the handshake, such as `authorization`. Never logged. */\n  headers?: Record<string, string>;\n}\n\n/** A connection a function `connect` returns, with what `release` needs back. */\nexport interface RemoteLeasedConnection<TLease = unknown> extends RemoteConnection {\n  /** Opaque to the runner, handed to `release` once and never logged (it may carry credentials). */\n  lease?: TLease | undefined;\n}\n\n/** What a run is doing when it connects. */\nexport type RemotePurpose = \"render\" | \"extract\" | \"tests\";\n\n/** How a leased connection ended, handed to `release`. */\nexport type RemoteLeaseOutcome = \"finished\" | \"failed\" | \"cancelled\";\n\n/** What a function `connect` is told about the connection it is asked for. */\nexport interface RemoteConnectContext {\n  engine: BrowserName;\n  /** The StoryShelf build; the same for every shard of it. */\n  buildId: string;\n  /** The shard's own id; the build id when the render is not sharded. */\n  runId: string;\n  /** The shard's 1-based position in the build's plan; `undefined` (never 0) when not sharded. */\n  shardIndex?: number | undefined;\n  /** `render` for a build or shard, `extract` for the parameter pre-pass, `tests` for `.test()` entries. */\n  purpose: RemotePurpose;\n  /** This connection's attempt, from 1; each retry connects anew. */\n  attempt: number;\n  /**\n   * Aborts while `connect` is pending: on `timeouts.acquireMs`, a cancel (user, build, render\n   * budget) and shutdown. Spent once `connect` resolves.\n   */\n  signal: AbortSignal;\n}\n\n/** What `release` is told about how the connection's render went. */\nexport interface RemoteReleaseInfo {\n  outcome: RemoteLeaseOutcome;\n  /** Why it failed, for `failed`. Carries no credentials, but may carry provider text. */\n  error?: unknown;\n}\n\n/** What {@link defineRemote} takes: what `remote()` exposes to operators. */\nexport interface RemoteOptions<TLease = unknown> {\n  /** The target name half (`chromium@<name>`): lowercase letters, digits and hyphens, at most 32. */\n  name: string;\n  /** The engines to offer (a subset of what the service has). */\n  engines: readonly BrowserName[];\n  /** Parallel sessions the plan allows: the page cap of the target, per process (decision 4). A function is read live. */\n  sessions: number | (() => number);\n  /** Maximum concurrent pages on each browser connection; independent of the shared session gate. */\n  maxPagesPerConnection?: number | undefined;\n  /**\n   * Maximum connections this process holds to the service at once (default: no cap). A separate\n   * limit from `sessions` (pages) and `maxPagesPerConnection`: a connection counts from the moment\n   * it is requested until its render has ended, a shared one once. Renders over the cap wait, and a\n   * cancel or shutdown ends the wait. Per process; the deployment-wide cap is another issue.\n   */\n  maxConnections?: number | undefined;\n  /** Declared, never inferred: how the runner talks to the service. */\n  protocol: RemoteProtocol;\n  /**\n   * Declared, never inferred: `loopback` when the remote browser can route back to this host\n   * (Playwright's `exposeNetwork: \"<loopback>\"`), else `url` (it needs a signed Storybook URL).\n   */\n  reach: TargetReach;\n  /**\n   * The connection: an object for a fixed service (validated at creation), or a function called\n   * for every connection (sync or async) to wake or start something, pick a server per shard, or\n   * mint a token. A throw is retried and ends as a `TargetLaunchError`.\n   */\n  connect:\n    | RemoteConnection\n    | ((\n        context: RemoteConnectContext,\n      ) => RemoteLeasedConnection<TLease> | Promise<RemoteLeasedConnection<TLease>>);\n  /**\n   * Called once for every connection `connect` returned a `lease` for, after the render that used\n   * it finished, failed or was cancelled (and for leases still held at shutdown, `cancelled`).\n   * Only valid with a function `connect`. A throw or a timeout (`timeouts.releaseMs`) is logged and\n   * never fails the render.\n   */\n  release?: ((lease: TLease, info: RemoteReleaseInfo) => Promise<void> | void) | undefined;\n  /** OS the service renders on, reported when the page cannot tell (`linux-x64`, `windows`, …). */\n  platform?: string | undefined;\n  /** Connect retries: `attempts` after the first (default 3), `backoffMs` doubling (default 500). */\n  retry?: { attempts?: number | undefined; backoffMs?: number | undefined } | undefined;\n  /**\n   * `acquireMs` bounds the `connect` function, `connectMs` the handshake after it (a farm with a\n   * client cap queues extra connections, so a busy farm shows up as this timeout), `releaseMs`\n   * the `release` hook. All default to 30 000. `probeMs` bounds measuring the browser's\n   * environment once connected (default 15 000): a probe that overruns leaves the environment\n   * unknown with a warning, and a cancel stops it at once.\n   */\n  timeouts?:\n    | {\n        acquireMs?: number | undefined;\n        connectMs?: number | undefined;\n        releaseMs?: number | undefined;\n        probeMs?: number | undefined;\n      }\n    | undefined;\n}\n\n/** One remote service, validated: an entry of a runner's `browsers`. */\nexport interface RemoteBrowser {\n  readonly kind: \"remote\";\n  readonly name: string;\n  readonly engines: readonly BrowserName[];\n  readonly sessions: number | (() => number);\n  readonly maxPagesPerConnection?: number | undefined;\n  readonly maxConnections?: number | undefined;\n  readonly protocol: RemoteProtocol;\n  readonly reach: TargetReach;\n  readonly connect: RemoteOptions[\"connect\"];\n  readonly release: ((lease: never, info: RemoteReleaseInfo) => Promise<void> | void) | undefined;\n  readonly platform: string | undefined;\n  readonly retry: { readonly attempts: number; readonly backoffMs: number };\n  readonly timeouts: {\n    readonly acquireMs: number;\n    readonly connectMs: number;\n    readonly releaseMs: number;\n    readonly probeMs: number;\n  };\n}\n\n/** What a runner supports, which {@link defineRemote} checks the service against. */\nexport interface RemoteSupport {\n  /** Engines the runner can drive. */\n  engines: readonly BrowserName[];\n  /** Protocols the runner can speak. */\n  protocols: readonly RemoteProtocol[];\n  /** Shown in errors, for example `remote()`. */\n  label: string;\n}\n\n/** One target a remote service offers. */\nexport interface RemoteTarget {\n  kind: \"remote\";\n  target: CaptureTarget;\n  engine: BrowserName;\n  remote: RemoteBrowser;\n  /** How the browser reaches the Storybook. */\n  reach: TargetReach;\n}\n\nconst CDP_ENGINES = new Set<BrowserName>([\"chromium\", \"chrome\"]);\nconst SCHEMES: Record<RemoteProtocol, readonly string[]> = {\n  playwright: [\"ws:\", \"wss:\"],\n  cdp: [\"ws:\", \"wss:\", \"http:\", \"https:\"],\n};\n\n/** Options 0.7 took that 0.8 renamed or removed, with what replaces them (a loud migration error). */\nconst MOVED: Record<string, string> = {\n  acquire: \"merge it into `connect` (a function that receives a context)\",\n  exposeNetwork: 'declare `reach: \"loopback\"` on the service instead',\n  connectRetries: \"use `retry: { attempts }`\",\n  connectBackoffMs: \"use `retry: { backoffMs }`\",\n  connectTimeoutMs: \"use `timeouts: { connectMs }`\",\n  acquireTimeoutMs: \"use `timeouts: { acquireMs }`\",\n};\n\nconst KNOWN = new Set([\n  \"name\",\n  \"engines\",\n  \"sessions\",\n  \"maxPagesPerConnection\",\n  \"maxConnections\",\n  \"protocol\",\n  \"reach\",\n  \"connect\",\n  \"release\",\n  \"platform\",\n  \"retry\",\n  \"timeouts\",\n]);\n\n/**\n * Validate a remote service eagerly, so a mistake fails when the runner is created and not when the\n * first build runs: unknown or moved options, the name, the sessions, the engines against what the\n * runner drives, the protocol, the reach, and a fixed connection (endpoint scheme).\n */\nexport function defineRemote<TLease = unknown>(\n  options: RemoteOptions<TLease>,\n  support: RemoteSupport,\n): RemoteBrowser {\n  const plain = options as unknown as RemoteOptions;\n  checkOptions(plain, support);\n  checkEngines(plain, support);\n  checkProtocol(plain, support);\n  return {\n    kind: \"remote\",\n    name: options.name,\n    engines: [...options.engines],\n    sessions: options.sessions,\n    maxPagesPerConnection: options.maxPagesPerConnection,\n    maxConnections: options.maxConnections,\n    protocol: options.protocol,\n    reach: options.reach,\n    connect: options.connect,\n    release: options.release,\n    platform: options.platform,\n    retry: { attempts: options.retry?.attempts ?? 3, backoffMs: options.retry?.backoffMs ?? 500 },\n    timeouts: {\n      acquireMs: options.timeouts?.acquireMs ?? 30_000,\n      connectMs: options.timeouts?.connectMs ?? 30_000,\n      releaseMs: options.timeouts?.releaseMs ?? 30_000,\n      probeMs: options.timeouts?.probeMs ?? DEFAULT_PROBE_MS,\n    },\n  };\n}\n\n/** The targets a service offers, in the order of its `engines`. */\nexport function remoteTargetsOf(remote: RemoteBrowser): RemoteTarget[] {\n  return remote.engines.map((engine) => ({\n    kind: \"remote\",\n    target: `${engine}@${remote.name}`,\n    engine,\n    remote,\n    reach: remote.reach,\n  }));\n}\n\n/** Whether a value is a remote service entry. */\nexport function isRemoteBrowser(value: unknown): value is RemoteBrowser {\n  return typeof value === \"object\" && value !== null && (value as RemoteBrowser).kind === \"remote\";\n}\n\n/** Whether `endpoint` has a scheme `protocol` can open. */\nexport function hasSchemeFor(protocol: RemoteProtocol, endpoint: string): boolean {\n  try {\n    return SCHEMES[protocol].includes(new URL(endpoint).protocol);\n  } catch {\n    return false;\n  }\n}\n\n/** The schemes `protocol` accepts, for messages. */\nexport function schemesOf(protocol: RemoteProtocol): string {\n  return SCHEMES[protocol].join(\" or \");\n}\n\n/**\n * Remove what identifies the connection from text surfaced to operators: the endpoint (it can carry\n * a key in its path or query), its host and path, its query values, every header value and every\n * value inside the lease (non-strings are stringified).\n */\nexport function scrubConnection(\n  text: string,\n  connection: RemoteConnection & { lease?: unknown },\n): string {\n  const secrets = [\n    connection.endpoint,\n    ...Object.values(connection.headers ?? {}),\n    ...leaseSecrets(connection.lease),\n  ];\n  try {\n    const url = new URL(connection.endpoint);\n    // Drivers echo the endpoint without its query; the host and a path that acts as a key stay hidden.\n    secrets.push(\n      url.password,\n      ...url.searchParams.values(),\n      decodeURIComponent(url.search),\n      `${url.protocol}//${url.host}${url.pathname}`,\n      url.host,\n      url.pathname,\n    );\n  } catch {\n    // An unparsable endpoint is scrubbed whole above.\n  }\n  let scrubbed = text;\n  // Longest first: the endpoint goes before the fragments it contains.\n  for (const secret of secrets\n    .filter((value) => value.length >= 4)\n    .toSorted((a, b) => b.length - a.length)) {\n    scrubbed = scrubbed.replaceAll(secret, \"[redacted]\");\n  }\n  return scrubbed;\n}\n\n/** Every value of a lease, as text: a string whole, anything else stringified, objects walked. */\nfunction leaseSecrets(lease: unknown, depth = 0): string[] {\n  if (lease === undefined || lease === null) {\n    return [];\n  }\n  if (typeof lease === \"object\") {\n    return depth > 3 ? [] : Object.values(lease).flatMap((value) => leaseSecrets(value, depth + 1));\n  }\n  return typeof lease === \"string\" || typeof lease === \"number\" || typeof lease === \"boolean\"\n    ? [String(lease)]\n    : [];\n}\n\nfunction checkKnownKeys(options: RemoteOptions, where: string): void {\n  for (const key of Object.keys(options)) {\n    if (!KNOWN.has(key)) {\n      const moved = MOVED[key];\n      throw new Error(\n        moved === undefined\n          ? `${where}: unknown option \"${key}\"`\n          : `${where}: option \"${key}\" is gone in 0.8: ${moved}`,\n      );\n    }\n  }\n}\n\nfunction checkOptions(options: RemoteOptions, { label }: RemoteSupport): void {\n  const where = `${label} \"${options.name}\"`;\n  checkKnownKeys(options, where);\n  if (!TARGET_NAME_PATTERN.test(options.name)) {\n    throw new Error(\n      `${label}: name \"${options.name}\" must be lowercase letters, digits and hyphens, start with a letter or digit and be at most 32 characters`,\n    );\n  }\n  checkSessions(options.sessions, where);\n  checkPositiveInteger(\"maxPagesPerConnection\", options.maxPagesPerConnection, where);\n  checkPositiveInteger(\"maxConnections\", options.maxConnections, where);\n  checkNumbers(options, where);\n  if (options.release !== undefined && typeof options.connect !== \"function\") {\n    throw new Error(`${where}: release needs a function connect (a fixed connection has no lease)`);\n  }\n}\n\n/** An optional limit: absent, or a whole number of at least 1. */\nfunction checkPositiveInteger(name: string, value: number | undefined, where: string): void {\n  if (value !== undefined && (!Number.isInteger(value) || value < 1)) {\n    throw new Error(`${where}: ${name} must be a positive integer`);\n  }\n}\n\nfunction checkSessions(sessions: RemoteOptions[\"sessions\"], where: string): void {\n  const value = typeof sessions === \"function\" ? sessions() : sessions;\n  if (!Number.isInteger(value) || value < 1) {\n    throw new Error(`${where}: sessions must be a positive integer`);\n  }\n}\n\nfunction checkNumbers(options: RemoteOptions, where: string): void {\n  const entries: [string, number | undefined][] = [\n    [\"retry.attempts\", options.retry?.attempts],\n    [\"timeouts.acquireMs\", options.timeouts?.acquireMs],\n    [\"timeouts.connectMs\", options.timeouts?.connectMs],\n    [\"timeouts.releaseMs\", options.timeouts?.releaseMs],\n    [\"timeouts.probeMs\", options.timeouts?.probeMs],\n    [\"retry.backoffMs\", options.retry?.backoffMs],\n  ];\n  for (const [name, value] of entries) {\n    const allowed = name === \"retry.attempts\" || name === \"retry.backoffMs\" ? 0 : 1;\n    if (value !== undefined && (!Number.isInteger(value) || value < allowed)) {\n      throw new Error(`${where}: ${name} must be an integer of at least ${allowed}`);\n    }\n  }\n}\n\nfunction checkEngines(options: RemoteOptions, support: RemoteSupport): void {\n  const where = `${support.label} \"${options.name}\"`;\n  if (options.engines.length === 0) {\n    throw new Error(`${where}: engines must list at least one engine`);\n  }\n  for (const [index, engine] of options.engines.entries()) {\n    if (!isBrowserName(engine)) {\n      throw new Error(`${where}: unknown engine \"${String(engine)}\"`);\n    }\n    if (!support.engines.includes(engine)) {\n      throw new Error(\n        `${where}: this runner cannot drive \"${engine}\" (it drives ${support.engines.join(\", \")})`,\n      );\n    }\n    if (options.engines.indexOf(engine) !== index) {\n      throw new Error(`${where}: engine \"${engine}\" is listed twice`);\n    }\n  }\n}\n\nfunction checkProtocol(options: RemoteOptions, support: RemoteSupport): void {\n  const where = `${support.label} \"${options.name}\"`;\n  checkDeclared(options, support, where);\n  if (options.protocol === \"cdp\") {\n    checkCdp(options, where);\n  }\n  if (typeof options.connect !== \"function\") {\n    checkFixedConnection(options.connect, options.protocol, where);\n  }\n}\n\nfunction checkDeclared(options: RemoteOptions, support: RemoteSupport, where: string): void {\n  if (options.protocol === undefined || options.reach === undefined) {\n    throw new Error(\n      `${where}: \"protocol\" and \"reach\" are required in 0.8 (declare how the runner talks to the service and whether its browser can reach this host)`,\n    );\n  }\n  if (!support.protocols.includes(options.protocol)) {\n    throw new Error(\n      `${where}: protocol \"${options.protocol}\" is not supported by this runner (it speaks ${support.protocols.join(\", \")})`,\n    );\n  }\n  if (options.reach !== \"loopback\" && options.reach !== \"url\") {\n    throw new Error(`${where}: reach must be \"loopback\" or \"url\"`);\n  }\n}\n\nfunction checkCdp(options: RemoteOptions, where: string): void {\n  const bad = options.engines.find((engine) => !CDP_ENGINES.has(engine));\n  if (bad !== undefined) {\n    throw new Error(`${where}: the CDP protocol drives Chromium only, not \"${bad}\"`);\n  }\n  if (options.reach === \"loopback\") {\n    throw new Error(`${where}: reach \"loopback\" needs the \"playwright\" protocol`);\n  }\n}\n\nfunction checkFixedConnection(\n  connection: RemoteConnection,\n  protocol: RemoteProtocol,\n  where: string,\n): void {\n  const extra = Object.keys(connection).filter((key) => key !== \"endpoint\" && key !== \"headers\");\n  if (extra.length > 0) {\n    throw new Error(`${where}: connect has unknown field(s) ${extra.join(\", \")}`);\n  }\n  if (!hasSchemeFor(protocol, connection.endpoint)) {\n    throw new Error(`${where}: the endpoint must be a ${schemesOf(protocol)} URL`);\n  }\n}\n"],"mappings":"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"}

package/dist/adapters/remote-lease-attempt.mjs

@@ -0,0 +1,39 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/adapters/remote-lease-attempt.ts
+const attempts = /* @__PURE__ */ new Set();
+/** Start an attempt tied to the run's signal; a signal already aborted stops it at once. */
+function startAttempt(parent) {
+	const controller = new AbortController();
+	const onAbort = () => {
+		attempt.stop();
+	};
+	const attempt = {
+		controller,
+		stopped: false,
+		stop: () => {
+			attempt.stopped = true;
+			controller.abort();
+		},
+		detach: () => {
+			parent?.removeEventListener("abort", onAbort);
+		}
+	};
+	attempts.add(attempt);
+	if (parent?.aborted === true) attempt.stop();
+	else parent?.addEventListener("abort", onAbort, { once: true });
+	return attempt;
+}
+/** The attempt is over: forget it and stop listening to the run's signal. */
+function endAttempt(attempt) {
+	attempts.delete(attempt);
+	attempt.detach();
+}
+/** Stop every attempt still pending (shutdown). */
+function stopAllAttempts() {
+	for (const attempt of attempts) attempt.stop();
+}
+export { endAttempt, startAttempt, stopAllAttempts };
+
+//# sourceMappingURL=remote-lease-attempt.mjs.map

package/dist/adapters/remote-lease-attempt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-lease-attempt.mjs","names":[],"sources":["../../src/adapters/remote-lease-attempt.ts"],"sourcesContent":["/** A `connect` attempt in flight, so a cancel or shutdown can reach it (ADR 0007, decision 4). */\n\n/** A `connect` attempt in flight: aborted by its deadline, a cancel or shutdown. */\nexport interface Attempt {\n  readonly controller: AbortController;\n  stopped: boolean;\n  stop(): void;\n  /** Stop listening to the run's signal, so retries do not pile up listeners on it. */\n  detach(): void;\n}\n\nconst attempts = new Set<Attempt>();\n\n/** Start an attempt tied to the run's signal; a signal already aborted stops it at once. */\nexport function startAttempt(parent?: AbortSignal): Attempt {\n  const controller = new AbortController();\n  const onAbort = (): void => {\n    attempt.stop();\n  };\n  const attempt: Attempt = {\n    controller,\n    stopped: false,\n    stop: () => {\n      attempt.stopped = true;\n      controller.abort();\n    },\n    detach: () => {\n      parent?.removeEventListener(\"abort\", onAbort);\n    },\n  };\n  attempts.add(attempt);\n  if (parent?.aborted === true) {\n    attempt.stop();\n  } else {\n    parent?.addEventListener(\"abort\", onAbort, { once: true });\n  }\n  return attempt;\n}\n\n/** The attempt is over: forget it and stop listening to the run's signal. */\nexport function endAttempt(attempt: Attempt): void {\n  attempts.delete(attempt);\n  attempt.detach();\n}\n\n/** Stop every attempt still pending (shutdown). */\nexport function stopAllAttempts(): void {\n  for (const attempt of attempts) {\n    attempt.stop();\n  }\n}\n"],"mappings":";;;;AAWA,MAAM,2BAAW,IAAI,IAAa;;AAGlC,SAAgB,aAAa,QAA+B;CAC1D,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,gBAAsB;EAC1B,QAAQ,KAAK;CACf;CACA,MAAM,UAAmB;EACvB;EACA,SAAS;EACT,YAAY;GACV,QAAQ,UAAU;GAClB,WAAW,MAAM;EACnB;EACA,cAAc;GACZ,QAAQ,oBAAoB,SAAS,OAAO;EAC9C;CACF;CACA,SAAS,IAAI,OAAO;CACpB,IAAI,QAAQ,YAAY,MACtB,QAAQ,KAAK;MAEb,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAE3D,OAAO;AACT;;AAGA,SAAgB,WAAW,SAAwB;CACjD,SAAS,OAAO,OAAO;CACvB,QAAQ,OAAO;AACjB;;AAGA,SAAgB,kBAAwB;CACtC,KAAK,MAAM,WAAW,UACpB,QAAQ,KAAK;AAEjB"}

package/dist/adapters/remote-lease-error.d.mts

@@ -0,0 +1,25 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** What a connect failure means for the retry loop and for the target. */
+interface RemoteConnectErrorOptions {
+  /** `false` stops the retries and fails the job (default `true`: retried). */
+  transient?: boolean | undefined;
+  /**
+   * For `transient: false`: `target` (default) also marks the target unavailable until restart,
+   * `job` fails only this job and keeps the target offered (a per-shard server that is gone).
+   */
+  scope?: "target" | "job" | undefined;
+  /** A lease the failed `connect` already took, released as `failed`. */
+  lease?: unknown;
+  cause?: unknown;
+}
+/** An error a function `connect` throws to say how the runner should treat the failure. */
+declare class RemoteConnectError extends Error {
+  readonly name = "RemoteConnectError";
+  readonly transient: boolean;
+  readonly scope: "target" | "job";
+  readonly lease: unknown;
+  constructor(message: string, options?: RemoteConnectErrorOptions);
+}
+export { RemoteConnectError, RemoteConnectErrorOptions };
+//# sourceMappingURL=remote-lease-error.d.mts.map

package/dist/adapters/remote-lease-error.mjs

@@ -0,0 +1,54 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { isRetryableConnectError } from "../utils/connect-retry.mjs";
+// src/adapters/remote-lease-error.ts
+/** How a connect failure is classified (ADR 0007, decision 4): retried or not, and what it does to the target. */
+/** An error a function `connect` throws to say how the runner should treat the failure. */
+var RemoteConnectError = class extends Error {
+	name = "RemoteConnectError";
+	transient;
+	scope;
+	lease;
+	constructor(message, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.transient = options.transient ?? true;
+		this.scope = options.scope ?? "target";
+		this.lease = options.lease;
+	}
+};
+/** Marks the error of a `connect` abandoned because the run was cancelled or the process is shutting down. */
+const STOPPED = Symbol("remote connect stopped");
+/** The error of a `connect` that was cancelled or cut short by shutdown: never retried. */
+function stoppedError() {
+	return Object.assign(/* @__PURE__ */ new Error("cancelled while connecting"), { [STOPPED]: true });
+}
+/** What a connect error means: whether to retry it, and whether it marks the target unavailable. */
+function classify(error) {
+	if (typeof error === "object" && error !== null && STOPPED in error) return {
+		retry: false,
+		unavailable: false
+	};
+	if (error instanceof RemoteConnectError) return {
+		retry: error.transient,
+		unavailable: !error.transient && error.scope !== "job"
+	};
+	const retry = isRetryableConnectError(error);
+	return {
+		retry,
+		unavailable: !retry
+	};
+}
+/** A provider's thrown value as a {@link RemoteConnectError}: transient unless it says `transient: false`. */
+function connectErrorOf(error) {
+	const flags = typeof error === "object" && error !== null ? error : {};
+	return new RemoteConnectError(`acquire failed: ${error instanceof Error ? error.message : String(error)}`, {
+		cause: error,
+		transient: flags.transient !== false,
+		scope: flags.scope === "job" ? "job" : "target",
+		lease: flags.lease
+	});
+}
+export { RemoteConnectError, classify, connectErrorOf, stoppedError };
+
+//# sourceMappingURL=remote-lease-error.mjs.map

package/dist/adapters/remote-lease-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-lease-error.mjs","names":[],"sources":["../../src/adapters/remote-lease-error.ts"],"sourcesContent":["/** How a connect failure is classified (ADR 0007, decision 4): retried or not, and what it does to the target. */\nimport { isRetryableConnectError } from \"../utils/connect-retry.ts\";\n\n/** What a connect failure means for the retry loop and for the target. */\nexport interface RemoteConnectErrorOptions {\n  /** `false` stops the retries and fails the job (default `true`: retried). */\n  transient?: boolean | undefined;\n  /**\n   * For `transient: false`: `target` (default) also marks the target unavailable until restart,\n   * `job` fails only this job and keeps the target offered (a per-shard server that is gone).\n   */\n  scope?: \"target\" | \"job\" | undefined;\n  /** A lease the failed `connect` already took, released as `failed`. */\n  lease?: unknown;\n  cause?: unknown;\n}\n\n/** An error a function `connect` throws to say how the runner should treat the failure. */\nexport class RemoteConnectError extends Error {\n  override readonly name = \"RemoteConnectError\";\n  readonly transient: boolean;\n  readonly scope: \"target\" | \"job\";\n  readonly lease: unknown;\n\n  constructor(message: string, options: RemoteConnectErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.transient = options.transient ?? true;\n    this.scope = options.scope ?? \"target\";\n    this.lease = options.lease;\n  }\n}\n\n/** Marks the error of a `connect` abandoned because the run was cancelled or the process is shutting down. */\nconst STOPPED = Symbol(\"remote connect stopped\");\n\n/** The error of a `connect` that was cancelled or cut short by shutdown: never retried. */\nexport function stoppedError(): Error {\n  return Object.assign(new Error(\"cancelled while connecting\"), { [STOPPED]: true });\n}\n\n/** What a connect error means: whether to retry it, and whether it marks the target unavailable. */\nexport function classify(error: unknown): { retry: boolean; unavailable: boolean } {\n  if (typeof error === \"object\" && error !== null && STOPPED in error) {\n    return { retry: false, unavailable: false };\n  }\n  if (error instanceof RemoteConnectError) {\n    return { retry: error.transient, unavailable: !error.transient && error.scope !== \"job\" };\n  }\n  const retry = isRetryableConnectError(error);\n  return { retry, unavailable: !retry };\n}\n\n/** A provider's thrown value as a {@link RemoteConnectError}: transient unless it says `transient: false`. */\nexport function connectErrorOf(error: unknown): RemoteConnectError {\n  const flags = (typeof error === \"object\" && error !== null ? error : {}) as {\n    transient?: unknown;\n    scope?: unknown;\n    lease?: unknown;\n  };\n  return new RemoteConnectError(\n    `acquire failed: ${error instanceof Error ? error.message : String(error)}`,\n    {\n      cause: error,\n      transient: flags.transient !== false,\n      scope: flags.scope === \"job\" ? \"job\" : \"target\",\n      lease: flags.lease,\n    },\n  );\n}\n"],"mappings":";;;;;;;AAkBA,IAAa,qBAAb,cAAwC,MAAM;CAC5C,OAAyB;CACzB;CACA;CACA;CAEA,YAAY,SAAiB,UAAqC,CAAC,GAAG;EACpE,MAAM,SAAS,QAAQ,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,OAAO,QAAQ,MAAM,CAAC;EACjF,KAAK,YAAY,QAAQ,aAAa;EACtC,KAAK,QAAQ,QAAQ,SAAS;EAC9B,KAAK,QAAQ,QAAQ;CACvB;AACF;;AAGA,MAAM,UAAU,OAAO,wBAAwB;;AAG/C,SAAgB,eAAsB;CACpC,OAAO,OAAO,uBAAO,IAAI,MAAM,4BAA4B,GAAG,GAAG,UAAU,KAAK,CAAC;AACnF;;AAGA,SAAgB,SAAS,OAA0D;CACjF,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,WAAW,OAC5D,OAAO;EAAE,OAAO;EAAO,aAAa;CAAM;CAE5C,IAAI,iBAAiB,oBACnB,OAAO;EAAE,OAAO,MAAM;EAAW,aAAa,CAAC,MAAM,aAAa,MAAM,UAAU;CAAM;CAE1F,MAAM,QAAQ,wBAAwB,KAAK;CAC3C,OAAO;EAAE;EAAO,aAAa,CAAC;CAAM;AACtC;;AAGA,SAAgB,eAAe,OAAoC;CACjE,MAAM,QAAS,OAAO,UAAU,YAAY,UAAU,OAAO,QAAQ,CAAC;CAKtE,OAAO,IAAI,mBACT,mBAAmB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,KACxE;EACE,OAAO;EACP,WAAW,MAAM,cAAc;EAC/B,OAAO,MAAM,UAAU,QAAQ,QAAQ;EACvC,OAAO,MAAM;CACf,CACF;AACF"}

package/dist/adapters/remote-lease-held.d.mts

@@ -0,0 +1,15 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { RemoteConnection, RemoteLeaseOutcome } from "./remote-browser.mjs";
+import "../logger.mjs";
+/** A connection held until its render ends. */
+interface HeldConnection {
+  /** The connection to open (with its lease, for scrubbing): the function's result, or the fixed object. */
+  readonly connection: RemoteConnection & {
+    lease?: unknown;
+  };
+  /** Release the lease with how the render ended; later calls do nothing (the first outcome wins). */
+  end(outcome: RemoteLeaseOutcome, error?: unknown): Promise<void>;
+}
+export { HeldConnection };
+//# sourceMappingURL=remote-lease-held.d.mts.map

package/dist/adapters/remote-lease-held.mjs

@@ -0,0 +1,86 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/adapters/remote-lease-held.ts
+const held = /* @__PURE__ */ new Set();
+const warnedNoLease = /* @__PURE__ */ new Set();
+/** Release every lease still held, as `cancelled`. */
+async function releaseAllHeld() {
+	await Promise.all([...held].map(async (lease) => {
+		await lease.end("cancelled");
+	}));
+}
+/** `pending`, or the error `onTimeout` makes after `ms`. */
+async function withDeadline(pending, ms, onTimeout) {
+	let timer;
+	const deadline = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			reject(onTimeout());
+		}, ms);
+	});
+	try {
+		return await Promise.race([pending, deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function noLease(connection) {
+	return {
+		connection,
+		end: async () => {
+			await Promise.resolve();
+		}
+	};
+}
+/**
+* Hold `lease` for `connection`: `end` calls the service's `release` once, bounded by
+* `timeouts.releaseMs`, and a failing or hanging release is logged (class only) and never thrown.
+* No lease means nothing to release: a warning says so once per target when `release` is set.
+*/
+function holdLease(entry, lease, connection, logger) {
+	const { release, timeouts } = entry.remote;
+	if (lease === void 0) {
+		if (release !== void 0 && !warnedNoLease.has(entry.target)) {
+			warnedNoLease.add(entry.target);
+			logger?.warn({ target: entry.target }, "remote release is set but connect returned no lease, so release is skipped");
+		}
+		return noLease(connection);
+	}
+	let ended = false;
+	const connectionHeld = {
+		connection: {
+			...connection,
+			lease
+		},
+		end: async (outcome, error) => {
+			if (ended) return;
+			ended = true;
+			held.delete(connectionHeld);
+			await runRelease(entry, async () => {
+				await release?.(lease, {
+					outcome,
+					error
+				});
+			}, timeouts.releaseMs, {
+				logger,
+				outcome
+			});
+		}
+	};
+	held.add(connectionHeld);
+	return connectionHeld;
+}
+async function runRelease(entry, call, timeoutMs, log) {
+	try {
+		await withDeadline(call(), timeoutMs, () => Object.assign(/* @__PURE__ */ new Error(`release timed out after ${timeoutMs} ms`), { name: "ReleaseTimeout" }));
+	} catch (error) {
+		log.logger?.warn({
+			target: entry.target,
+			outcome: log.outcome,
+			err: error instanceof Error ? error.name : "Error"
+		}, "remote browser release failed");
+	}
+}
+export { holdLease, noLease, releaseAllHeld, withDeadline };
+
+//# sourceMappingURL=remote-lease-held.mjs.map

package/dist/adapters/remote-lease-held.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-lease-held.mjs","names":[],"sources":["../../src/adapters/remote-lease-held.ts"],"sourcesContent":["/** A connection held until its render ends, and the one release it owes (ADR 0007, decision 4). */\nimport type { Logger } from \"../logger.ts\";\nimport type { RemoteConnection, RemoteLeaseOutcome, RemoteTarget } from \"./remote-browser.ts\";\n\n/** A connection held until its render ends. */\nexport interface HeldConnection {\n  /** The connection to open (with its lease, for scrubbing): the function's result, or the fixed object. */\n  readonly connection: RemoteConnection & { lease?: unknown };\n  /** Release the lease with how the render ended; later calls do nothing (the first outcome wins). */\n  end(outcome: RemoteLeaseOutcome, error?: unknown): Promise<void>;\n}\n\nconst held = new Set<HeldConnection>();\nconst warnedNoLease = new Set<string>();\n\n/** Release every lease still held, as `cancelled`. */\nexport async function releaseAllHeld(): Promise<void> {\n  await Promise.all(\n    [...held].map(async (lease) => {\n      await lease.end(\"cancelled\");\n    }),\n  );\n}\n\n/** `pending`, or the error `onTimeout` makes after `ms`. */\nexport async function withDeadline<T>(\n  pending: Promise<T>,\n  ms: number,\n  onTimeout: () => Error,\n): Promise<T> {\n  let timer: NodeJS.Timeout | undefined;\n  const deadline = new Promise<never>((_, reject) => {\n    timer = setTimeout(() => {\n      reject(onTimeout());\n    }, ms);\n  });\n  try {\n    return await Promise.race([pending, deadline]);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\nexport function noLease(connection: RemoteConnection): HeldConnection {\n  return {\n    connection,\n    end: async () => {\n      await Promise.resolve();\n    },\n  };\n}\n\n/**\n * Hold `lease` for `connection`: `end` calls the service's `release` once, bounded by\n * `timeouts.releaseMs`, and a failing or hanging release is logged (class only) and never thrown.\n * No lease means nothing to release: a warning says so once per target when `release` is set.\n */\nexport function holdLease(\n  entry: RemoteTarget,\n  lease: unknown,\n  connection: RemoteConnection,\n  logger?: Logger,\n): HeldConnection {\n  const { release, timeouts } = entry.remote;\n  if (lease === undefined) {\n    if (release !== undefined && !warnedNoLease.has(entry.target)) {\n      warnedNoLease.add(entry.target);\n      logger?.warn(\n        { target: entry.target },\n        \"remote release is set but connect returned no lease, so release is skipped\",\n      );\n    }\n    return noLease(connection);\n  }\n  let ended = false;\n  const connectionHeld: HeldConnection = {\n    connection: { ...connection, lease },\n    end: async (outcome, error) => {\n      if (ended) {\n        return;\n      }\n      ended = true;\n      held.delete(connectionHeld);\n      await runRelease(\n        entry,\n        async () => {\n          await release?.(lease as never, { outcome, error });\n        },\n        timeouts.releaseMs,\n        { logger, outcome },\n      );\n    },\n  };\n  held.add(connectionHeld);\n  return connectionHeld;\n}\n\nasync function runRelease(\n  entry: RemoteTarget,\n  call: () => Promise<void>,\n  timeoutMs: number,\n  log: { logger: Logger | undefined; outcome: RemoteLeaseOutcome },\n): Promise<void> {\n  try {\n    await withDeadline(call(), timeoutMs, () =>\n      Object.assign(new Error(`release timed out after ${timeoutMs} ms`), {\n        name: \"ReleaseTimeout\",\n      }),\n    );\n  } catch (error) {\n    // Never the lease or the error text: either can carry a credential.\n    log.logger?.warn(\n      {\n        target: entry.target,\n        outcome: log.outcome,\n        err: error instanceof Error ? error.name : \"Error\",\n      },\n      \"remote browser release failed\",\n    );\n  }\n}\n"],"mappings":";;;;AAYA,MAAM,uBAAO,IAAI,IAAoB;AACrC,MAAM,gCAAgB,IAAI,IAAY;;AAGtC,eAAsB,iBAAgC;CACpD,MAAM,QAAQ,IACZ,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,OAAO,UAAU;EAC7B,MAAM,MAAM,IAAI,WAAW;CAC7B,CAAC,CACH;AACF;;AAGA,eAAsB,aACpB,SACA,IACA,WACY;CACZ,IAAI;CACJ,MAAM,WAAW,IAAI,SAAgB,GAAG,WAAW;EACjD,QAAQ,iBAAiB;GACvB,OAAO,UAAU,CAAC;EACpB,GAAG,EAAE;CACP,CAAC;CACD,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,QAAQ,CAAC;CAC/C,UAAU;EACR,aAAa,KAAK;CACpB;AACF;AAEA,SAAgB,QAAQ,YAA8C;CACpE,OAAO;EACL;EACA,KAAK,YAAY;GACf,MAAM,QAAQ,QAAQ;EACxB;CACF;AACF;;;;;;AAOA,SAAgB,UACd,OACA,OACA,YACA,QACgB;CAChB,MAAM,EAAE,SAAS,aAAa,MAAM;CACpC,IAAI,UAAU,KAAA,GAAW;EACvB,IAAI,YAAY,KAAA,KAAa,CAAC,cAAc,IAAI,MAAM,MAAM,GAAG;GAC7D,cAAc,IAAI,MAAM,MAAM;GAC9B,QAAQ,KACN,EAAE,QAAQ,MAAM,OAAO,GACvB,4EACF;EACF;EACA,OAAO,QAAQ,UAAU;CAC3B;CACA,IAAI,QAAQ;CACZ,MAAM,iBAAiC;EACrC,YAAY;GAAE,GAAG;GAAY;EAAM;EACnC,KAAK,OAAO,SAAS,UAAU;GAC7B,IAAI,OACF;GAEF,QAAQ;GACR,KAAK,OAAO,cAAc;GAC1B,MAAM,WACJ,OACA,YAAY;IACV,MAAM,UAAU,OAAgB;KAAE;KAAS;IAAM,CAAC;GACpD,GACA,SAAS,WACT;IAAE;IAAQ;GAAQ,CACpB;EACF;CACF;CACA,KAAK,IAAI,cAAc;CACvB,OAAO;AACT;AAEA,eAAe,WACb,OACA,MACA,WACA,KACe;CACf,IAAI;EACF,MAAM,aAAa,KAAK,GAAG,iBACzB,OAAO,uBAAO,IAAI,MAAM,2BAA2B,UAAU,IAAI,GAAG,EAClE,MAAM,iBACR,CAAC,CACH;CACF,SAAS,OAAO;EAEd,IAAI,QAAQ,KACV;GACE,QAAQ,MAAM;GACd,SAAS,IAAI;GACb,KAAK,iBAAiB,QAAQ,MAAM,OAAO;EAC7C,GACA,+BACF;CACF;AACF"}

package/dist/adapters/remote-lease-shutdown.d.mts

@@ -0,0 +1,12 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/**
+ * Stop everything remote this process holds, for a runner shutting down: abort pending `connect`
+ * calls, release every lease still held as `cancelled`, then run the shutdown hooks (pools close
+ * their resources). A server is not left running by a process that is gone.
+ */
+declare function shutdownRemote(): Promise<void>;
+/** Run `hook` on shutdown; returns the function that unregisters it. */
+declare function onRemoteShutdown(hook: () => Promise<void>): () => void;
+export { onRemoteShutdown, shutdownRemote };
+//# sourceMappingURL=remote-lease-shutdown.d.mts.map

package/dist/adapters/remote-lease-shutdown.mjs

@@ -0,0 +1,32 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { stopAllAttempts } from "./remote-lease-attempt.mjs";
+import { releaseAllHeld } from "./remote-lease-held.mjs";
+import { resetAllLimiters } from "./remote-limiter.mjs";
+// src/adapters/remote-lease-shutdown.ts
+/** Stopping everything remote the process holds, for a runner shutting down (ADR 0007, decision 4). */
+const shutdownHooks = /* @__PURE__ */ new Set();
+/**
+* Stop everything remote this process holds, for a runner shutting down: abort pending `connect`
+* calls, release every lease still held as `cancelled`, then run the shutdown hooks (pools close
+* their resources). A server is not left running by a process that is gone.
+*/
+async function shutdownRemote() {
+	stopAllAttempts();
+	resetAllLimiters();
+	await releaseAllHeld();
+	await Promise.all([...shutdownHooks].map(async (hook) => {
+		await hook();
+	}));
+}
+/** Run `hook` on shutdown; returns the function that unregisters it. */
+function onRemoteShutdown(hook) {
+	shutdownHooks.add(hook);
+	return () => {
+		shutdownHooks.delete(hook);
+	};
+}
+export { onRemoteShutdown, shutdownRemote };
+
+//# sourceMappingURL=remote-lease-shutdown.mjs.map

package/dist/adapters/remote-lease-shutdown.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-lease-shutdown.mjs","names":[],"sources":["../../src/adapters/remote-lease-shutdown.ts"],"sourcesContent":["import { stopAllAttempts } from \"./remote-lease-attempt.ts\";\n/** Stopping everything remote the process holds, for a runner shutting down (ADR 0007, decision 4). */\nimport { releaseAllHeld } from \"./remote-lease-held.ts\";\nimport { resetAllLimiters } from \"./remote-limiter.ts\";\n\nconst shutdownHooks = new Set<() => Promise<void>>();\n\n/**\n * Stop everything remote this process holds, for a runner shutting down: abort pending `connect`\n * calls, release every lease still held as `cancelled`, then run the shutdown hooks (pools close\n * their resources). A server is not left running by a process that is gone.\n */\nexport async function shutdownRemote(): Promise<void> {\n  stopAllAttempts();\n  resetAllLimiters();\n  await releaseAllHeld();\n  await Promise.all(\n    [...shutdownHooks].map(async (hook) => {\n      await hook();\n    }),\n  );\n}\n\n/** Run `hook` on shutdown; returns the function that unregisters it. */\nexport function onRemoteShutdown(hook: () => Promise<void>): () => void {\n  shutdownHooks.add(hook);\n  return () => {\n    shutdownHooks.delete(hook);\n  };\n}\n"],"mappings":";;;;;;;;AAKA,MAAM,gCAAgB,IAAI,IAAyB;;;;;;AAOnD,eAAsB,iBAAgC;CACpD,gBAAgB;CAChB,iBAAiB;CACjB,MAAM,eAAe;CACrB,MAAM,QAAQ,IACZ,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,OAAO,SAAS;EACrC,MAAM,KAAK;CACb,CAAC,CACH;AACF;;AAGA,SAAgB,iBAAiB,MAAuC;CACtE,cAAc,IAAI,IAAI;CACtB,aAAa;EACX,cAAc,OAAO,IAAI;CAC3B;AACF"}

package/dist/adapters/remote-lease.d.mts

@@ -0,0 +1,39 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { RemoteConnectContext, RemoteConnection, RemoteTarget } from "./remote-browser.mjs";
+import { Logger } from "../logger.mjs";
+import { HeldConnection } from "./remote-lease-held.mjs";
+import { RemoteConnectError, RemoteConnectErrorOptions } from "./remote-lease-error.mjs";
+import { onRemoteShutdown, shutdownRemote } from "./remote-lease-shutdown.mjs";
+/** Which run a connection is for. */
+interface ConnectLeasedContext {
+  buildId: string;
+  runId: string;
+  shardIndex?: number | undefined;
+  purpose: RemoteConnectContext["purpose"];
+  /** Aborts a pending `connect` when the run is cancelled. */
+  signal?: AbortSignal | undefined;
+}
+/** Options of {@link connectLeased}. */
+interface ConnectLeasedOptions<T> {
+  logger?: Logger | undefined;
+  /** The handshake over one connection; its failures are retried when connection-level. */
+  open: (connection: RemoteConnection) => Promise<T>;
+  /** One line saying what failed, with the connection's credentials removed. */
+  reasonOf: (error: unknown, connection: RemoteConnection & {
+    lease?: unknown;
+  }) => string;
+}
+/**
+ * Connect (calling `connect` when it is a function) and open the connection, as one retried
+ * attempt: a failed handshake releases its lease as `failed` before the next attempt connects
+ * again, so at most one lease is held per connection. On success the caller owns the returned
+ * lease and must call {@link HeldConnection.end}; on failure nothing is held and a
+ * {@link TargetLaunchError} is thrown.
+ */
+declare function connectLeased<T>(entry: RemoteTarget, context: ConnectLeasedContext, options: ConnectLeasedOptions<T>): Promise<{
+  value: T;
+  lease: HeldConnection;
+}>;
+export { ConnectLeasedContext, ConnectLeasedOptions, type HeldConnection, RemoteConnectError, type RemoteConnectErrorOptions, connectLeased, onRemoteShutdown, shutdownRemote };
+//# sourceMappingURL=remote-lease.d.mts.map