@storyshelf/core 0.6.2 → 0.8.0

package/dist/adapters/remote-lease.mjs

@@ -0,0 +1,175 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { TargetLaunchError } from "./capture-target.mjs";
+import { hasSchemeFor, schemesOf } from "./remote-browser.mjs";
+import { retryConnect } from "../utils/connect-retry.mjs";
+import { endAttempt, startAttempt } from "./remote-lease-attempt.mjs";
+import { RemoteConnectError, classify, connectErrorOf, stoppedError } from "./remote-lease-error.mjs";
+import { holdLease, noLease, withDeadline } from "./remote-lease-held.mjs";
+import { shutdownEpoch, takeSlot } from "./remote-limiter.mjs";
+import { onRemoteShutdown, shutdownRemote } from "./remote-lease-shutdown.mjs";
+// src/adapters/remote-lease.ts
+/**
+* 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.
+*/
+async function connectLeased(entry, context, options) {
+	const { remote } = entry;
+	let current = typeof remote.connect === "function" ? { endpoint: "" } : remote.connect;
+	let attemptNo = 0;
+	try {
+		return await retryConnect(async () => {
+			attemptNo += 1;
+			const lease = await acquire(entry, context, attemptNo, options.logger);
+			current = lease.connection;
+			try {
+				return {
+					value: await options.open(lease.connection),
+					lease
+				};
+			} catch (error) {
+				await lease.end("failed", error);
+				throw error;
+			}
+		}, {
+			retries: remote.retry.attempts,
+			backoffMs: remote.retry.backoffMs,
+			retryable: (error) => classify(error).retry,
+			onRetry: (error, retry, delayMs) => {
+				options.logger?.warn({
+					target: entry.target,
+					retry,
+					delayMs,
+					reason: options.reasonOf(error, current)
+				}, "remote browser connect failed, retrying");
+			}
+		});
+	} catch (error) {
+		const reason = options.reasonOf(error, current);
+		throw new TargetLaunchError(entry.target, reason, {
+			cause: Object.assign(new Error(reason), { name: error instanceof Error ? error.name : "Error" }),
+			transient: !classify(error).unavailable
+		});
+	}
+}
+/**
+* One connection, counted under the service's `maxConnections` when it has one: the slot is taken
+* (waiting, cancellably) before `connect` runs and given back when the lease ends, or at once when
+* the connection never materialises. Without a cap this is just {@link open}.
+*/
+async function acquire(entry, context, attemptNo, logger) {
+	const epoch = shutdownEpoch();
+	const taking = takeSlot(entry, context.signal, logger);
+	const slot = taking === void 0 ? void 0 : await taking;
+	stopIfShutDown(slot, epoch);
+	try {
+		const held = await open(entry, context, attemptNo, logger);
+		return slot === void 0 ? held : withSlot(held, slot);
+	} catch (error) {
+		slot?.release();
+		throw error;
+	}
+}
+/**
+* A slot granted across a shutdown must not open a connection: the shutdown has already stopped the
+* attempts and collected the leases, so nothing would release it. The slot is given back and the
+* connection stops. Called right before `open`, with nothing awaited in between, so a shutdown cannot
+* slip into the gap (`open` registers its attempt synchronously).
+*/
+function stopIfShutDown(slot, epoch) {
+	if (slot !== void 0 && shutdownEpoch() !== epoch) {
+		slot.release();
+		throw stoppedError();
+	}
+}
+/** `held` that gives its slot back, once, after the lease is released. */
+function withSlot(held, slot) {
+	let ending;
+	return {
+		connection: held.connection,
+		end: async (outcome, error) => {
+			ending ??= endAndFree(held, slot, outcome, error);
+			await ending;
+		}
+	};
+}
+async function endAndFree(held, slot, outcome, error) {
+	try {
+		await held.end(outcome, error);
+	} finally {
+		slot.release();
+	}
+}
+async function open(entry, context, attemptNo, logger) {
+	const { remote } = entry;
+	if (typeof remote.connect !== "function") return noLease(remote.connect);
+	const attempt = startAttempt(context.signal);
+	try {
+		return await adopt(entry, await called(entry, context, attemptNo, attempt, logger), logger);
+	} finally {
+		endAttempt(attempt);
+	}
+}
+/** The function `connect` under its deadline; a lease that arrives after it is released at once. */
+async function called(entry, context, attemptNo, attempt, logger) {
+	if (attempt.stopped) throw stoppedError();
+	const pending = invoke(entry.remote.connect, {
+		engine: entry.engine,
+		buildId: context.buildId,
+		runId: context.runId,
+		shardIndex: context.shardIndex,
+		purpose: context.purpose,
+		attempt: attemptNo,
+		signal: attempt.controller.signal
+	});
+	const { acquireMs } = entry.remote.timeouts;
+	try {
+		return await withDeadline(pending, acquireMs, () => {
+			attempt.controller.abort();
+			releaseLate(entry, pending, logger).catch(() => {});
+			return new RemoteConnectError(`acquire timed out after ${acquireMs} ms`);
+		});
+	} catch (error) {
+		throw await failedConnect(entry, error, attempt, logger);
+	}
+}
+/** Call a sync or async `connect`, so a sync throw is a rejection like any other. */
+async function invoke(connect, context) {
+	return await connect(context);
+}
+/** A function `connect`'s failure as the error to throw, releasing a lease it carried. */
+async function failedConnect(entry, error, attempt, logger) {
+	const converted = error instanceof RemoteConnectError ? error : connectErrorOf(error);
+	if (converted.lease !== void 0) await holdLease(entry, converted.lease, { endpoint: "" }, logger).end("failed", converted);
+	return attempt.stopped ? stoppedError() : converted;
+}
+/** Check what a function `connect` returned against what the service declared, then hold it. */
+async function adopt(entry, result, logger) {
+	const problem = problemWith(entry, result);
+	if (problem === null) return holdLease(entry, result.lease, result, logger);
+	const lease = result?.lease;
+	if (lease !== void 0) await holdLease(entry, lease, { endpoint: "" }, logger).end("failed");
+	throw new RemoteConnectError(problem, {
+		transient: false,
+		scope: "job"
+	});
+}
+function problemWith(entry, result) {
+	if (typeof result !== "object" || result === null || typeof result.endpoint !== "string") return "connect must return an object with an endpoint";
+	const extra = Object.keys(result).filter((key) => key !== "endpoint" && key !== "headers" && key !== "lease");
+	if (extra.length > 0) return `connect returned ${extra.join(", ")}: protocol and reach are declared on remote(), not returned`;
+	const { protocol } = entry.remote;
+	return hasSchemeFor(protocol, result.endpoint) ? null : `connect returned an endpoint that is not a ${schemesOf(protocol)} URL`;
+}
+/** A connection that arrives after its deadline is released at once. */
+async function releaseLate(entry, pending, logger) {
+	const late = await pending.catch(() => null);
+	if (late?.lease !== void 0) await holdLease(entry, late.lease, { endpoint: "" }, logger).end("failed");
+}
+export { RemoteConnectError, connectLeased, onRemoteShutdown, shutdownRemote };
+
+//# sourceMappingURL=remote-lease.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-lease.mjs","names":[],"sources":["../../src/adapters/remote-lease.ts"],"sourcesContent":["/**\n * Connecting to a remote browser over a lease (ADR 0007, decision 4): a function `connect` is\n * called per connection, and `release` once the render that used it has ended. The runners own the\n * handshake itself; this owns the pairing, so a lease is released exactly once on every path\n * (finish, failure, cancel, shutdown) and never logged.\n */\nimport type { Logger } from \"../logger.ts\";\nimport { retryConnect } from \"../utils/connect-retry.ts\";\nimport { TargetLaunchError } from \"./capture-target.ts\";\nimport {\n  hasSchemeFor,\n  schemesOf,\n  type RemoteConnectContext,\n  type RemoteConnection,\n  type RemoteLeaseOutcome,\n  type RemoteLeasedConnection,\n  type RemoteTarget,\n} from \"./remote-browser.ts\";\nimport { endAttempt, startAttempt, type Attempt } from \"./remote-lease-attempt.ts\";\nimport {\n  RemoteConnectError,\n  classify,\n  connectErrorOf,\n  stoppedError,\n} from \"./remote-lease-error.ts\";\nimport { holdLease, noLease, withDeadline, type HeldConnection } from \"./remote-lease-held.ts\";\nimport { shutdownEpoch, takeSlot, type ConnectionSlot } from \"./remote-limiter.ts\";\n\nexport { RemoteConnectError, type RemoteConnectErrorOptions } from \"./remote-lease-error.ts\";\nexport type { HeldConnection } from \"./remote-lease-held.ts\";\nexport { onRemoteShutdown, shutdownRemote } from \"./remote-lease-shutdown.ts\";\n\n/** Which run a connection is for. */\nexport interface ConnectLeasedContext {\n  buildId: string;\n  runId: string;\n  shardIndex?: number | undefined;\n  purpose: RemoteConnectContext[\"purpose\"];\n  /** Aborts a pending `connect` when the run is cancelled. */\n  signal?: AbortSignal | undefined;\n}\n\n/** Options of {@link connectLeased}. */\nexport interface ConnectLeasedOptions<T> {\n  logger?: Logger | undefined;\n  /** The handshake over one connection; its failures are retried when connection-level. */\n  open: (connection: RemoteConnection) => Promise<T>;\n  /** One line saying what failed, with the connection's credentials removed. */\n  reasonOf: (error: unknown, connection: RemoteConnection & { lease?: unknown }) => string;\n}\n\ntype ConnectFn = (\n  context: RemoteConnectContext,\n) => RemoteLeasedConnection | Promise<RemoteLeasedConnection>;\n\n/**\n * Connect (calling `connect` when it is a function) and open the connection, as one retried\n * attempt: a failed handshake releases its lease as `failed` before the next attempt connects\n * again, so at most one lease is held per connection. On success the caller owns the returned\n * lease and must call {@link HeldConnection.end}; on failure nothing is held and a\n * {@link TargetLaunchError} is thrown.\n */\nexport async function connectLeased<T>(\n  entry: RemoteTarget,\n  context: ConnectLeasedContext,\n  options: ConnectLeasedOptions<T>,\n): Promise<{ value: T; lease: HeldConnection }> {\n  const { remote } = entry;\n  let current: RemoteConnection & { lease?: unknown } =\n    typeof remote.connect === \"function\" ? { endpoint: \"\" } : remote.connect;\n  let attemptNo = 0;\n  try {\n    return await retryConnect(\n      async () => {\n        attemptNo += 1;\n        const lease = await acquire(entry, context, attemptNo, options.logger);\n        current = lease.connection;\n        try {\n          return { value: await options.open(lease.connection), lease };\n        } catch (error) {\n          await lease.end(\"failed\", error);\n          throw error;\n        }\n      },\n      {\n        retries: remote.retry.attempts,\n        backoffMs: remote.retry.backoffMs,\n        retryable: (error) => classify(error).retry,\n        onRetry: (error, retry, delayMs) => {\n          options.logger?.warn(\n            { target: entry.target, retry, delayMs, reason: options.reasonOf(error, current) },\n            \"remote browser connect failed, retrying\",\n          );\n        },\n      },\n    );\n  } catch (error) {\n    const reason = options.reasonOf(error, current);\n    throw new TargetLaunchError(entry.target, reason, {\n      cause: Object.assign(new Error(reason), {\n        name: error instanceof Error ? error.name : \"Error\",\n      }),\n      transient: !classify(error).unavailable,\n    });\n  }\n}\n\n/**\n * One connection, counted under the service's `maxConnections` when it has one: the slot is taken\n * (waiting, cancellably) before `connect` runs and given back when the lease ends, or at once when\n * the connection never materialises. Without a cap this is just {@link open}.\n */\nasync function acquire(\n  entry: RemoteTarget,\n  context: ConnectLeasedContext,\n  attemptNo: number,\n  logger: Logger | undefined,\n): Promise<HeldConnection> {\n  // No `await` without a cap: an uncapped connection starts exactly as it did before.\n  const epoch = shutdownEpoch();\n  const taking = takeSlot(entry, context.signal, logger);\n  const slot = taking === undefined ? undefined : await taking;\n  stopIfShutDown(slot, epoch);\n  try {\n    const held = await open(entry, context, attemptNo, logger);\n    return slot === undefined ? held : withSlot(held, slot);\n  } catch (error) {\n    slot?.release();\n    throw error;\n  }\n}\n\n/**\n * A slot granted across a shutdown must not open a connection: the shutdown has already stopped the\n * attempts and collected the leases, so nothing would release it. The slot is given back and the\n * connection stops. Called right before `open`, with nothing awaited in between, so a shutdown cannot\n * slip into the gap (`open` registers its attempt synchronously).\n */\nfunction stopIfShutDown(slot: ConnectionSlot | undefined, epoch: number): void {\n  if (slot !== undefined && shutdownEpoch() !== epoch) {\n    slot.release();\n    throw stoppedError();\n  }\n}\n\n/** `held` that gives its slot back, once, after the lease is released. */\nfunction withSlot(held: HeldConnection, slot: ConnectionSlot): HeldConnection {\n  let ending: Promise<void> | undefined;\n  return {\n    connection: held.connection,\n    // Every caller gets the first call's promise: the inner `end` returns at once for a second call,\n    // which would free the slot while the first release is still running.\n    end: async (outcome, error) => {\n      ending ??= endAndFree(held, slot, outcome, error);\n      await ending;\n    },\n  };\n}\n\nasync function endAndFree(\n  held: HeldConnection,\n  slot: ConnectionSlot,\n  outcome: RemoteLeaseOutcome,\n  error: unknown,\n): Promise<void> {\n  try {\n    await held.end(outcome, error);\n  } finally {\n    slot.release();\n  }\n}\n\nasync function open(\n  entry: RemoteTarget,\n  context: ConnectLeasedContext,\n  attemptNo: number,\n  logger: Logger | undefined,\n): Promise<HeldConnection> {\n  const { remote } = entry;\n  if (typeof remote.connect !== \"function\") {\n    return noLease(remote.connect);\n  }\n  const attempt = startAttempt(context.signal);\n  try {\n    const result = await called(entry, context, attemptNo, attempt, logger);\n    return await adopt(entry, result, logger);\n  } finally {\n    endAttempt(attempt);\n  }\n}\n\n/** The function `connect` under its deadline; a lease that arrives after it is released at once. */\nasync function called(\n  entry: RemoteTarget,\n  context: ConnectLeasedContext,\n  attemptNo: number,\n  attempt: Attempt,\n  logger: Logger | undefined,\n): Promise<RemoteLeasedConnection> {\n  if (attempt.stopped) {\n    // Cancelled during a backoff: never call the provider with a signal that is already aborted.\n    throw stoppedError();\n  }\n  const pending = invoke(entry.remote.connect as ConnectFn, {\n    engine: entry.engine,\n    buildId: context.buildId,\n    runId: context.runId,\n    shardIndex: context.shardIndex,\n    purpose: context.purpose,\n    attempt: attemptNo,\n    signal: attempt.controller.signal,\n  });\n  const { acquireMs } = entry.remote.timeouts;\n  try {\n    return await withDeadline(pending, acquireMs, () => {\n      attempt.controller.abort();\n      releaseLate(entry, pending, logger).catch(() => {});\n      return new RemoteConnectError(`acquire timed out after ${acquireMs} ms`);\n    });\n  } catch (error) {\n    throw await failedConnect(entry, error, attempt, logger);\n  }\n}\n\n/** Call a sync or async `connect`, so a sync throw is a rejection like any other. */\nasync function invoke(\n  connect: ConnectFn,\n  context: RemoteConnectContext,\n): Promise<RemoteLeasedConnection> {\n  return await connect(context);\n}\n\n/** A function `connect`'s failure as the error to throw, releasing a lease it carried. */\nasync function failedConnect(\n  entry: RemoteTarget,\n  error: unknown,\n  attempt: Attempt,\n  logger: Logger | undefined,\n): Promise<Error> {\n  const converted = error instanceof RemoteConnectError ? error : connectErrorOf(error);\n  if (converted.lease !== undefined) {\n    await holdLease(entry, converted.lease, { endpoint: \"\" }, logger).end(\"failed\", converted);\n  }\n  return attempt.stopped ? stoppedError() : converted;\n}\n\n/** Check what a function `connect` returned against what the service declared, then hold it. */\nasync function adopt(\n  entry: RemoteTarget,\n  result: RemoteLeasedConnection,\n  logger: Logger | undefined,\n): Promise<HeldConnection> {\n  const problem = problemWith(entry, result);\n  if (problem === null) {\n    return holdLease(entry, result.lease, result, logger);\n  }\n  const lease = (result as { lease?: unknown } | null)?.lease;\n  if (lease !== undefined) {\n    await holdLease(entry, lease, { endpoint: \"\" }, logger).end(\"failed\");\n  }\n  throw new RemoteConnectError(problem, { transient: false, scope: \"job\" });\n}\n\nfunction problemWith(entry: RemoteTarget, result: RemoteLeasedConnection): string | null {\n  if (typeof result !== \"object\" || result === null || typeof result.endpoint !== \"string\") {\n    return \"connect must return an object with an endpoint\";\n  }\n  const extra = Object.keys(result).filter(\n    (key) => key !== \"endpoint\" && key !== \"headers\" && key !== \"lease\",\n  );\n  if (extra.length > 0) {\n    return `connect returned ${extra.join(\", \")}: protocol and reach are declared on remote(), not returned`;\n  }\n  const { protocol } = entry.remote;\n  return hasSchemeFor(protocol, result.endpoint)\n    ? null\n    : `connect returned an endpoint that is not a ${schemesOf(protocol)} URL`;\n}\n\n/** A connection that arrives after its deadline is released at once. */\nasync function releaseLate(\n  entry: RemoteTarget,\n  pending: Promise<RemoteLeasedConnection>,\n  logger: Logger | undefined,\n): Promise<void> {\n  const late = await pending.catch(() => null);\n  if (late?.lease !== undefined) {\n    await holdLease(entry, late.lease, { endpoint: \"\" }, logger).end(\"failed\");\n  }\n}\n"],"mappings":"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"}

