import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js"; /** * Controls for the scenarios in * docs/development/testing.md#lifecycle-regressions that a fixed delay cannot * establish: a late handshake or work still in flight at close (`phaseGate`, * or `phaseArrival` when the work waits on something other than a release), * cancellation during final cleanup (`cancelDuringCleanup`), and mixed child * cleanup outcomes with retry (`controlledCleanup`). */ /** * A phase boundary the code under test only announces: it calls `arrive` and * keeps going (or waits on something the test triggers, such as an abort), * and the test waits until the boundary is `reached`. */ export interface PhaseArrival { /** Called by the code under test: records arrival with `value`. */ arrive(value: T): void; /** * Resolve with the arrival value once the boundary is reached. Fails if * `operation` settles first or the test wait deadline passes. */ reached(operation: Promise, boundary: string): Promise; } export const phaseArrival = (): PhaseArrival => { let arrive!: (value: T) => void; const arrived = new Promise((resolve) => { arrive = resolve; }); return { arrive, reached: async (operation, boundary) => { // Pass `arrived` itself: a derived promise would settle a turn later // and lose the race to an operation that settles right after arriving. await awaitAcknowledgement(arrived, operation, boundary); return arrived; }, }; }; /** * A phase boundary the test holds open. The code under test calls `hold` at * the boundary and waits there; the test waits until the boundary is * `reached`, acts (closes, cancels, lets a deadline pass), then `release`s it * with the value `hold` returns, or `reject`s it with the failure `hold` * throws (a late module load, a read that fails after cancellation). */ export interface PhaseGate { /** Called by the code under test: records arrival with `value`, then waits for release. */ hold(value: T): Promise; /** * Resolve with the held value once the boundary is reached. Fails if * `operation` settles first or the test wait deadline passes. */ reached(operation: Promise, boundary: string): Promise; /** * Let every current and later `hold` continue with `value`. Only the first * `release` or `reject` decides the outcome; later calls are ignored. */ release(value: R): void; /** Make every current and later `hold` throw `error`. */ reject(error: unknown): void; } export const phaseGate = (): PhaseGate => { const arrival = phaseArrival(); let release!: (value: R) => void; let reject!: (error: unknown) => void; const released = new Promise((resolve, refuse) => { release = resolve; reject = refuse; }); // A rejection before any `hold` is observed by that later `hold`, not here. released.catch(() => {}); return { // Each hold gets its own promise, so code under test that leaves a held // rejection unhandled is still reported; the guard above covers only the // gate's shared outcome. hold: (value) => { arrival.arrive(value); return released.then((outcome) => outcome); }, reached: arrival.reached, release, reject, }; }; /** * One child cleanup whose outcome the test controls. Each `close` counts an * attempt, refuses with `failure` while refused, and otherwise runs its * `release` (the real close, or a gate's `hold`). Two of them with different * outcomes cover mixed child outcomes; `allow` then a retried close covers * cleanup retry, and `attempts` shows a confirmed peer is not closed again. */ export interface ControlledCleanup { readonly attempts: number; /** Stop refusing: the next attempt runs its release. */ allow(): void; close(release?: () => unknown): Promise; } export const controlledCleanup = ({ refused = false, failure = new Error("controlled cleanup refusal"), }: { readonly refused?: boolean; readonly failure?: unknown; } = {}): ControlledCleanup => { let attempts = 0; let refusing = refused; return { get attempts() { return attempts; }, allow: () => { refusing = false; }, close: async (release) => { attempts++; if (refusing) throw failure; await release?.(); }, }; }; /** * A final cleanup step that observes cancellation: it aborts `controller` * with `reason` (whose identity the test asserts afterwards), then runs * `cleanup`. A cancellation during active work does not cover this phase. */ export const cancelDuringCleanup = ( controller: AbortController, reason: unknown, cleanup?: () => T | Promise, ): (() => Promise) => async () => { controller.abort(reason); return cleanup?.(); }; /** The rejection of `operation`, or `undefined` once it fulfils. */ export const settledCause = (operation: Promise): Promise => operation.then( () => undefined, (cause: unknown) => cause, );