Skip to content

Write HTML. Render video. Built for agents.

19.0 KB
Raw Blame
import { createHash } from "node:crypto";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  rmSync,
  truncateSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { basename, dirname, join } from "node:path";
import { pathToFileURL } from "node:url";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { DownloadOptions } from "../cloud/download.js";
import { execFileSync } from "node:child_process";
import {
  decodeTimeoutMs,
  ensureParakeetModel,
  installSherpaRuntime,
  SHERPA_RUNTIME_DIR,
  sherpaPlatformPackage,
  DecodeCancelled,
  sherpaRuntimeLoadError,
  sherpaUnsupportedReason,
  transcribeWithSherpa,
  type ModelFile,
} from "./sherpa.js";
import { encodeWav } from "./wav.test-helpers.js";

const file = (name: string, content: string): ModelFile => ({
  name,
  bytes: Buffer.byteLength(content),
  sha256: createHash("sha256").update(content).digest("hex"),
});

/** A downloader that serves `served[name]` for any URL ending in that name. */
function fakeDownload(served: Record<string, string>) {
  return vi.fn(async (url: string, dest: string, opts?: DownloadOptions) => {
    const content = served[url.split("/").at(-1)!]!;
    mkdirSync(dirname(dest), { recursive: true });
    writeFileSync(dest, content);
    opts?.signal?.throwIfAborted();
    opts?.onProgress?.(Buffer.byteLength(content), undefined);
    return { path: dest, bytes: Buffer.byteLength(content) };
  });
}

/** A stand-in runtime in `root` whose entry point loads, or throws as a missing library does. */
const LOADS = "module.exports = {};";
const BROKEN = 'throw new Error("libonnxruntime.so: cannot open\\n  shared object");';
function fakeRuntime(root: string, body: string, version = "1.13.8") {
  const pkg = join(root, "node_modules", "sherpa-onnx-node");
  mkdirSync(pkg, { recursive: true });
  writeFileSync(
    join(pkg, "package.json"),
    JSON.stringify({ name: "sherpa-onnx-node", main: "index.js", version }),
  );
  writeFileSync(join(pkg, "index.js"), body);
}