package/dist/adapters/remote-limiter.mjs

@@ -0,0 +1,121 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { stoppedError } from "./remote-lease-error.mjs";
+// src/adapters/remote-limiter.ts
+/** A counting semaphore with a FIFO queue whose waiters can be cancelled. */
+var ConnectionLimiter = class {
+	limit;
+	#held = 0;
+	#queue = [];
+	constructor(limit) {
+		this.limit = limit;
+	}
+	/** Slots in use. */
+	get held() {
+		return this.#held;
+	}
+	/** Callers waiting for a slot. */
+	get waiting() {
+		return this.#queue.length;
+	}
+	/**
+	* Take a slot, waiting for one when all are in use. Rejects with the stopped error when `signal`
+	* aborts (or the process shuts down) while waiting, without having taken anything.
+	* `onLongWait` runs once if the wait outlasts `longWaitMs`.
+	*/
+	async acquire(signal, onLongWait, longWaitMs = 0) {
+		if (signal?.aborted === true) throw stoppedError();
+		if (this.#held < this.limit && this.#queue.length === 0) {
+			this.#held += 1;
+			return this.#slot();
+		}
+		return await new Promise((resolve, reject) => {
+			const timer = onLongWait === void 0 ? void 0 : setTimeout(onLongWait, longWaitMs).unref();
+			const settle = () => {
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+			};
+			const waiter = {
+				grant: () => {
+					settle();
+					this.#held += 1;
+					resolve(this.#slot());
+				},
+				stop: () => {
+					settle();
+					const index = this.#queue.indexOf(waiter);
+					if (index >= 0) this.#queue.splice(index, 1);
+					reject(stoppedError());
+				}
+			};
+			const onAbort = () => {
+				waiter.stop();
+			};
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.#queue.push(waiter);
+		});
+	}
+	/** Reject every waiter (shutdown). Slots already taken are released by their leases. */
+	stopWaiting() {
+		for (const waiter of this.#queue.splice(0)) waiter.stop();
+	}
+	#slot() {
+		let released = false;
+		return { release: () => {
+			if (released) return;
+			released = true;
+			this.#held -= 1;
+			this.#queue.shift()?.grant();
+		} };
+	}
+};
+const limiters = /* @__PURE__ */ new Map();
+let epoch = 0;
+/** The limiter of a service, created on first use; undefined when it has no `maxConnections`. */
+function limiterOf(remote) {
+	if (remote.maxConnections === void 0) return;
+	let limiter = limiters.get(remote);
+	if (limiter === void 0) {
+		limiter = new ConnectionLimiter(remote.maxConnections);
+		limiters.set(remote, limiter);
+	}
+	return limiter;
+}
+/**
+* Take the connection slot of `entry`'s service, or undefined when it has no cap. Not `async`: without
+* a cap the caller must not wait even one tick before it connects. A wait longer than
+* `timeouts.acquireMs` is logged once, with the target and the limit and nothing about the endpoint.
+*/
+function takeSlot(entry, signal, logger) {
+	const limiter = limiterOf(entry.remote);
+	if (limiter === void 0) return;
+	return limiter.acquire(signal, () => {
+		logger?.warn({
+			target: entry.target,
+			limit: limiter.limit,
+			waiting: limiter.waiting
+		}, "waiting for a remote browser connection slot");
+	}, entry.remote.timeouts.acquireMs);
+}
+/**
+* Shutdown: reject every caller still waiting for a slot and forget every limiter, so a service used
+* again starts with none held. A lease that is released later gives its slot back to the limiter it
+* took it from, which nothing uses any more.
+*/
+function resetAllLimiters() {
+	epoch += 1;
+	for (const limiter of limiters.values()) limiter.stopWaiting();
+	limiters.clear();
+}
+/**
+* Counts shutdowns. A caller that took a slot compares it with the value from before it waited: a
+* slot granted just before a shutdown resumes a tick later, after the attempts were stopped, and
+* must not open a connection nobody will release.
+*/
+function shutdownEpoch() {
+	return epoch;
+}
+export { ConnectionLimiter, limiterOf, resetAllLimiters, shutdownEpoch, takeSlot };
+
+//# sourceMappingURL=remote-limiter.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-limiter.mjs","names":[],"sources":["../../src/adapters/remote-limiter.ts"],"sourcesContent":["/**\n * The per-process cap on a remote service's connections (ADR 0007, decision 4): a separate limiter,\n * never the page gate. A slot is taken before `connect` is called and given back with the lease,\n * exactly once, so a connection counts from the moment it is requested until its render has ended.\n * Waiting for a slot ends on the run's cancel and at shutdown, and frees nothing it did not take.\n */\nimport type { Logger } from \"../logger.ts\";\nimport type { RemoteBrowser, RemoteTarget } from \"./remote-browser.ts\";\nimport { stoppedError } from \"./remote-lease-error.ts\";\n\n/** One connection's place under the cap; `release` is safe to call more than once. */\nexport interface ConnectionSlot {\n  release(): void;\n}\n\ninterface Waiter {\n  grant(): void;\n  stop(): void;\n}\n\n/** A counting semaphore with a FIFO queue whose waiters can be cancelled. */\nexport class ConnectionLimiter {\n  readonly limit: number;\n  #held = 0;\n  readonly #queue: Waiter[] = [];\n\n  constructor(limit: number) {\n    this.limit = limit;\n  }\n\n  /** Slots in use. */\n  get held(): number {\n    return this.#held;\n  }\n\n  /** Callers waiting for a slot. */\n  get waiting(): number {\n    return this.#queue.length;\n  }\n\n  /**\n   * Take a slot, waiting for one when all are in use. Rejects with the stopped error when `signal`\n   * aborts (or the process shuts down) while waiting, without having taken anything.\n   * `onLongWait` runs once if the wait outlasts `longWaitMs`.\n   */\n  async acquire(\n    signal?: AbortSignal,\n    onLongWait?: () => void,\n    longWaitMs = 0,\n  ): Promise<ConnectionSlot> {\n    if (signal?.aborted === true) {\n      throw stoppedError();\n    }\n    if (this.#held < this.limit && this.#queue.length === 0) {\n      this.#held += 1;\n      return this.#slot();\n    }\n    return await new Promise<ConnectionSlot>((resolve, reject) => {\n      const timer =\n        onLongWait === undefined ? undefined : setTimeout(onLongWait, longWaitMs).unref();\n      const settle = (): void => {\n        clearTimeout(timer);\n        signal?.removeEventListener(\"abort\", onAbort);\n      };\n      const waiter: Waiter = {\n        grant: () => {\n          settle();\n          this.#held += 1;\n          resolve(this.#slot());\n        },\n        stop: () => {\n          settle();\n          const index = this.#queue.indexOf(waiter);\n          if (index >= 0) {\n            this.#queue.splice(index, 1);\n          }\n          reject(stoppedError());\n        },\n      };\n      const onAbort = (): void => {\n        waiter.stop();\n      };\n      signal?.addEventListener(\"abort\", onAbort, { once: true });\n      this.#queue.push(waiter);\n    });\n  }\n\n  /** Reject every waiter (shutdown). Slots already taken are released by their leases. */\n  stopWaiting(): void {\n    for (const waiter of this.#queue.splice(0)) {\n      waiter.stop();\n    }\n  }\n\n  #slot(): ConnectionSlot {\n    let released = false;\n    return {\n      release: () => {\n        if (released) {\n          return;\n        }\n        released = true;\n        this.#held -= 1;\n        this.#queue.shift()?.grant();\n      },\n    };\n  }\n}\n\nconst limiters = new Map<RemoteBrowser, ConnectionLimiter>();\nlet epoch = 0;\n\n/** The limiter of a service, created on first use; undefined when it has no `maxConnections`. */\nexport function limiterOf(remote: RemoteBrowser): ConnectionLimiter | undefined {\n  if (remote.maxConnections === undefined) {\n    return undefined;\n  }\n  let limiter = limiters.get(remote);\n  if (limiter === undefined) {\n    limiter = new ConnectionLimiter(remote.maxConnections);\n    limiters.set(remote, limiter);\n  }\n  return limiter;\n}\n\n/**\n * Take the connection slot of `entry`'s service, or undefined when it has no cap. Not `async`: without\n * a cap the caller must not wait even one tick before it connects. A wait longer than\n * `timeouts.acquireMs` is logged once, with the target and the limit and nothing about the endpoint.\n */\nexport function takeSlot(\n  entry: RemoteTarget,\n  signal: AbortSignal | undefined,\n  logger: Logger | undefined,\n): Promise<ConnectionSlot> | undefined {\n  const limiter = limiterOf(entry.remote);\n  if (limiter === undefined) {\n    return undefined;\n  }\n  return limiter.acquire(\n    signal,\n    () => {\n      logger?.warn(\n        { target: entry.target, limit: limiter.limit, waiting: limiter.waiting },\n        \"waiting for a remote browser connection slot\",\n      );\n    },\n    entry.remote.timeouts.acquireMs,\n  );\n}\n\n/**\n * Shutdown: reject every caller still waiting for a slot and forget every limiter, so a service used\n * again starts with none held. A lease that is released later gives its slot back to the limiter it\n * took it from, which nothing uses any more.\n */\nexport function resetAllLimiters(): void {\n  epoch += 1;\n  for (const limiter of limiters.values()) {\n    limiter.stopWaiting();\n  }\n  limiters.clear();\n}\n\n/**\n * Counts shutdowns. A caller that took a slot compares it with the value from before it waited: a\n * slot granted just before a shutdown resumes a tick later, after the attempts were stopped, and\n * must not open a connection nobody will release.\n */\nexport function shutdownEpoch(): number {\n  return epoch;\n}\n"],"mappings":";;;;;;AAqBA,IAAa,oBAAb,MAA+B;CAC7B;CACA,QAAQ;CACR,SAA4B,CAAC;CAE7B,YAAY,OAAe;EACzB,KAAK,QAAQ;CACf;;CAGA,IAAI,OAAe;EACjB,OAAO,KAAK;CACd;;CAGA,IAAI,UAAkB;EACpB,OAAO,KAAK,OAAO;CACrB;;;;;;CAOA,MAAM,QACJ,QACA,YACA,aAAa,GACY;EACzB,IAAI,QAAQ,YAAY,MACtB,MAAM,aAAa;EAErB,IAAI,KAAK,QAAQ,KAAK,SAAS,KAAK,OAAO,WAAW,GAAG;GACvD,KAAK,SAAS;GACd,OAAO,KAAK,MAAM;EACpB;EACA,OAAO,MAAM,IAAI,SAAyB,SAAS,WAAW;GAC5D,MAAM,QACJ,eAAe,KAAA,IAAY,KAAA,IAAY,WAAW,YAAY,UAAU,CAAC,CAAC,MAAM;GAClF,MAAM,eAAqB;IACzB,aAAa,KAAK;IAClB,QAAQ,oBAAoB,SAAS,OAAO;GAC9C;GACA,MAAM,SAAiB;IACrB,aAAa;KACX,OAAO;KACP,KAAK,SAAS;KACd,QAAQ,KAAK,MAAM,CAAC;IACtB;IACA,YAAY;KACV,OAAO;KACP,MAAM,QAAQ,KAAK,OAAO,QAAQ,MAAM;KACxC,IAAI,SAAS,GACX,KAAK,OAAO,OAAO,OAAO,CAAC;KAE7B,OAAO,aAAa,CAAC;IACvB;GACF;GACA,MAAM,gBAAsB;IAC1B,OAAO,KAAK;GACd;GACA,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;GACzD,KAAK,OAAO,KAAK,MAAM;EACzB,CAAC;CACH;;CAGA,cAAoB;EAClB,KAAK,MAAM,UAAU,KAAK,OAAO,OAAO,CAAC,GACvC,OAAO,KAAK;CAEhB;CAEA,QAAwB;EACtB,IAAI,WAAW;EACf,OAAO,EACL,eAAe;GACb,IAAI,UACF;GAEF,WAAW;GACX,KAAK,SAAS;GACd,KAAK,OAAO,MAAM,CAAC,EAAE,MAAM;EAC7B,EACF;CACF;AACF;AAEA,MAAM,2BAAW,IAAI,IAAsC;AAC3D,IAAI,QAAQ;;AAGZ,SAAgB,UAAU,QAAsD;CAC9E,IAAI,OAAO,mBAAmB,KAAA,GAC5B;CAEF,IAAI,UAAU,SAAS,IAAI,MAAM;CACjC,IAAI,YAAY,KAAA,GAAW;EACzB,UAAU,IAAI,kBAAkB,OAAO,cAAc;EACrD,SAAS,IAAI,QAAQ,OAAO;CAC9B;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,SACd,OACA,QACA,QACqC;CACrC,MAAM,UAAU,UAAU,MAAM,MAAM;CACtC,IAAI,YAAY,KAAA,GACd;CAEF,OAAO,QAAQ,QACb,cACM;EACJ,QAAQ,KACN;GAAE,QAAQ,MAAM;GAAQ,OAAO,QAAQ;GAAO,SAAS,QAAQ;EAAQ,GACvE,8CACF;CACF,GACA,MAAM,OAAO,SAAS,SACxB;AACF;;;;;;AAOA,SAAgB,mBAAyB;CACvC,SAAS;CACT,KAAK,MAAM,WAAW,SAAS,OAAO,GACpC,QAAQ,YAAY;CAEtB,SAAS,MAAM;AACjB;;;;;;AAOA,SAAgB,gBAAwB;CACtC,OAAO;AACT"}

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

@@ -0,0 +1,56 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { RemoteConnectContext, RemoteConnection, RemoteLeasedConnection, RemoteReleaseInfo } from "./remote-browser.mjs";
+import { Logger } from "../logger.mjs";
+/** Options of {@link refCounted}. */
+interface RefCountedOptions<TResource> {
+  /**
+   * Start the resource (wake the computer) and return what connections need of it. Called by the
+   * first connection; concurrent first connections share the call. Must be idempotent: it runs
+   * again after a failed `close`, and may overlap a `close` that timed out. `signal` aborts when
+   * every waiting connection was cancelled, and at shutdown: clean up after yourself when it does,
+   * or throw an error with a `resource` property so the pool closes it.
+   */
+  open: (context: RemoteConnectContext, signal: AbortSignal) => Promise<TResource>;
+  /** Stop the resource (suspend the computer). */
+  close: (resource: TResource) => Promise<void> | void;
+  /**
+   * How long the resource stays open with no connection, in ms. Required: set it longer than the
+   * gap between a build's passes (the extract and tests pre-passes and its shards connect close
+   * together), for example 120 000.
+   */
+  idleMs: number;
+  /** How long `close` may take in ms before it counts as failed (default 30 000). */
+  closeTimeoutMs?: number | undefined;
+  /** Where close failures go (error class only, never the message). */
+  logger?: Logger | undefined;
+  /**
+   * Runs `run` after `ms` and returns what cancels it (default: an unref'd `setTimeout`). A seam
+   * for tests to drive the idle timer without real time.
+   */
+  schedule?: ((run: () => void, ms: number) => () => void) | undefined;
+}
+/** What the pool hands to `release`: an opaque token for one connection. */
+interface PoolLease {
+  readonly pool: "refCounted";
+}
+/** A reference-counted resource, wired into a service's `connect` and `release`. */
+interface RefCounted<TResource> {
+  /** Build the service's `connect`: `build` gets the shared resource and returns the connection. */
+  connect(build: (resource: TResource, context: RemoteConnectContext) => RemoteConnection | Promise<RemoteConnection>): (context: RemoteConnectContext) => Promise<RemoteLeasedConnection<PoolLease>>;
+  /** The service's `release`. */
+  release(lease: PoolLease, info: RemoteReleaseInfo): Promise<void>;
+  /** Close now: abort a pending `open`, then close the resource. Runs at shutdown. */
+  flush(): Promise<void>;
+  /** Unregister from shutdown and drop the idle timer, without closing (for tests). */
+  dispose(): void;
+}
+/**
+ * Share one resource between connections: opened by the first, closed `idleMs` after the last
+ * was released (or at once on shutdown). A connection arriving while it closes waits, then opens it
+ * again. After a failed `close` the resource is `unknown`: the next connection opens it again and
+ * the idle timer retries the close.
+ */
+declare function refCounted<TResource>(options: RefCountedOptions<TResource>): RefCounted<TResource>;
+export { PoolLease, RefCounted, RefCountedOptions, refCounted };
+//# sourceMappingURL=remote-pool.d.mts.map

package/dist/adapters/remote-pool.mjs

@@ -0,0 +1,195 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { onRemoteShutdown } from "./remote-lease-shutdown.mjs";
+// src/adapters/remote-pool.ts
+/**
+* Share one resource between connections: opened by the first, closed `idleMs` after the last
+* was released (or at once on shutdown). A connection arriving while it closes waits, then opens it
+* again. After a failed `close` the resource is `unknown`: the next connection opens it again and
+* the idle timer retries the close.
+*/
+function refCounted(options) {
+	const pool = new Pool(options);
+	const unregister = onRemoteShutdown(async () => {
+		await pool.flush();
+	});
+	return {
+		connect: (build) => async (context) => {
+			const slot = await pool.take(context);
+			try {
+				return {
+					...await build(slot.resource, context),
+					lease: slot
+				};
+			} catch (error) {
+				pool.give(slot);
+				throw error;
+			}
+		},
+		release: async (lease) => {
+			pool.give(lease);
+			await Promise.resolve();
+		},
+		flush: async () => {
+			await pool.flush();
+		},
+		dispose: () => {
+			unregister();
+			pool.dispose();
+		}
+	};
+}
+var Pool = class {
+	#state = "idle";
+	#slot;
+	#stale;
+	#hasStale = false;
+	#cancelIdle;
+	#opening;
+	#openController;
+	#waiters = /* @__PURE__ */ new Set();
+	#closing;
+	#options;
+	constructor(options) {
+		this.#options = options;
+	}
+	/** A connection's share of the resource, opening it first when nobody has. */
+	async take(context) {
+		for (;;) if (this.#state === "closing") await this.#closing?.catch(() => {});
+		else if (this.#state === "opening") await this.#waitOpen(context.signal);
+		else if (this.#state === "open" && this.#slot !== void 0) {
+			this.#clearIdle();
+			this.#slot.count += 1;
+			return this.#slot;
+		} else this.#startOpen(context);
+	}
+	/** A connection is done with its slot; the last one starts the idle timer. */
+	give(slot) {
+		slot.count = Math.max(0, slot.count - 1);
+		if (slot === this.#slot && slot.count === 0 && this.#state === "open") this.#armIdle();
+	}
+	/** Close now, aborting a pending open first. */
+	async flush() {
+		this.#clearIdle();
+		this.#openController?.abort();
+		await this.#opening?.catch(() => {});
+		if (this.#state === "closing") await this.#closing?.catch(() => {});
+		if (this.#state === "open" || this.#state === "unknown") await this.#close();
+	}
+	dispose() {
+		this.#clearIdle();
+	}
+	#startOpen(context) {
+		this.#clearIdle();
+		const controller = new AbortController();
+		this.#openController = controller;
+		this.#state = "opening";
+		this.#opening = this.#options.open(context, controller.signal).then((resource) => {
+			this.#slot = {
+				resource,
+				count: 0
+			};
+			this.#hasStale = false;
+			this.#stale = void 0;
+			this.#state = "open";
+		}, async (error) => {
+			this.#state = this.#hasStale ? "unknown" : "idle";
+			if (this.#hasStale) this.#armIdle();
+			await this.#closeLeftover(error);
+			throw error;
+		}).finally(() => {
+			this.#openController = void 0;
+			this.#waiters.clear();
+		});
+		this.#opening.catch(() => {});
+		this.#waitOpen(context.signal).catch(() => {});
+	}
+	/** Wait for the open in flight; it is aborted once every waiter has given up. */
+	async #waitOpen(signal) {
+		this.#waiters.add(signal);
+		const onAbort = () => {
+			this.#waiters.delete(signal);
+			if (this.#waiters.size === 0) this.#openController?.abort();
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			await this.#opening;
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+	#armIdle() {
+		this.#clearIdle();
+		const schedule = this.#options.schedule ?? scheduleTimeout;
+		this.#cancelIdle = schedule(() => {
+			if ((this.#slot?.count ?? 0) === 0) this.#close().catch(() => {});
+		}, this.#options.idleMs);
+	}
+	#clearIdle() {
+		this.#cancelIdle?.();
+		this.#cancelIdle = void 0;
+	}
+	async #close() {
+		const resource = this.#slot?.resource ?? this.#stale;
+		if (resource === void 0 || this.#state === "closing") return;
+		this.#state = "closing";
+		this.#closing = this.#runClose(resource);
+		await this.#closing;
+	}
+	async #runClose(resource) {
+		try {
+			await timed(async () => {
+				await this.#options.close(resource);
+			}, this.#options.closeTimeoutMs ?? 3e4);
+			this.#settle("idle");
+		} catch (error) {
+			this.#settle("unknown", resource);
+			this.#options.logger?.warn({ err: error instanceof Error ? error.name : "Error" }, "remote pool close failed, will retry after the idle period");
+			this.#armIdle();
+		}
+	}
+	/** After a close: `idle` with nothing, or `unknown` holding the resource to close again. */
+	#settle(state, stale) {
+		this.#slot = void 0;
+		this.#stale = stale;
+		this.#hasStale = state === "unknown";
+		this.#state = state;
+	}
+	/** An `open` that failed after starting something may name it, so it is not left running. */
+	async #closeLeftover(error) {
+		const leftover = error?.resource;
+		if (leftover === void 0) return;
+		try {
+			await timed(async () => {
+				await this.#options.close(leftover);
+			}, this.#options.closeTimeoutMs ?? 3e4);
+		} catch (closeError) {
+			this.#options.logger?.warn({ err: closeError instanceof Error ? closeError.name : "Error" }, "remote pool close failed after a failed open");
+		}
+	}
+};
+/** The default scheduler: an unref'd timer, so an idle pool never keeps the process alive. */
+function scheduleTimeout(run, ms) {
+	const timer = setTimeout(run, ms);
+	timer.unref();
+	return () => {
+		clearTimeout(timer);
+	};
+}
+async function timed(run, ms) {
+	let timer;
+	const deadline = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			reject(Object.assign(/* @__PURE__ */ new Error(`close timed out after ${ms} ms`), { name: "CloseTimeout" }));
+		}, ms);
+	});
+	try {
+		await Promise.race([run(), deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+export { refCounted };
+
+//# sourceMappingURL=remote-pool.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-pool.mjs","names":[],"sources":["../../src/adapters/remote-pool.ts"],"sourcesContent":["/**\n * A shared resource behind a remote service, opened by the first connection and closed once the\n * last one has been idle for a while: a computer woken for the builds' shards and suspended after\n * (ADR 0007, decision 4). One pool per service; its connections share the resource.\n */\nimport type { Logger } from \"../logger.ts\";\nimport type {\n  RemoteConnectContext,\n  RemoteConnection,\n  RemoteLeasedConnection,\n  RemoteReleaseInfo,\n} from \"./remote-browser.ts\";\nimport { onRemoteShutdown } from \"./remote-lease.ts\";\n\n/** Options of {@link refCounted}. */\nexport interface RefCountedOptions<TResource> {\n  /**\n   * Start the resource (wake the computer) and return what connections need of it. Called by the\n   * first connection; concurrent first connections share the call. Must be idempotent: it runs\n   * again after a failed `close`, and may overlap a `close` that timed out. `signal` aborts when\n   * every waiting connection was cancelled, and at shutdown: clean up after yourself when it does,\n   * or throw an error with a `resource` property so the pool closes it.\n   */\n  open: (context: RemoteConnectContext, signal: AbortSignal) => Promise<TResource>;\n  /** Stop the resource (suspend the computer). */\n  close: (resource: TResource) => Promise<void> | void;\n  /**\n   * How long the resource stays open with no connection, in ms. Required: set it longer than the\n   * gap between a build's passes (the extract and tests pre-passes and its shards connect close\n   * together), for example 120 000.\n   */\n  idleMs: number;\n  /** How long `close` may take in ms before it counts as failed (default 30 000). */\n  closeTimeoutMs?: number | undefined;\n  /** Where close failures go (error class only, never the message). */\n  logger?: Logger | undefined;\n  /**\n   * Runs `run` after `ms` and returns what cancels it (default: an unref'd `setTimeout`). A seam\n   * for tests to drive the idle timer without real time.\n   */\n  schedule?: ((run: () => void, ms: number) => () => void) | undefined;\n}\n\n/** What the pool hands to `release`: an opaque token for one connection. */\nexport interface PoolLease {\n  readonly pool: \"refCounted\";\n}\n\n/** A reference-counted resource, wired into a service's `connect` and `release`. */\nexport interface RefCounted<TResource> {\n  /** Build the service's `connect`: `build` gets the shared resource and returns the connection. */\n  connect(\n    build: (\n      resource: TResource,\n      context: RemoteConnectContext,\n    ) => RemoteConnection | Promise<RemoteConnection>,\n  ): (context: RemoteConnectContext) => Promise<RemoteLeasedConnection<PoolLease>>;\n  /** The service's `release`. */\n  release(lease: PoolLease, info: RemoteReleaseInfo): Promise<void>;\n  /** Close now: abort a pending `open`, then close the resource. Runs at shutdown. */\n  flush(): Promise<void>;\n  /** Unregister from shutdown and drop the idle timer, without closing (for tests). */\n  dispose(): void;\n}\n\ntype State = \"idle\" | \"opening\" | \"open\" | \"closing\" | \"unknown\";\n\ninterface Slot<TResource> {\n  resource: TResource;\n  count: number;\n}\n\n/**\n * Share one resource between connections: opened by the first, closed `idleMs` after the last\n * was released (or at once on shutdown). A connection arriving while it closes waits, then opens it\n * again. After a failed `close` the resource is `unknown`: the next connection opens it again and\n * the idle timer retries the close.\n */\nexport function refCounted<TResource>(\n  options: RefCountedOptions<TResource>,\n): RefCounted<TResource> {\n  const pool = new Pool(options);\n  const unregister = onRemoteShutdown(async () => {\n    await pool.flush();\n  });\n  return {\n    connect: (build) => async (context) => {\n      const slot = await pool.take(context);\n      try {\n        const connection = await build(slot.resource, context);\n        return { ...connection, lease: slot as unknown as PoolLease };\n      } catch (error) {\n        pool.give(slot);\n        throw error;\n      }\n    },\n    release: async (lease) => {\n      pool.give(lease as unknown as Slot<TResource>);\n      await Promise.resolve();\n    },\n    flush: async () => {\n      await pool.flush();\n    },\n    dispose: () => {\n      unregister();\n      pool.dispose();\n    },\n  };\n}\n\nclass Pool<TResource> {\n  #state: State = \"idle\";\n  #slot: Slot<TResource> | undefined;\n  #stale: TResource | undefined;\n  #hasStale = false;\n  #cancelIdle: (() => void) | undefined;\n  #opening: Promise<void> | undefined;\n  #openController: AbortController | undefined;\n  #waiters = new Set<AbortSignal>();\n  #closing: Promise<void> | undefined;\n  readonly #options: RefCountedOptions<TResource>;\n\n  constructor(options: RefCountedOptions<TResource>) {\n    this.#options = options;\n  }\n\n  /** A connection's share of the resource, opening it first when nobody has. */\n  async take(context: RemoteConnectContext): Promise<Slot<TResource>> {\n    for (;;) {\n      if (this.#state === \"closing\") {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- a connection waits for the close to end\n        await this.#closing?.catch(() => {});\n      } else if (this.#state === \"opening\") {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- waiters share the one open\n        await this.#waitOpen(context.signal);\n      } else if (this.#state === \"open\" && this.#slot !== undefined) {\n        this.#clearIdle();\n        this.#slot.count += 1;\n        return this.#slot;\n      } else {\n        this.#startOpen(context);\n      }\n    }\n  }\n\n  /** A connection is done with its slot; the last one starts the idle timer. */\n  give(slot: Slot<TResource>): void {\n    slot.count = Math.max(0, slot.count - 1);\n    if (slot === this.#slot && slot.count === 0 && this.#state === \"open\") {\n      this.#armIdle();\n    }\n  }\n\n  /** Close now, aborting a pending open first. */\n  async flush(): Promise<void> {\n    this.#clearIdle();\n    this.#openController?.abort();\n    await this.#opening?.catch(() => {});\n    if (this.#state === \"closing\") {\n      await this.#closing?.catch(() => {});\n    }\n    if (this.#state === \"open\" || this.#state === \"unknown\") {\n      await this.#close();\n    }\n  }\n\n  dispose(): void {\n    this.#clearIdle();\n  }\n\n  #startOpen(context: RemoteConnectContext): void {\n    this.#clearIdle();\n    const controller = new AbortController();\n    this.#openController = controller;\n    this.#state = \"opening\";\n    this.#opening = this.#options\n      .open(context, controller.signal)\n      .then(\n        (resource) => {\n          this.#slot = { resource, count: 0 };\n          this.#hasStale = false;\n          this.#stale = undefined;\n          this.#state = \"open\";\n        },\n        async (error: unknown) => {\n          this.#state = this.#hasStale ? \"unknown\" : \"idle\";\n          if (this.#hasStale) {\n            // Reopening cancelled the retry of the failed close; it is still owed.\n            this.#armIdle();\n          }\n          await this.#closeLeftover(error);\n          throw error;\n        },\n      )\n      .finally(() => {\n        this.#openController = undefined;\n        this.#waiters.clear();\n      });\n    // The first waiter is the caller that started it.\n    this.#opening.catch(() => {});\n    this.#waitOpen(context.signal).catch(() => {});\n  }\n\n  /** Wait for the open in flight; it is aborted once every waiter has given up. */\n  async #waitOpen(signal: AbortSignal): Promise<void> {\n    this.#waiters.add(signal);\n    const onAbort = (): void => {\n      this.#waiters.delete(signal);\n      if (this.#waiters.size === 0) {\n        this.#openController?.abort();\n      }\n    };\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n    try {\n      await this.#opening;\n    } finally {\n      signal.removeEventListener(\"abort\", onAbort);\n    }\n  }\n\n  #armIdle(): void {\n    this.#clearIdle();\n    const schedule = this.#options.schedule ?? scheduleTimeout;\n    this.#cancelIdle = schedule(() => {\n      if ((this.#slot?.count ?? 0) === 0) {\n        this.#close().catch(() => {});\n      }\n    }, this.#options.idleMs);\n  }\n\n  #clearIdle(): void {\n    this.#cancelIdle?.();\n    this.#cancelIdle = undefined;\n  }\n\n  async #close(): Promise<void> {\n    const resource = this.#slot?.resource ?? this.#stale;\n    if (resource === undefined || this.#state === \"closing\") {\n      return;\n    }\n    this.#state = \"closing\";\n    this.#closing = this.#runClose(resource);\n    await this.#closing;\n  }\n\n  async #runClose(resource: TResource): Promise<void> {\n    try {\n      await timed(async () => {\n        await this.#options.close(resource);\n      }, this.#options.closeTimeoutMs ?? 30_000);\n      this.#settle(\"idle\");\n    } catch (error) {\n      // The suspend may have worked on the server: keep the reference, but trust nothing about it.\n      this.#settle(\"unknown\", resource);\n      this.#options.logger?.warn(\n        { err: error instanceof Error ? error.name : \"Error\" },\n        \"remote pool close failed, will retry after the idle period\",\n      );\n      this.#armIdle();\n    }\n  }\n\n  /** After a close: `idle` with nothing, or `unknown` holding the resource to close again. */\n  #settle(state: \"idle\" | \"unknown\", stale?: TResource): void {\n    this.#slot = undefined;\n    this.#stale = stale;\n    this.#hasStale = state === \"unknown\";\n    this.#state = state;\n  }\n\n  /** An `open` that failed after starting something may name it, so it is not left running. */\n  async #closeLeftover(error: unknown): Promise<void> {\n    const leftover = (error as { resource?: TResource } | null)?.resource;\n    if (leftover === undefined) {\n      return;\n    }\n    try {\n      await timed(async () => {\n        await this.#options.close(leftover);\n      }, this.#options.closeTimeoutMs ?? 30_000);\n    } catch (closeError) {\n      this.#options.logger?.warn(\n        { err: closeError instanceof Error ? closeError.name : \"Error\" },\n        \"remote pool close failed after a failed open\",\n      );\n    }\n  }\n}\n\n/** The default scheduler: an unref'd timer, so an idle pool never keeps the process alive. */\nfunction scheduleTimeout(run: () => void, ms: number): () => void {\n  const timer = setTimeout(run, ms);\n  timer.unref();\n  return () => {\n    clearTimeout(timer);\n  };\n}\n\nasync function timed(run: () => Promise<void>, ms: number): Promise<void> {\n  let timer: NodeJS.Timeout | undefined;\n  const deadline = new Promise<never>((_, reject) => {\n    timer = setTimeout(() => {\n      reject(Object.assign(new Error(`close timed out after ${ms} ms`), { name: \"CloseTimeout\" }));\n    }, ms);\n  });\n  try {\n    await Promise.race([run(), deadline]);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n"],"mappings":"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"}

package/dist/adapters/render-runs.d.mts

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** In-flight render calls of a capture runner, so `cancel` reaches exactly the runs it names. */
+/**
+ * Every render call a runner has in flight, by build and run id.
+ *
+ * Several renders of one build can run at once in one process (the shards of a sharded build), and
+ * even two with the same run id (a redelivered shard). Each call registers its own entry and
+ * removes only that entry when it ends, so no render ever drops another's handle.
+ */
+declare class RenderRuns<T> {
+  #private;
+  /**
+   * Register a render call. Returns the function that removes it again (call it in `finally`).
+   *
+   * @param runId - The request's run id; a render without one is keyed by its build id.
+   */
+  add(buildId: string, runId: string | undefined, run: T): () => void;
+  /** The runs `cancel(buildId, runId)` should stop: every run of the build without a run id. */
+  matching(buildId: string, runId?: string): T[];
+}
+export { RenderRuns };
+//# sourceMappingURL=render-runs.d.mts.map