Files
rea/src/process/PendingOperations.ts
T
N0zoM1z0andN0zoM1z0 70e1a0f532 refactor(process): extract reusable provider lifecycle primitives
Introduce provider-neutral ownership, private runtime roots, absolute startup deadlines, pending-operation correlation, bounded output capture, and verified TERM-to-KILL process supervision.\n\nMigrate Hopper onto the shared lifecycle pieces while keeping its Unix-socket protocol and health/shutdown parsing adapter-specific. Preserve exact ownership checks and fail-closed cleanup, including descendant cleanup after the launcher leader exits.\n\nAdd reusable process fixtures and deterministic coverage for startup timeout, cancellation, output bounds, exit diagnostics, cleanup escalation, repeated close, spawn failure, and resource disposal. Update architecture, provider evaluation, contributor guidance, and generated API documentation.
2026-07-15 23:20:48 +09:00

84 lines
2.7 KiB
TypeScript

/** Timeout and cancellation projections for one correlated operation. */
export interface PendingOperationOptions<Value> {
readonly timeoutMs: number;
readonly signal?: AbortSignal;
readonly timeoutValue: () => Value;
readonly cancelledValue: () => Value;
}
interface PendingOperation<Value> {
readonly resolve: (value: Value) => void;
readonly timer: NodeJS.Timeout;
readonly signal: AbortSignal | undefined;
readonly onAbort: (() => void) | undefined;
}
/**
* Correlates event-driven provider replies with bounded waits.
*
* The registry owns every request timer and abort listener. Settling, timing
* out, cancelling, or failing an operation removes both before resolution, so
* late protocol replies can be ignored without retaining request resources.
*/
export class PendingOperations<Key, Value> {
readonly #pending = new Map<Key, PendingOperation<Value>>();
/** Number of currently correlated operations. */
get size(): number {
return this.#pending.size;
}
/** Return whether an operation key is awaiting a protocol reply. */
has(key: Key): boolean {
return this.#pending.has(key);
}
/** Register one unique operation key and start its bounded wait. */
wait(key: Key, options: PendingOperationOptions<Value>): Promise<Value> {
if (this.#pending.has(key))
throw new Error("Pending operation key is already registered");
if (options.signal?.aborted === true)
return Promise.resolve(options.cancelledValue());
return new Promise((resolve) => {
const onAbort =
options.signal === undefined
? undefined
: () => this.#finish(key, options.cancelledValue());
const timer = setTimeout(
() => this.#finish(key, options.timeoutValue()),
options.timeoutMs,
);
this.#pending.set(key, {
resolve,
timer,
signal: options.signal,
onAbort,
});
if (onAbort !== undefined)
options.signal?.addEventListener("abort", onAbort, { once: true });
});
}
/** Settle one correlated reply; returns false for late or unknown keys. */
settle(key: Key, value: Value): boolean {
return this.#finish(key, value);
}
/** Fail every active operation while releasing all timers and listeners. */
failAll(valueFor: (key: Key) => Value): void {
for (const key of this.#pending.keys()) this.#finish(key, valueFor(key));
}
#finish(key: Key, value: Value): boolean {
const pending = this.#pending.get(key);
if (pending === undefined) return false;
this.#pending.delete(key);
clearTimeout(pending.timer);
if (pending.signal !== undefined && pending.onAbort !== undefined)
pending.signal.removeEventListener("abort", pending.onAbort);
pending.resolve(value);
return true;
}
}