Files
hyperframes/packages/cli/src/utils/commandResult.ts
T
Miguel Ángel 1289734770 fix(cli): a finished capture exits even when a site's DNS never answers (#5983)
* fix(cli): a finished capture exits even when a site's DNS never answers

Capture resolved every page request with the system lookup and gave up after
10 s, but a system lookup cannot be cancelled: the abandoned one kept the
process alive until the OS resolver timed out, so a capture that had printed
its result could run past the app's 5-minute cap and lose its folder.
Resolve through c-ares instead, as hostAnswers does, and cancel it at the
same 10 s deadline.

* test(cli): a capture lookup that answers must exit right after too

Dropping the timer cleanup kept every successful lookup alive 10 s and no test noticed.

* fix(cli): capture falls back to the system lookup and exits once its result is out

c-ares answers first. When it has no answer, the system lookup (hosts file, OS-only DNS)
runs in a child process killed at the 10 s deadline, cached per host, because Node waits
for an in-process system lookup even in process.exit. Capture then asks the CLI to exit
100 ms after printing its result, as render does.

* fix(cli): capture reads the hosts file first and kills its lookup child on exit

The hosts file answers before DNS, as the system lookup does (overrides and 0.0.0.0
blocks keep working). A host whose system answer is cached skips c-ares, a caller that
joins a running lookup keeps its own deadline, and a pending lookup child is killed when
the CLI exits.

* fix(cli): capture's forced exit waits until a slow reader has the whole result

The root exit now waits for stdout and stderr to hand over what is already
written before it calls process.exit, so a large JSON result on a slow pipe
arrives complete. A hostname listed several times in the hosts file now has
every address checked, not only the first.

* fix(cli): keep process exit in the CLI root and let test fixtures exit

The output wait is now a helper that only waits; cli.ts still owns the
process.exit. The process-ownership check treats test fixtures like tests,
since each one runs as its own process.

* chore(cli): run the process-ownership check before every commit

A process.exit outside a process root used to pass the local hooks and fail
only in CI's Preflight.
2026-10-21 02:46:17 +00:00

150 lines
4.3 KiB
TypeScript

export type CommandResultKind = "success" | "usage_error" | "runtime_error";
export interface CommandResult {
exitCode: number;
kind: CommandResultKind;
/** The command already emitted its structured/human output. */
presented?: boolean;
}
const SUCCESS_RESULT: CommandResult = { exitCode: 0, kind: "success" };
let pendingResult: CommandResult = SUCCESS_RESULT;
let rootExitRequester: ((exitCode: number) => void) | undefined;
let rootExitCodeSanitizer: (() => void) | undefined;
export class CliUsageError extends Error {
readonly result: CommandResult;
constructor(
message = "Invalid command usage",
options: { exitCode?: number; presented?: boolean } = {},
) {
super(message);
this.name = "CliUsageError";
this.result = {
exitCode: options.exitCode ?? 1,
kind: "usage_error",
presented: options.presented,
};
}
}
export class CliRuntimeError extends Error {
readonly result: CommandResult;
constructor(
message = "Command failed",
options: { exitCode?: number; presented?: boolean; cause?: unknown } = {},
) {
super(message, options.cause === undefined ? undefined : { cause: options.cause });
this.name = "CliRuntimeError";
this.result = {
exitCode: options.exitCode ?? 1,
kind: "runtime_error",
presented: options.presented,
};
}
}
/** Internal control-flow signal for an early, already-presented result. */
export class CliResultSignal extends Error {
readonly result: CommandResult;
constructor(result: CommandResult) {
super(`CLI result ${result.exitCode}`);
this.name = "CliResultSignal";
this.result = result;
}
}
export function failCommand(exitCode = 1, cause?: unknown): never {
throw new CliRuntimeError("Command failed", { exitCode, presented: true, cause });
}
export function failUsage(exitCode = 1): never {
throw new CliUsageError("Invalid command usage", { exitCode, presented: true });
}
export function finishCommand(exitCode = 0): never {
throw new CliResultSignal({
exitCode,
kind: exitCode === 0 ? "success" : "runtime_error",
presented: true,
});
}
/** Record a non-fatal result while allowing output/finalizers to complete. */
export function setCommandResult(result: CommandResult): void {
if (pendingResult.exitCode !== 0 && result.exitCode === 0) return;
pendingResult = result;
}
export function setCommandExitCode(exitCode: number): void {
setCommandResult({
exitCode,
kind: exitCode === 0 ? "success" : "runtime_error",
presented: true,
});
}
export function consumeCommandResult(): CommandResult {
const result = pendingResult;
pendingResult = SUCCESS_RESULT;
return result;
}
/** Called only by cli.ts to retain ownership of forced process termination. */
export function registerRootExitRequester(requester: (exitCode: number) => void): void {
rootExitRequester = requester;
}
/** Called only by cli.ts to retain ownership of process exit-code mutation. */
export function registerRootExitCodeSanitizer(sanitizer: () => void): void {
rootExitCodeSanitizer = sanitizer;
}
/** Ask cli.ts to clear stray process exit state after a successful render. */
export function sanitizeSuccessfulExitCode(): void {
rootExitCodeSanitizer?.();
}
export async function outputWritten(): Promise<void> {
const written = (stream: NodeJS.WriteStream) =>
new Promise<void>((resolve) => stream.write("", () => resolve()));
await Promise.all([written(process.stdout), written(process.stderr)]);
}
/** Ask cli.ts to finalize telemetry/output and then terminate the process. */
export function requestCliExit(exitCode = 0): void {
if (!rootExitRequester) {
setCommandResult({
exitCode,
kind: exitCode === 0 ? "success" : "runtime_error",
presented: true,
});
return;
}
rootExitRequester(exitCode);
}
type UnrefableTimer = {
unref: () => void;
};
function isUnrefableTimer(
timer: ReturnType<typeof setTimeout>,
): timer is ReturnType<typeof setTimeout> & UnrefableTimer {
return (
typeof timer === "object" &&
timer !== null &&
"unref" in timer &&
typeof timer.unref === "function"
);
}
/** For a command whose result is out: ends the process if anything it started is still holding it. */
export function scheduleCliExit(exitCode = 0): void {
const timer = setTimeout(() => requestCliExit(exitCode), 100);
if (isUnrefableTimer(timer)) timer.unref();
}