describe("installSherpaRuntime", () => {
  it.each([
    ["darwin", "arm64", "[email protected]"],
    ["linux", "x64", "[email protected]"],
    ["win32", "ia32", "[email protected]"],
  ])("pins the %s-%s native package", (platform, arch, spec) => {
    expect(sherpaPlatformPackage(platform as NodeJS.Platform, arch as NodeJS.Architecture)).toBe(
      spec,
    );
  });

  it("asks npm for the runtime and its native package at the same exact version", async () => {
    const run = vi.fn(async (_args: string[]) => {
      throw new Error("stop before touching the cache");
    });
    const cancel = new AbortController();
    const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
    await installSherpaRuntime({ run, signal: cancel.signal, dir }).catch(() => undefined);
    rmSync(dir, { recursive: true, force: true });
    expect((run.mock.calls[0] as unknown[] | undefined)?.[1]).toBe(cancel.signal);
    const args = run.mock.calls[0]?.[0] as string[] | undefined;
    expect(args).toContain("[email protected]");
    expect(args).toContain(sherpaPlatformPackage());
  });

  it("reinstalls a runtime that is present but does not load", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
    try {
      fakeRuntime(dir, BROKEN);
      expect(await sherpaRuntimeLoadError(dir)).toBe(
        "libonnxruntime.so: cannot open shared object",
      );
      const run = vi.fn(async (args: string[]) =>
        fakeRuntime(args[args.indexOf("--prefix") + 1]!, LOADS),
      );

      expect(await installSherpaRuntime({ run, dir })).toEqual({
        installed: true,
        runtimePath: join(dir, "node_modules", "sherpa-onnx-node", "index.js"),
      });
      expect(run).toHaveBeenCalledTimes(1);
      expect(await sherpaRuntimeLoadError(dir)).toBeNull();
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("leaves a runtime that loads alone", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
    try {
      fakeRuntime(dir, LOADS);
      const run = vi.fn();
      expect(await installSherpaRuntime({ run, dir })).toEqual({
        installed: false,
        runtimePath: join(dir, "node_modules", "sherpa-onnx-node", "index.js"),
      });
      expect(run).not.toHaveBeenCalled();
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("fails with the loader's error when the reinstalled runtime still does not load", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
    try {
      const run = vi.fn(async (args: string[]) =>
        fakeRuntime(args[args.indexOf("--prefix") + 1]!, BROKEN),
      );
      await expect(installSherpaRuntime({ run, dir })).rejects.toThrow(
        "The sherpa-onnx runtime was reinstalled but still does not load (libonnxruntime.so: cannot open shared object). Use --engine whisper for now.",
      );
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it.skipIf(process.platform === "win32").each(["SIGINT", "SIGHUP"])(
    "treats a probe stopped by %s as a cancel and keeps the runtime",
    async (signal) => {
      const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
      try {
        fakeRuntime(dir, `process.kill(process.pid, "${signal}");`);
        const run = vi.fn();
        await expect(installSherpaRuntime({ run, dir })).rejects.toBeInstanceOf(DecodeCancelled);
        expect(run).not.toHaveBeenCalled();
        expect(existsSync(join(dir, "node_modules", "sherpa-onnx-node", "index.js"))).toBe(true);
      } finally {
        rmSync(dir, { recursive: true, force: true });
      }
    },
  );

  it("reads its own probe timeout as a broken runtime, not a cancel, and says so", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
    try {
      fakeRuntime(dir, "Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5000);");
      expect(await sherpaRuntimeLoadError(dir, 300)).toBe("loading it timed out after 0.3 s");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("reports timeout even when the runtime handles SIGTERM and exits zero", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
    try {
      fakeRuntime(
        dir,
        'process.on("SIGTERM", () => process.exit(0)); require("node:net").createServer().listen(0, "127.0.0.1");',
      );
      expect(await sherpaRuntimeLoadError(dir, 300)).toBe("loading it timed out after 0.3 s");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("keeps each platform and arch in its own runtime dir", () => {
    expect(SHERPA_RUNTIME_DIR).toMatch(
      new RegExp(`sherpa-onnx-node@1\\.13\\.8-${process.platform}-${process.arch}$`),
    );
  });
});

describe("a pinned Sherpa copy beside the CLI", () => {
  let root: string;
  beforeEach(() => {
    root = mkdtempSync(join(tmpdir(), "hf-sherpa-beside-"));
    writeFileSync(join(root, "speech.wav"), encodeWav(new Float32Array(100).fill(0.5), 100));
  });
  afterEach(() => {
    vi.restoreAllMocks();
    rmSync(root, { recursive: true, force: true });
  });

  function layout(besideBody: string, cachedBody?: string) {
    const bundle = join(root, "bundle");
    const cache = join(root, "cache");
    fakeRuntime(bundle, besideBody);
    if (cachedBody !== undefined) fakeRuntime(cache, cachedBody);
    const cliUrl = pathToFileURL(join(bundle, "dist", "cli.js")).href;
    const pinnedPath = join(bundle, "node_modules", "sherpa-onnx-node", "index.js");
    return { cache, cliUrl, pinnedPath };
  }

  function decoder() {
    const parentMarker = join(root, "loaded-in-parent");
    return `
if (process.pid === ${process.pid}) require("node:fs").writeFileSync(${JSON.stringify(parentMarker)}, "");
module.exports = {
  readWave() { throw new Error("External buffers are not allowed"); },
  OfflineRecognizer: class {
    createStream() { return { acceptWaveform() {} }; }
    decode() {}
    getResult() { return { tokens: [" hello"], timestamps: [0], durations: [1] }; }
  }
};`;
  }

  async function transcript(cache: string, cliUrl: string) {
    const out = join(root, "out");
    mkdirSync(out, { recursive: true });
    const onEvent = vi.fn();
    await transcribeWithSherpa(join(root, "speech.wav"), out, {
      signal: new AbortController().signal,
      runtimeDir: cache,
      cliUrl,
      onEvent,
    });
    const result = JSON.parse(readFileSync(join(out, "transcript.json"), "utf-8"));
    expect(result).toEqual([{ text: "hello", start: 0, end: 1 }]);
    const event = { type: "progress", phase: "transcription", model: "parakeet-tdt-0.6b-v3" };
    // The worker's one 1 s window streams its words before the final transcript.
    expect(onEvent.mock.calls).toEqual([
      // The started line sizes the WAV as 16 kHz mono: 44 header bytes and 100 samples here.
      [{ ...event, status: "started", durationSeconds: (44 + 2 * 100) / 32_000 }],
      [{ type: "words", model: event.model, words: result, through: 1 }],
      [{ ...event, status: "completed" }],
    ]);
    expect(existsSync(join(root, "loaded-in-parent"))).toBe(false);
  }

  it("loads a pinned adjacent copy without a cache or npm install", async () => {
    const { cache, cliUrl, pinnedPath } = layout(LOADS);
    const run = vi.fn();
    expect(await sherpaRuntimeLoadError(cache, 60_000, cliUrl)).toBeNull();
    expect(await installSherpaRuntime({ dir: cache, cliUrl, run })).toEqual({
      installed: false,
      runtimePath: pinnedPath,
    });
    expect(run).not.toHaveBeenCalled();
    expect(existsSync(cache)).toBe(false);
  });

  it.skipIf(process.platform === "win32")(
    "cancels an in-flight probe without inspecting the cache",
    async () => {
      const cacheMarker = join(root, "cache-loaded");
      const { cache, cliUrl } = layout(
        'require("node:net").createServer().listen(0, "127.0.0.1", () => process.kill(process.ppid, "SIGUSR2"));',
        `require("node:fs").writeFileSync(${JSON.stringify(cacheMarker)}, ""); module.exports = {};`,
      );
      const log = vi.spyOn(console, "error").mockImplementation(() => {});
      const controller = new AbortController();
      const abort = () => controller.abort();
      process.once("SIGUSR2", abort);
      try {
        await expect(
          sherpaRuntimeLoadError(cache, 300, cliUrl, controller.signal),
        ).rejects.toBeInstanceOf(DecodeCancelled);
        expect(existsSync(cacheMarker)).toBe(false);
        expect(log).not.toHaveBeenCalled();
      } finally {
        process.removeListener("SIGUSR2", abort);
      }
    },
  );

  it("passes the pinned adjacent copy to the real decode worker", async () => {
    const { cache, cliUrl } = layout(decoder());
    await transcript(cache, cliUrl);
  });

  it("logs the broken pinned path once and decodes with the healthy cache", async () => {
    const { cache, cliUrl, pinnedPath } = layout(BROKEN, decoder());
    const log = vi.spyOn(console, "error").mockImplementation(() => {});
    await transcript(cache, cliUrl);
    expect(log).toHaveBeenCalledTimes(1);
    expect(log.mock.calls[0]?.[0]).toContain(pinnedPath);
    expect(log.mock.calls[0]?.[0]).toContain("libonnxruntime.so: cannot open shared object");
    expect(String(log.mock.calls[0]?.[0])).not.toContain("\n");
  });

  it("reports an accepted package with a missing entry and uses the healthy cache", async () => {
    const { cache, cliUrl, pinnedPath } = layout(LOADS, decoder());
    rmSync(pinnedPath);
    const log = vi.spyOn(console, "error").mockImplementation(() => {});
    await transcript(cache, cliUrl);
    expect(log).toHaveBeenCalledTimes(1);
    expect(log.mock.calls[0]?.[0]).toContain(dirname(pinnedPath));
    expect(log.mock.calls[0]?.[0]).toContain("Cannot find module");
  });

  it.each([undefined, BROKEN])(
    "logs the broken pinned path once and reports repair when no cache loads (%s)",
    async (cachedBody) => {
      const { cache, cliUrl, pinnedPath } = layout(BROKEN, cachedBody);
      const log = vi.spyOn(console, "error").mockImplementation(() => {});
      const out = join(root, "out");
      mkdirSync(out);
      await expect(
        transcribeWithSherpa(join(root, "speech.wav"), out, {
          signal: new AbortController().signal,
          runtimeDir: cache,
          cliUrl,
        }),
      ).rejects.toThrow(/hyperframes models install parakeet/);
      expect(log).toHaveBeenCalledTimes(1);
      expect(log.mock.calls[0]?.[0]).toContain(pinnedPath);
      expect(log.mock.calls[0]?.[0]).toContain("libonnxruntime.so: cannot open shared object");
      expect(readdirSync(out)).toEqual([]);
    },
  );
});

describe("sherpaParakeetInstalled", () => {
  it.each(["cache", "beside CLI"])(
    "counts a broken runtime in %s, so transcribe reports it instead of skipping it",
    async (location) => {
      const home = mkdtempSync(join(tmpdir(), "hf-sherpa-home-"));
      vi.stubEnv("HOME", home);
      vi.resetModules();
      try {
        const sherpa = await import("./sherpa.js");
        const bundle = join(home, "bundle");
        const cliUrl = pathToFileURL(join(bundle, "dist", "cli.js")).href;
        const manifest = join(
          location === "cache" ? sherpa.SHERPA_RUNTIME_DIR : bundle,
          "node_modules",
          "sherpa-onnx-node",
        );
        mkdirSync(manifest, { recursive: true });
        if (location === "cache") writeFileSync(join(manifest, "package.json"), "{}");
        else fakeRuntime(bundle, BROKEN);
        mkdirSync(sherpa.PARAKEET_MODEL_DIR, { recursive: true });
        for (const [name, bytes] of [
          ["encoder.int8.onnx", 652_184_281],
          ["decoder.int8.onnx", 11_845_275],
          ["joiner.int8.onnx", 6_355_277],
          ["tokens.txt", 93_939],
        ] as const) {
          writeFileSync(join(sherpa.PARAKEET_MODEL_DIR, name), "");
          truncateSync(join(sherpa.PARAKEET_MODEL_DIR, name), bytes);
        }
        expect(sherpa.sherpaParakeetInstalled(cliUrl)).toBe(true);
      } finally {
        vi.unstubAllEnvs();
        rmSync(home, { recursive: true, force: true });
      }
    },
  );
});

describe("ensureParakeetModel", () => {
  let dir: string;
  afterEach(() => rmSync(dir, { recursive: true, force: true }));
  const tempDir = () => (dir = mkdtempSync(join(tmpdir(), "hf-parakeet-model-")));
  const stagingLeft = () =>
    readdirSync(dirname(dir)).filter((name) => name.startsWith(`${basename(dir)}.tmp-`));

  it("refuses a file whose sha256 does not match and leaves nothing under its name", async () => {
    tempDir();
    const files = [file("encoder.onnx", "abc")];
    const download = fakeDownload({ "encoder.onnx": "abd" });

    await expect(ensureParakeetModel({ dir, files, download })).rejects.toThrow(/sha256/);
    expect(readdirSync(dir)).toEqual([]);
    expect(stagingLeft()).toEqual([]);
  });

  it("names the file, the host and a retry when a download fails", async () => {
    tempDir();
    const download = vi.fn(async () => {
      throw new TypeError("fetch failed");
    });
    await expect(
      ensureParakeetModel({ dir, files: [file("encoder.onnx", "enc")], download }),
    ).rejects.toThrow(
      "Could not download encoder.onnx from huggingface.co (fetch failed). Check your network and re-run.",
    );
    expect(stagingLeft()).toEqual([]);
  });

  it("stops at the next file on cancel, keeping only files that verified", async () => {
    tempDir();
    const files = [file("encoder.onnx", "enc"), file("tokens.txt", "tok")];
    const cancel = new AbortController();
    const download = fakeDownload({ "encoder.onnx": "enc", "tokens.txt": "tok" });
    download.mockImplementationOnce(async (_url, dest) => {
      mkdirSync(dirname(dest), { recursive: true });
      writeFileSync(dest, "enc");
      cancel.abort();
      return { path: dest, bytes: 3 };
    });

    await expect(
      ensureParakeetModel({ dir, files, download, signal: cancel.signal }),
    ).rejects.toThrow(/abort/i);
    expect(download).toHaveBeenCalledTimes(1);
    expect(download.mock.calls[0]?.[2]?.signal).toBe(cancel.signal);
    expect(readdirSync(dir)).toEqual(["encoder.onnx"]);
    expect(stagingLeft()).toEqual([]);
  });

  it("sweeps the staging dir a killed install left behind", async () => {
    tempDir();
    const stale = `${dir}.tmp-999999999-dead`;
    mkdirSync(stale);
    writeFileSync(join(stale, "encoder.onnx"), "half");
    const files = [file("tokens.txt", "tok")];

    await ensureParakeetModel({ dir, files, download: fakeDownload({ "tokens.txt": "tok" }) });
    expect(existsSync(stale)).toBe(false);
  });

  it("fetches only what is missing or corrupt, then is a no-op", async () => {
    tempDir();
    mkdirSync(dir, { recursive: true });
    const files = [
      file("encoder.onnx", "enc"),
      file("tokens.txt", "tok"),
      file("joiner.onnx", "j"),
    ];
    writeFileSync(join(dir, "encoder.onnx"), "enc");
    writeFileSync(join(dir, "tokens.txt"), "xxx");
    const download = fakeDownload({ "tokens.txt": "tok", "joiner.onnx": "j" });
    const onBytes = vi.fn();

    expect(await ensureParakeetModel({ dir, files, download, onBytes })).toBe(true);
    expect(download.mock.calls.map(([url]) => url.split("/").at(-1))).toEqual([
      "tokens.txt",
      "joiner.onnx",
    ]);
    expect(readdirSync(dir).sort()).toEqual(["encoder.onnx", "joiner.onnx", "tokens.txt"]);
    expect(onBytes.mock.calls.at(-1)).toEqual([4, 4]);

    download.mockClear();
    expect(await ensureParakeetModel({ dir, files, download })).toBe(false);
    expect(download).not.toHaveBeenCalled();
    expect(existsSync(join(dir, "tokens.txt"))).toBe(true);
  });
});

describe("sherpaUnsupportedReason", () => {
  const linux = (glibc?: string) => ({ platform: "linux", arch: "x64", glibc });

  it("refuses Linux without glibc 2.32 and accepts newer glibc", () => {
    expect(sherpaUnsupportedReason(linux("2.31"))).toMatch(/glibc 2\.32.*2\.31/);
    expect(sherpaUnsupportedReason(linux())).toMatch(/musl/);
    expect(sherpaUnsupportedReason(linux("2.32"))).toBeNull();
    expect(sherpaUnsupportedReason(linux("2.36"))).toBeNull();
  });

  it("refuses targets with no native package, naming the ones that have one", () => {
    expect(sherpaUnsupportedReason({ platform: "darwin", arch: "arm64" })).toBeNull();
    expect(sherpaUnsupportedReason({ platform: "win32", arch: "x64" })).toBeNull();
    expect(sherpaUnsupportedReason({ platform: "win32", arch: "arm64" })).toMatch(
      /darwin-arm64.*win32-ia32; this system is win32-arm64/,
    );
    expect(sherpaUnsupportedReason({ platform: "linux", arch: "arm", glibc: "2.36" })).toMatch(
      /this system is linux-arm/,
    );
  });
});

describe("decodeTimeoutMs", () => {
  // 1851.245125 s of audio once gave 3702490.25, which execFile refused as out of range.
  it.each([1851.245125, 10_000_000])(
    "gives execFile a timeout it accepts for %s s of audio",
    (seconds) => {
      const timeout = decodeTimeoutMs(seconds);
      expect(Number.isInteger(timeout)).toBe(true);
      expect(timeout).toBeGreaterThanOrEqual(Math.min(seconds * 2000, 2 ** 31 - 1));
      expect(() => execFileSync(process.execPath, ["-e", ""], { timeout })).not.toThrow();
    },
  );
});