Function claimAndBoot

e2e/src/ports.ts:258–299

(
  claims: ReadonlyArray<PortClaim>,
  boot: (ports: Record<string, number>) => Promise<{ teardown: () => Promise<void>; value: T }>,
  options: {
    readonly maxAttempts?: number;
    readonly label?: string;
    /** Additional acquisition failures that are safe to retry from scratch. */
    readonly retryWhen?: (error: unknown) => boolean;
  } = {},
)

 * returned `teardown` chains the caller's teardown then releases the block.
 */
export const claimAndBoot = async <T>(
  claims: ReadonlyArray<PortClaim>,
  boot: (ports: Record<string, number>) => Promise<{ teardown: () => Promise<void>; value: T }>,
  options: {
    readonly maxAttempts?: number;
    readonly label?: string;
    /** Additional acquisition failures that are safe to retry from scratch. */
    readonly retryWhen?: (error: unknown) => boolean;
  } = {},
): Promise<{ ports: Record<string, number>; teardown: () => Promise<void>; value: T }> => {
  const maxAttempts = options.maxAttempts ?? 3;
  const label = options.label ?? "boot";
  let lastError: unknown;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const { ports, release } = await claimPorts(claims);
    try {
      const booted = await boot(ports);
      return {
        ports,
        value: booted.value,
        teardown: async () => {
          await booted.teardown();
          await release();
        },
      };
    } catch (error) {
      await release();
      lastError = error;
      const retryable = isAddrInUse(error) || options.retryWhen?.(error) === true;
      if (!retryable || attempt === maxAttempts) throw error;
      const collided = claims
        .map((claim) => ports[claim.envVar])
        .filter((port): port is number => port !== undefined)
        .join(", ");
      const reason = isAddrInUse(error) ? `hit EADDRINUSE on port(s) ${collided}` : String(error);
      console.warn(
        `[e2e] ${label} acquisition failed (${reason}, attempt ${attempt}/${maxAttempts}); re-claiming a fresh block and retrying`,
      );
    }
  }
  throw lastError;
};