mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
* feat(cli): add hyperframes/api entry with transcribe and removeBackground HyperFrames Desktop runs the CLI as a child process, relaunching Electron with ELECTRON_RUN_AS_NODE=1. A programmatic entry lets it import plain functions and run them in a utilityProcess instead, so the RunAsNode fuse can be turned off. packages/cli/src/api.ts exports transcribe() and removeBackground(): typed options in, typed result out, progress through callbacks, failures thrown as TranscribeError / RemoveBackgroundError with a code and the original error as cause. Neither prints, reads argv or exits. The transcribe and remove-background commands now keep only flag handling, printing and exit codes, and call these functions. Their output, JSON and exit codes are unchanged. The package gains an exports map with "./api" (built dist plus d.ts) and "./package.json", generated from package-subpaths.json like the sibling packages. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(cli): trim api.ts comments under the package's comment share Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(cli): trim trailing dots without a quadratic regex CodeQL flags the trailing-dots regex on the Parakeet error now that it sits behind a library entry. Same result, linear time. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(cli): make the transcribe API's signal stop every stage Review follow-ups on the api entry: - parakeet-mlx now runs as an async child that the caller's signal can kill. Its failures keep the synchronous run's message, status and stderr. - A pre-aborted signal throws before any setup. Whisper checks the signal before each setup stage, and the model download gets it. - onEngine reports the model whisper runs (small for Spanish, not small.en). The resolver moved to whisper/modelForLanguage.ts so both share it. - api/transcribe.ts imports everything at module scope. The command test hoists its whisper mock, since that module now loads during imports. - whisper's internal TranscribeOptions/TranscribeResult types are renamed WhisperOptions/RunnerResult, so the API's public names are unique. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(cli): let an AbortSignal stop whisper's install and audio prep Review follow-ups on the api entry: - whisper's runtime install (brew, git clone, cmake) and its ffmpeg audio prep run through a new stoppableExecFile when an API caller passes a signal. The child runs off the event loop, an abort ends it and every process it started, and the call rejects with a "cancelled" TranscribeError once they are gone. A failure throws the same error execFileSync throws (message, code, errno, status, signal, stdout, stderr), compared field by field in stoppableExecFile.test.ts. parakeet-mlx uses the same helper. - Without a signal the helper is execFileSync, and the CLI passes none, so the CLI output stays byte for byte the same as hyperframes 0.8.146. - TranscribeOptions.signal now says what it covers: a tool lookup that is already running (capped at 10 seconds) finishes first. - New regressions in api.test.ts abort during a stand-in install step and during a stand-in ffmpeg convert. Both end in under 10 seconds with no process left, and both fail with the old synchronous calls. - Tests load every module at the top of the file: namespace spies replace the importOriginal partial mocks, and node:fs and node:child_process are spied through their default exports and synced with syncBuiltinESMExports. remove-background --info imports its manager statically. The scanner in api.test.ts now reads every file this PR touches and catches importOriginal and vi.importActual. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
173 lines
6.0 KiB
TypeScript
173 lines
6.0 KiB
TypeScript
import { randomUUID } from "node:crypto";
|
|
import { createWriteStream, renameSync, unlinkSync } from "node:fs";
|
|
import { get as httpsGet } from "node:https";
|
|
import type { ClientRequest, IncomingMessage } from "node:http";
|
|
import { Transform } from "node:stream";
|
|
import { pipeline } from "node:stream/promises";
|
|
|
|
const DEFAULT_DOWNLOAD_TIMEOUT_MS = 30_000;
|
|
|
|
export interface DownloadOptions {
|
|
/** Abort after this many milliseconds without network activity. */
|
|
timeoutMs?: number;
|
|
/** Reject before writing more than this many response bytes. */
|
|
maxBytes?: number;
|
|
onProgress?: (receivedBytes: number, totalBytes: number | null) => void;
|
|
/** Aborting it destroys the request and removes the partial file. */
|
|
signal?: AbortSignal;
|
|
}
|
|
|
|
/** Every redirect a host may reasonably answer with, not just the two we saw first. */
|
|
export const REDIRECT_CODES = new Set([301, 302, 303, 307, 308]);
|
|
|
|
/**
|
|
* Where a redirect actually points.
|
|
*
|
|
* Split out because this is the part that was wrong, and it is the part that
|
|
* can be checked without a socket: hosts answer with relative locations
|
|
* (`/api/resolve-cache/...`) far more often than the original code assumed, and
|
|
* handing that string back as a request target fails.
|
|
*/
|
|
export function redirectTarget(location: string, from: string): string {
|
|
return new URL(location, from).toString();
|
|
}
|
|
|
|
/** Enough hops for a CDN handoff, few enough that a redirect loop still ends. */
|
|
const MAX_REDIRECTS = 10;
|
|
|
|
function removePartialFile(path: string): void {
|
|
try {
|
|
unlinkSync(path);
|
|
} catch {
|
|
// Missing/locked partial files are handled by the next atomic download.
|
|
}
|
|
}
|
|
|
|
function measureDownload(options: DownloadOptions, contentLength: string | undefined) {
|
|
const length = Number(contentLength);
|
|
const totalBytes = Number.isSafeInteger(length) && length >= 0 ? length : null;
|
|
let receivedBytes = 0;
|
|
let reportedAt = Date.now();
|
|
options.onProgress?.(0, totalBytes);
|
|
const stream = new Transform({
|
|
transform(chunk: Buffer, _encoding, callback) {
|
|
receivedBytes += chunk.byteLength;
|
|
if (options.maxBytes !== undefined && receivedBytes > options.maxBytes) {
|
|
callback(new Error(`Download exceeded ${options.maxBytes} bytes`));
|
|
return;
|
|
}
|
|
const now = Date.now();
|
|
if (now - reportedAt >= 100) {
|
|
options.onProgress?.(receivedBytes, totalBytes);
|
|
reportedAt = now;
|
|
}
|
|
callback(null, chunk);
|
|
},
|
|
});
|
|
return { stream, complete: () => options.onProgress?.(receivedBytes, totalBytes) };
|
|
}
|
|
|
|
function getUrl(
|
|
url: string,
|
|
signal: AbortSignal | undefined,
|
|
onResponse: (res: IncomingMessage) => void,
|
|
): ClientRequest {
|
|
return signal ? httpsGet(url, { signal }, onResponse) : httpsGet(url, onResponse);
|
|
}
|
|
|
|
/**
|
|
* Download a file from a URL, following redirects.
|
|
* Uses atomic write (download to .tmp, rename on success) to prevent
|
|
* corrupt partial files from persisting in the cache on interruption.
|
|
*
|
|
* Location headers are resolved against the URL that sent them, because they
|
|
* are frequently relative: a host answering 307 with `/api/resolve-cache/...`
|
|
* is normal, and passing that string back as a request target is not.
|
|
*
|
|
* The timeout is per request, so it re-arms on each hop of a redirect chain
|
|
* rather than budgeting the whole chain. A stalled socket is what it exists to
|
|
* catch, and without it the CLI waits forever.
|
|
*/
|
|
export function downloadFile(
|
|
url: string,
|
|
dest: string,
|
|
options: DownloadOptions = {},
|
|
): Promise<void> {
|
|
const tmp = `${dest}.${process.pid}.${randomUUID()}.tmp`;
|
|
const timeoutMs = options.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;
|
|
return new Promise((resolve, reject) => {
|
|
const follow = (u: string, hops = 0) => {
|
|
let activeResponse: IncomingMessage | undefined;
|
|
let responseDiscarded = false;
|
|
let responsePipelineStarted = false;
|
|
let requestError: Error | undefined;
|
|
let request: ClientRequest;
|
|
try {
|
|
request = getUrl(u, options.signal, (res) => {
|
|
activeResponse = res;
|
|
if (res.statusCode && REDIRECT_CODES.has(res.statusCode)) {
|
|
const location = res.headers.location;
|
|
if (location) {
|
|
responseDiscarded = true;
|
|
res.destroy();
|
|
if (hops >= MAX_REDIRECTS) {
|
|
removePartialFile(tmp);
|
|
reject(
|
|
new Error(`Download failed: more than ${MAX_REDIRECTS} redirects from ${url}`),
|
|
);
|
|
return;
|
|
}
|
|
try {
|
|
follow(redirectTarget(location, u), hops + 1);
|
|
} catch (error) {
|
|
removePartialFile(tmp);
|
|
reject(error);
|
|
}
|
|
return;
|
|
}
|
|
}
|
|
if (res.statusCode !== 200) {
|
|
responseDiscarded = true;
|
|
res.destroy();
|
|
removePartialFile(tmp);
|
|
reject(new Error(`Download failed: HTTP ${res.statusCode}`));
|
|
return;
|
|
}
|
|
const meter = measureDownload(options, res.headers["content-length"]);
|
|
const file = createWriteStream(tmp);
|
|
responsePipelineStarted = true;
|
|
const transfer = pipeline(res, meter.stream, file);
|
|
transfer
|
|
.then(() => {
|
|
renameSync(tmp, dest);
|
|
meter.complete();
|
|
resolve();
|
|
})
|
|
.catch((err) => {
|
|
removePartialFile(tmp);
|
|
reject(requestError ?? err);
|
|
});
|
|
});
|
|
} catch (error) {
|
|
removePartialFile(tmp);
|
|
reject(error);
|
|
return;
|
|
}
|
|
request.setTimeout(timeoutMs, () => {
|
|
request.destroy(new Error(`Download timed out after ${timeoutMs}ms`));
|
|
});
|
|
request.on("error", (err) => {
|
|
if (responseDiscarded) return;
|
|
if (responsePipelineStarted) {
|
|
requestError = err;
|
|
activeResponse?.destroy(err);
|
|
return;
|
|
}
|
|
removePartialFile(tmp);
|
|
reject(err);
|
|
});
|
|
};
|
|
follow(url);
|
|
});
|
|
}
|