Files
reverse-engineering-anything/src/process/ProviderDeadline.ts
T
morluto a67dbe07a4 refactor(process): own deadlines as one monotonic type with a finalize budget (#10723)
* refactor(process): own deadlines as one monotonic type with a finalize budget

Deadline (src/domain/deadline) holds a monotonic work budget and a separate finalize budget that starts when finalization begins. ProviderStartupDeadline is built on it and exposes finalize(), so a failed Ghidra startup drains launcher output under its own budget and the caller's signal instead of the expired startup signal. The six wall-clock deadline sums in src move onto Deadline; a counted guard keeps the one page-clock conversion and rejects new copies.

* refactor(process): share one finalize window across repeated beginFinalize calls
2026-11-15 13:45:27 +08:00

183 lines
6.3 KiB
TypeScript

import { Deadline } from "../domain/deadline.js";
/** Result of an abort-aware interval wait. */
export type AbortableWaitResult = "elapsed" | "aborted";
/** Wait for an interval while removing the supplied abort listener on settle. */
export const waitForAbortableDelay = (
milliseconds: number,
signal?: AbortSignal,
): Promise<AbortableWaitResult> => {
if (signal?.aborted === true) return Promise.resolve("aborted");
return new Promise((resolve) => {
const settle = (result: AbortableWaitResult): void => {
clearTimeout(timer);
signal?.removeEventListener("abort", onAbort);
resolve(result);
};
const onAbort = (): void => settle("aborted");
const timer = setTimeout(
() => settle("elapsed"),
Math.max(0, milliseconds),
);
signal?.addEventListener("abort", onAbort, { once: true });
});
};
/** The window a startup failure finalizes under. */
export interface StartupFinalization {
/** Monotonic finalize budget, started when finalization began. */
readonly deadline: Deadline;
/** The caller's signal. Startup expiry does not interrupt finalization. */
readonly signal: AbortSignal | undefined;
}
/**
* One absolute deadline shared by every phase of a provider startup handshake,
* with a separate finalize budget for the work a failed startup still owes.
*
* The deadline owns its timer and the listener attached to an optional caller
* signal. Adapters must dispose it after startup succeeds or fails.
*/
export class ProviderStartupDeadline {
readonly #controller = new AbortController();
readonly #budget: Deadline;
readonly #externalSignal: AbortSignal | undefined;
readonly #onExternalAbort: () => void;
#timer: NodeJS.Timeout | undefined;
#interruption: "cancelled" | "timeout" | undefined;
constructor(
readonly timeoutMs: number,
signal?: AbortSignal,
options: { readonly finalizeMs?: number } = {},
) {
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
throw new RangeError("Provider startup timeout must be positive");
this.#budget = Deadline.after(timeoutMs, options);
this.#externalSignal = signal;
this.#onExternalAbort = () => {
if (this.#controller.signal.aborted) return;
if (this.#budget.expired()) {
this.#interruption = "timeout";
this.#abort(
new DOMException("Provider startup deadline elapsed", "TimeoutError"),
);
return;
}
this.#interruption = "cancelled";
this.#abort(signal?.reason);
};
if (signal?.aborted === true) {
this.#onExternalAbort();
return;
}
signal?.addEventListener("abort", this.#onExternalAbort, { once: true });
this.#armDeadlineTimer(timeoutMs);
}
/** Composite signal aborted by either the caller or the absolute deadline. */
get signal(): AbortSignal {
return this.#controller.signal;
}
/** First control path that interrupted startup, if any. */
get interruption(): "cancelled" | "timeout" | undefined {
return (
this.#interruption ?? (this.#budget.expired() ? "timeout" : undefined)
);
}
/** Milliseconds still available to the next startup phase. */
remainingMs(): number {
// Node timers can fire a fraction of a millisecond before the monotonic
// deadline, so an elapsed timer must not report time left to spend. A
// terminal timeout also cannot regain budget after later clock queries.
if (this.#interruption === "timeout") return 0;
return this.#budget.remainingMs();
}
/**
* Wait for at most one polling interval under the shared deadline signal.
*
* Both timers may fire before their monotonic targets. Retain the earlier
* of the polling target and deadline, and wait again for any residual time.
*/
wait(milliseconds: number): Promise<AbortableWaitResult> {
const startedAt = performance.now();
// Absolute target: the earlier of the requested polling interval and the
// absolute monotonic deadline.
const targetAt =
startedAt + Math.min(milliseconds, this.#budget.remainingMs());
const poll = (): Promise<AbortableWaitResult> => {
const budget = this.remainingMs();
const residual = Math.max(0, targetAt - performance.now());
return waitForAbortableDelay(
Math.min(residual, budget),
this.signal,
).then((result) => {
if (result === "aborted") return "aborted";
// The monotonic deadline expired: a full-budget wait resolves as an
// abort so polling stops at the boundary.
if (this.#budget.expired()) return "aborted";
// The polling interval elapsed without expiring the deadline.
if (performance.now() >= targetAt) return "elapsed";
// A timer fired before the absolute target; keep waiting.
return poll();
});
};
return poll();
}
/**
* Begin finalizing a failed or interrupted startup. The finalize budget
* starts now and only the caller's signal interrupts it, so work that
* exhausted the startup budget can still drain evidence and release what it
* owns.
*/
finalize(): StartupFinalization {
return {
deadline: this.#budget.beginFinalize(),
signal: this.#externalSignal,
};
}
/** Release the deadline timer and external abort listener. */
dispose(): void {
this.#clearTimer();
this.#externalSignal?.removeEventListener("abort", this.#onExternalAbort);
}
#abort(reason: unknown): void {
this.#clearTimer();
this.#externalSignal?.removeEventListener("abort", this.#onExternalAbort);
this.#controller.abort(reason);
}
#clearTimer(): void {
if (this.#timer !== undefined) clearTimeout(this.#timer);
this.#timer = undefined;
}
/**
* Arm (or re-arm) the timer that expires the absolute monotonic deadline.
*
* Re-check the clock before classifying expiry, and retain the residual
* budget when the timer arrives early.
*/
#armDeadlineTimer(milliseconds: number): void {
this.#timer = setTimeout(() => {
this.#timer = undefined;
if (this.#controller.signal.aborted) return;
if (this.#budget.expired()) {
this.#interruption = "timeout";
this.#abort(
new DOMException("Provider startup deadline elapsed", "TimeoutError"),
);
return;
}
this.#armDeadlineTimer(this.remainingMs());
}, milliseconds);
}
}