Skip to content

Commit 83343cc

Browse files
committed
fix(cli): give the user-stop rule one owner, SIGHUP included, and end a cancelled install at 130
stoppedByCancelSignal in renderCancellation.ts uses the scope's own signal list (SIGINT, SIGTERM, SIGHUP) and is false whenever Node stopped the child (a code, killed, or a spawn error). decode, runFfmpeg, the runtime probe and the whisper fallback all route through it, so a probe killed by SIGHUP keeps the runtime. isWhisperTimeoutError now keys on ETIMEDOUT only, which Node sets on execFileSync's own timeout, so a SIGTERM reaches the cancel rule. A cancelled models install sets exit 130 and returns instead of failing, and the probe says what went wrong (timed out, crashed, no output).
1 parent 5ae1dc5 commit 83343cc

12 files changed

Lines changed: 130 additions & 47 deletions

File tree

‎packages/cli/src/commands/models.test.ts‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,21 @@ vi.mock("../utils/renderCancellation.js", () => ({
2020

2121
import modelsCmd from "./models.js";
2222

23-
async function install(): Promise<{ exitCode: number; out: Record<string, unknown> }> {
23+
async function install() {
2424
let exitCode = 0;
25+
let threw = false;
2526
try {
2627
await modelsCmd.run!({ args: { action: "install", name: "parakeet", json: true } } as never);
2728
} catch (err) {
2829
if (!(err instanceof CliRuntimeError)) throw err;
2930
exitCode = err.result.exitCode;
31+
threw = true;
3032
}
31-
return { exitCode, out: JSON.parse(String(vi.mocked(console.log).mock.calls.at(-1)?.[0])) };
33+
exitCode ||= consumeCommandResult().exitCode;
34+
const out: Record<string, unknown> = JSON.parse(
35+
String(vi.mocked(console.log).mock.calls.at(-1)?.[0]),
36+
);
37+
return { exitCode, threw, out };
3238
}
3339

3440
describe("models install parakeet --json", () => {
@@ -46,6 +52,7 @@ describe("models install parakeet --json", () => {
4652
it("prints one result naming what it installed and where", async () => {
4753
expect(await install()).toEqual({
4854
exitCode: 0,
55+
threw: false,
4956
out: {
5057
ok: true,
5158
model: "parakeet-tdt-0.6b-v3",
@@ -66,6 +73,7 @@ describe("models install parakeet --json", () => {
6673
sherpa.ensureParakeetModel.mockRejectedValue(new Error("tokens.txt did not match"));
6774
expect(await install()).toEqual({
6875
exitCode: 1,
76+
threw: true,
6977
out: { ok: false, error: "tokens.txt did not match" },
7078
});
7179
});
@@ -74,6 +82,7 @@ describe("models install parakeet --json", () => {
7482
sherpa.sherpaUnsupportedReason.mockReturnValue("Parakeet needs glibc 2.32 or newer");
7583
expect(await install()).toEqual({
7684
exitCode: 1,
85+
threw: true,
7786
out: { ok: false, error: "Parakeet needs glibc 2.32 or newer" },
7887
});
7988
expect(sherpa.installSherpaRuntime).not.toHaveBeenCalled();
@@ -82,8 +91,9 @@ describe("models install parakeet --json", () => {
8291

8392
it("stops with exit 130 when Ctrl-C stops the runtime check before any listener runs", async () => {
8493
sherpa.installSherpaRuntime.mockRejectedValue(new sherpa.DecodeCancelled("cancelled"));
85-
const { exitCode, out } = await install();
94+
const { exitCode, threw, out } = await install();
8695
expect(exitCode).toBe(130);
96+
expect(threw).toBe(false);
8797
expect(out).toMatchObject({ ok: false, error: expect.stringMatching(/cancelled/) });
8898
});
8999

@@ -92,8 +102,9 @@ describe("models install parakeet --json", () => {
92102
cancel.abort();
93103
signal.throwIfAborted();
94104
});
95-
const { exitCode, out } = await install();
105+
const { exitCode, threw, out } = await install();
96106
expect(exitCode).toBe(130);
107+
expect(threw).toBe(false);
97108
expect(out).toMatchObject({ ok: false, error: expect.stringMatching(/cancelled/) });
98109
expect(sherpa.installSherpaRuntime).toHaveBeenCalledWith({ signal: cancel.signal });
99110
});

‎packages/cli/src/commands/models.ts‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import * as clack from "@clack/prompts";
33
import type { Example } from "./_examples.js";
44
import { c } from "../ui/colors.js";
55
import { formatBytes } from "../ui/format.js";
6-
import { failCommand } from "../utils/commandResult.js";
6+
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
77
import { createRenderCancellationScope } from "../utils/renderCancellation.js";
88
import { PARAKEET_MODEL_LABEL } from "../whisper/parakeet.js";
99

@@ -14,10 +14,18 @@ export const examples: Example[] = [
1414
],
1515
];
1616

17-
function fail(message: string, json: boolean, exitCode = 1): never {
17+
function fail(message: string, json: boolean): never {
1818
if (json) console.log(JSON.stringify({ ok: false, error: message }));
1919
else console.error(c.error(message));
20-
failCommand(exitCode);
20+
failCommand();
21+
}
22+
23+
/** A cancel is the user's choice, not a command failure: exit 130 without a cli_error. */
24+
function reportCancel(json: boolean): void {
25+
const message = "Parakeet install cancelled; nothing partial was kept.";
26+
if (json) console.log(JSON.stringify({ ok: false, error: message }));
27+
else console.error(c.warn(message));
28+
setCommandExitCode(130);
2129
}
2230

2331
function downloadProgress(spin: Spinner) {
@@ -73,7 +81,7 @@ async function installParakeet(json: boolean): Promise<void> {
7381
spin?.stop(
7482
cancelled ? c.warn("Parakeet install cancelled") : c.error("Parakeet install failed"),
7583
);
76-
if (cancelled) fail("Parakeet install cancelled; nothing partial was kept.", json, 130);
84+
if (cancelled) return reportCancel(json);
7785
fail(err instanceof Error ? err.message : String(err), json);
7886
} finally {
7987
cancellation.dispose();

‎packages/cli/src/commands/transcribe.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,20 @@ describe("transcribe command", () => {
209209
expect(out).toEqual({ ok: false, error: "Transcription cancelled" });
210210
});
211211

212+
it("reports the fallback's own timeout as a failure, not a cancel", async () => {
213+
crashChild("SIGABRT");
214+
transcribeMock.mockImplementation(async () => {
215+
throw Object.assign(new Error("spawnSync whisper-cli ETIMEDOUT"), {
216+
code: "ETIMEDOUT",
217+
signal: "SIGTERM",
218+
});
219+
});
220+
Object.assign(runners, { sherpa: true, mlx: false });
221+
const { exitCode, out } = await transcribeFails("auto");
222+
expect(exitCode).toBe(1);
223+
expect(out.error).toMatch(/The whisper fallback failed too: spawnSync whisper-cli ETIMEDOUT/);
224+
});
225+
212226
it("--engine parakeet with nothing installed names the install command", async () => {
213227
Object.assign(runners, { sherpa: false, mlx: false });
214228
const { dir, input } = dummyAudio();

‎packages/cli/src/commands/transcribe.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,8 @@ async function transcribeAudio(
308308
sherpaUnsupportedReason,
309309
transcribeWithSherpa,
310310
} = await import("../whisper/sherpa.js");
311-
const { createRenderCancellationScope } = await import("../utils/renderCancellation.js");
311+
const { createRenderCancellationScope, stoppedByCancelSignal } =
312+
await import("../utils/renderCancellation.js");
312313

313314
const engine = (opts.engine ?? "auto").toLowerCase();
314315
if (engine !== "auto" && engine !== "parakeet" && engine !== "whisper") {
@@ -372,8 +373,7 @@ async function transcribeAudio(
372373
result = await run(runner);
373374
} catch (fallbackErr) {
374375
// Whisper runs synchronously, so Ctrl-C shows as its child's signal before any listener runs.
375-
const { code, signal } = fallbackErr as { code?: string; signal?: string };
376-
if (!code && (signal === "SIGINT" || signal === "SIGTERM")) {
376+
if (stoppedByCancelSignal(fallbackErr as { signal?: string })) {
377377
throw new DecodeCancelled("Transcription cancelled");
378378
}
379379
const why = normalizeErrorMessage(fallbackErr);

‎packages/cli/src/utils/renderCancellation.test.ts‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// fallow-ignore-file code-duplication
22
import { afterEach, describe, expect, it, vi } from "vitest";
3-
import { createRenderCancellationScope } from "./renderCancellation.js";
3+
import { createRenderCancellationScope, stoppedByCancelSignal } from "./renderCancellation.js";
44

55
afterEach(() => {
66
vi.useRealTimers();
@@ -159,3 +159,20 @@ describe("createRenderCancellationScope ancestor monitoring", () => {
159159
}
160160
});
161161
});
162+
163+
describe("stoppedByCancelSignal", () => {
164+
it("is true for a child killed by any signal the scope cancels on, SIGHUP included", () => {
165+
for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
166+
expect(stoppedByCancelSignal({ signal })).toBe(true);
167+
}
168+
});
169+
170+
it("is false when Node stopped the child or it stopped another way", () => {
171+
expect(stoppedByCancelSignal({ code: "ETIMEDOUT", signal: "SIGTERM" })).toBe(false);
172+
expect(stoppedByCancelSignal({ code: "ENOBUFS", signal: "SIGTERM" })).toBe(false);
173+
expect(stoppedByCancelSignal({ killed: true, signal: "SIGTERM" })).toBe(false);
174+
expect(stoppedByCancelSignal({ error: new Error("ETIMEDOUT"), signal: "SIGTERM" })).toBe(false);
175+
expect(stoppedByCancelSignal({ signal: "SIGKILL" })).toBe(false);
176+
expect(stoppedByCancelSignal({ code: 1, signal: null })).toBe(false);
177+
});
178+
});

‎packages/cli/src/utils/renderCancellation.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,17 @@ const RENDER_CANCELLATION_SIGNALS: readonly RenderCancellationSignal[] = [
3939
"SIGHUP",
4040
];
4141

42+
/** A child killed by one of the signals above: the user's stop, unless Node killed it (timeout, limit). */
43+
export function stoppedByCancelSignal(stop: {
44+
code?: unknown;
45+
signal?: string | null;
46+
killed?: boolean;
47+
error?: unknown;
48+
}): boolean {
49+
if (stop.code || stop.killed || stop.error) return false;
50+
return RENDER_CANCELLATION_SIGNALS.some((signal) => signal === stop.signal);
51+
}
52+
4253
function captureAncestors(
4354
pid: number,
4455
lookupParentPid: (pid: number) => number | null,

‎packages/cli/src/whisper/sherpa.test.ts‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -112,19 +112,19 @@ describe("installSherpaRuntime", () => {
112112
fakeRuntime(args[args.indexOf("--prefix") + 1]!, BROKEN),
113113
);
114114
await expect(installSherpaRuntime({ run, dir })).rejects.toThrow(
115-
"The sherpa-onnx runtime installed but does not load: libonnxruntime.so: cannot open shared object",
115+
"The sherpa-onnx runtime was reinstalled but still does not load (libonnxruntime.so: cannot open shared object). Use --engine whisper for now.",
116116
);
117117
} finally {
118118
rmSync(dir, { recursive: true, force: true });
119119
}
120120
});
121121

122-
it.skipIf(process.platform === "win32")(
123-
"treats a probe stopped by Ctrl-C as a cancel and keeps the runtime",
124-
async () => {
122+
it.skipIf(process.platform === "win32").each(["SIGINT", "SIGHUP"])(
123+
"treats a probe stopped by %s as a cancel and keeps the runtime",
124+
async (signal) => {
125125
const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
126126
try {
127-
fakeRuntime(dir, 'process.kill(process.pid, "SIGINT");');
127+
fakeRuntime(dir, `process.kill(process.pid, "${signal}");`);
128128
const run = vi.fn();
129129
await expect(installSherpaRuntime({ run, dir })).rejects.toBeInstanceOf(DecodeCancelled);
130130
expect(run).not.toHaveBeenCalled();
@@ -135,6 +135,16 @@ describe("installSherpaRuntime", () => {
135135
},
136136
);
137137

138+
it("reads its own probe timeout as a broken runtime, not a cancel, and says so", () => {
139+
const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
140+
try {
141+
fakeRuntime(dir, "Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5000);");
142+
expect(sherpaRuntimeLoadError(dir, 300)).toBe("loading it timed out after 0.3 s");
143+
} finally {
144+
rmSync(dir, { recursive: true, force: true });
145+
}
146+
});
147+
138148
it("keeps each platform and arch in its own runtime dir", () => {
139149
expect(SHERPA_RUNTIME_DIR).toMatch(
140150
new RegExp(`sherpa-onnx-node@1\\.13\\.8-${process.platform}-${process.arch}$`),

‎packages/cli/src/whisper/sherpa.ts‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { homedir } from "node:os";
55
import { join } from "node:path";
66
import { fileURLToPath } from "node:url";
77
import { downloadToFile } from "../cloud/download.js";
8+
import { stoppedByCancelSignal } from "../utils/renderCancellation.js";
89
import {
910
CACHE_DIR,
1011
install,
@@ -121,21 +122,29 @@ const LOAD_RUNTIME = `try {
121122
}`;
122123

123124
/** Loads it in a child as the decode worker does: null when it loads, else the loader's error. */
124-
export function sherpaRuntimeLoadError(dir = SHERPA_RUNTIME_DIR): string | null {
125+
export function sherpaRuntimeLoadError(
126+
dir = SHERPA_RUNTIME_DIR,
127+
timeoutMs = 60_000,
128+
): string | null {
125129
if (!isInstalled(dir, RUNTIME)) return `${RUNTIME} is not installed in ${dir}`;
126130
const env = { ...process.env, HF_SHERPA_MANIFEST: join(dir, "package.json") };
127131
const probe = spawnSync(process.execPath, ["-e", LOAD_RUNTIME], {
128132
env,
129133
encoding: "utf8",
130134
stdio: ["ignore", "ignore", "pipe"],
131-
timeout: 60_000,
135+
timeout: timeoutMs,
132136
});
133137
if (probe.status === 0) return null;
134138
// Ctrl-C reaches the probe too: a cancel, never proof that a working runtime is broken.
135-
if (!probe.error && (probe.signal === "SIGINT" || probe.signal === "SIGTERM")) {
136-
throw new DecodeCancelled("Parakeet install cancelled");
137-
}
138-
return bounded(probe.stderr?.trim() || probe.error?.message || `exited with ${probe.status}`);
139+
if (stoppedByCancelSignal(probe)) throw new DecodeCancelled("Parakeet install cancelled");
140+
const timedOut = (probe.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT";
141+
return bounded(
142+
probe.stderr?.trim() ||
143+
(timedOut ? `loading it timed out after ${timeoutMs / 1000} s` : probe.error?.message) ||
144+
(probe.signal
145+
? `loading it crashed (${probe.signal})`
146+
: `it exited ${probe.status} with no output`),
147+
);
139148
}
140149

141150
/** The native package, pinned too: the runtime's own optionalDependencies accept any 1.13.x. */
@@ -155,8 +164,11 @@ export async function installSherpaRuntime({
155164
const native = sherpaPlatformPackage();
156165
await install(dir, RUNTIME, RUNTIME_VERSION, (args) => run([...args, native], signal));
157166
const stillBroken = sherpaRuntimeLoadError(dir);
158-
if (stillBroken)
159-
throw new Error(`The sherpa-onnx runtime installed but does not load: ${stillBroken}`);
167+
if (stillBroken) {
168+
throw new Error(
169+
`The sherpa-onnx runtime was reinstalled but still does not load (${stillBroken}). Use --engine whisper for now.`,
170+
);
171+
}
160172
return true;
161173
}
162174

@@ -304,9 +316,7 @@ function decode(wavPath: string, signal: AbortSignal): Promise<SherpaWindow[]> {
304316
signal,
305317
},
306318
(err, stdout, stderr) => {
307-
const interrupted =
308-
err && !err.killed && (err.signal === "SIGINT" || err.signal === "SIGTERM");
309-
if (signal.aborted || interrupted) {
319+
if (signal.aborted || (err && stoppedByCancelSignal(err))) {
310320
reject(new DecodeCancelled("Transcription cancelled"));
311321
return;
312322
}

‎packages/cli/src/whisper/transcribe.test.ts‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -165,14 +165,17 @@ describe("resolveWhisperTimeoutMs with overrideMs", () => {
165165
});
166166

167167
describe("isWhisperTimeoutError", () => {
168-
it("returns true for a Node SIGTERM child-timeout error", () => {
169-
const err = Object.assign(new Error("Command failed"), { signal: "SIGTERM" });
168+
it("returns true for execFileSync's own timeout (ETIMEDOUT with SIGTERM)", () => {
169+
const err = Object.assign(new Error("Command failed"), {
170+
code: "ETIMEDOUT",
171+
signal: "SIGTERM",
172+
});
170173
expect(isWhisperTimeoutError(err)).toBe(true);
171174
});
172175

173-
it("returns true for an ETIMEDOUT-coded error", () => {
174-
const err = Object.assign(new Error("Command failed"), { code: "ETIMEDOUT" });
175-
expect(isWhisperTimeoutError(err)).toBe(true);
176+
it("returns false for a SIGTERM someone else sent, so it reaches the cancel rule", () => {
177+
const err = Object.assign(new Error("Command failed"), { signal: "SIGTERM" });
178+
expect(isWhisperTimeoutError(err)).toBe(false);
176179
});
177180

178181
it("returns false for a non-timeout child error", () => {
@@ -197,7 +200,10 @@ describe("wrapWhisperTimeoutError", () => {
197200
});
198201

199202
it("wraps SIGTERM timeouts with a discoverable hint naming --timeout and the env var", () => {
200-
const original = Object.assign(new Error("Command failed"), { signal: "SIGTERM" });
203+
const original = Object.assign(new Error("Command failed"), {
204+
code: "ETIMEDOUT",
205+
signal: "SIGTERM",
206+
});
201207
const wrapped = wrapWhisperTimeoutError(original, {
202208
effectiveTimeoutMs: 1_260_000,
203209
model: "medium.en",

‎packages/cli/src/whisper/transcribe.ts‎

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { join, extname } from "node:path";
55
import { tmpdir } from "node:os";
66
import { randomUUID } from "node:crypto";
77
import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
8+
import { stoppedByCancelSignal } from "../utils/renderCancellation.js";
89
import { ensureWhisper, ensureModel, hasFFmpeg, DEFAULT_MODEL } from "./manager.js";
910

1011
/**
@@ -307,12 +308,11 @@ function runFfmpeg(ffmpegPath: string, args: string[], output: string, timeout:
307308
});
308309
} catch (err) {
309310
rmSync(output, { force: true });
310-
const { code, signal, stderr } = err as { code?: string; signal?: string; stderr?: Buffer };
311+
const stop = err as { code?: string; signal?: string; stderr?: Buffer };
311312
// A code means Node stopped it; ffmpeg traps Ctrl-C and says so (exit 255 is EPERM too on 7+).
312-
if (code) throw err;
313-
const said = String(stderr ?? "").trim();
314-
const cancelled =
315-
/Exiting normally, received signal/.test(said) || signal === "SIGINT" || signal === "SIGTERM";
313+
if (stop.code) throw err;
314+
const said = String(stop.stderr ?? "").trim();
315+
const cancelled = /Exiting normally, received signal/.test(said) || stoppedByCancelSignal(stop);
316316
const reason = said.split("\n").at(-1) || (err as Error).message;
317317
// stderr: the command shows its last lines, where ffmpeg names the cause above its summary line.
318318
const failure = new Error(`ffmpeg failed: ${reason}`, { cause: err });
@@ -569,14 +569,9 @@ export async function transcribe(
569569
// Timeout error discoverability
570570
// ---------------------------------------------------------------------------
571571

572-
// Node's `execFileSync` kills the child with SIGTERM when its `timeout` option
573-
// fires, so the resulting Error carries `signal === "SIGTERM"`. On some platforms
574-
// / Node versions `code === "ETIMEDOUT"` is also set. Match either signal so we
575-
// don't miss a timeout on a platform we haven't validated.
572+
// execFileSync's own timeout sets code ETIMEDOUT (and SIGTERM); a bare SIGTERM is someone stopping it.
576573
export function isWhisperTimeoutError(err: unknown): boolean {
577-
if (!(err instanceof Error)) return false;
578-
const record = err as { signal?: unknown; code?: unknown };
579-
return record.signal === "SIGTERM" || record.code === "ETIMEDOUT";
574+
return err instanceof Error && (err as { code?: unknown }).code === "ETIMEDOUT";
580575
}
581576

582577
export interface WrapWhisperTimeoutOptions {

0 commit comments

Comments
 (0)