@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/utils/download-common.js

@@ -0,0 +1,196 @@
+/**
+ * Shared primitives for the model download helpers — the event/result
+ * contract, retry/backoff math, partial-file sizing, friendly error mapping,
+ * and the honest gezel User-Agent. Both the classic streaming downloader
+ * (`download-with-retry.ts`) and the Xet reconstruction downloader
+ * (`xet-download.ts`) build on these, so neither has to import the other at
+ * runtime (avoids a cycle).
+ */
+import { statSync } from 'node:fs';
+import { DEFAULT_BACKOFF_SCHEDULE_MS, GEZEL_VERSION, backoffDelayMs, createLogger, sleepWithAbort, } from '@bendyline/gezel';
+export const downloadLog = createLogger('download');
+/**
+ * Honest User-Agent sent on every model-download request. We identify
+ * ourselves as gezel rather than impersonating a browser or the huggingface
+ * client — HF's Xet backend serves anonymous public reads, and being
+ * transparent about who we are is the right posture for a third-party client
+ * fetching public weights on the user's behalf.
+ */
+export const GEZEL_DOWNLOAD_UA = `gezel/${GEZEL_VERSION} (+https://github.com/bendyline/gezel)`;
+/**
+ * Headers for an HF control-plane request. An optional operator token raises
+ * public-model rate limits, but is never forwarded to Xet/CAS/CDN hosts.
+ */
+export function huggingFaceRequestHeaders(url, token = process.env.HF_TOKEN ?? process.env.HUGGING_FACE_HUB_TOKEN) {
+    const headers = { 'User-Agent': GEZEL_DOWNLOAD_UA };
+    try {
+        if (new URL(url).hostname === 'huggingface.co' && token?.trim()) {
+            headers.Authorization = `Bearer ${token.trim()}`;
+        }
+    }
+    catch {
+        // The fetch will surface an invalid URL. Do not add credentials while
+        // handling it here.
+    }
+    return headers;
+}
+/** Upper bound on *consecutive* failed attempts that made no headway. 5 covers
+ * the dominant on-device failure modes (transient ISP blip, mid-day
+ * congestion, brief HF rate-limit) without giving up too readily. An attempt
+ * that moved real bytes refunds this budget — see `DownloadRetryBudget`. */
+export const DEFAULT_MAX_RETRIES = 5;
+/** Absolute ceiling on attempts for one file, however much progress is being
+ * made. A 30 GB download over a link that drops every 200 MB legitimately
+ * needs a lot of resumes; this only exists so a pathological
+ * fails-after-one-chunk loop can't spin forever. */
+export const MAX_TOTAL_ATTEMPTS = 100;
+/** Forward progress that counts as "this transfer is alive" and refunds the
+ * consecutive-failure budget. Deliberately larger than one HTTP chunk so a
+ * server that hands us 64 KiB and hangs up can't refill the budget forever. */
+export const PROGRESS_REFUND_BYTES = 4 * 1024 * 1024;
+/** Backoff schedule (ms). Index = attempt number (0-based). Jitter is added on
+ * top so two parallel downloads don't retry in lockstep. */
+const BACKOFF_SCHEDULE_MS = DEFAULT_BACKOFF_SCHEDULE_MS;
+/** No-bytes-arrived window before we declare a transfer dead. */
+export const DEFAULT_CHUNK_TIMEOUT_MS = 20_000;
+export function existingPartialSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+export function retryDelayMs(retryIndex) {
+    return backoffDelayMs(retryIndex, BACKOFF_SCHEDULE_MS);
+}
+export async function sleepRespectingAbort(ms, signal) {
+    return sleepWithAbort(ms, signal);
+}
+/**
+ * Attempt accounting for a resumable download.
+ *
+ * The naive "5 attempts per file, then give up" budget is what made the
+ * first-run model install fail with a bare "network error": a 12 GB GGUF over
+ * a link that drops every couple of minutes burns all five attempts inside the
+ * first ten minutes and quits — even though every one of those attempts moved
+ * hundreds of megabytes onto disk and the transfer was, in the only sense the
+ * user cares about, working.
+ *
+ * So the budget counts *consecutive failures that made no headway*. An attempt
+ * that pushed the byte high-water mark forward by at least
+ * `PROGRESS_REFUND_BYTES` resets the counter (and the backoff schedule with
+ * it, since the network clearly isn't down). `MAX_TOTAL_ATTEMPTS` is the
+ * backstop for a server that hands us a little data and dies every single
+ * time.
+ *
+ * A budget constructed with `maxConsecutive <= 1` never refunds, so callers
+ * that pass `maxRetries: 1` still get exactly one attempt.
+ */
+export class DownloadRetryBudget {
+    maxConsecutive;
+    maxTotal;
+    consecutiveFailures = 0;
+    attemptsStarted = 0;
+    highWaterBytes;
+    constructor(maxConsecutive, startBytes = 0, maxTotal = MAX_TOTAL_ATTEMPTS) {
+        this.maxConsecutive = maxConsecutive;
+        this.maxTotal = maxTotal;
+        this.highWaterBytes = startBytes;
+    }
+    /** True while another attempt is permitted. */
+    canAttempt() {
+        return this.consecutiveFailures < this.maxConsecutive && this.attemptsStarted < this.maxTotal;
+    }
+    /** Call once at the top of each attempt. */
+    beginAttempt() {
+        return ++this.attemptsStarted;
+    }
+    /** Total attempts started so far — reported in the terminal error. */
+    get attemptsMade() {
+        return this.attemptsStarted;
+    }
+    /** Record a transient failure at `bytesWritten` bytes of on-disk progress. */
+    recordFailure(bytesWritten) {
+        const refundable = this.maxConsecutive > 1 && bytesWritten >= this.highWaterBytes + PROGRESS_REFUND_BYTES;
+        if (bytesWritten > this.highWaterBytes)
+            this.highWaterBytes = bytesWritten;
+        this.consecutiveFailures = refundable ? 0 : this.consecutiveFailures + 1;
+    }
+    /** Wait to serve before the next attempt, based on the consecutive streak. */
+    nextDelayMs() {
+        return retryDelayMs(Math.max(0, this.consecutiveFailures - 1));
+    }
+    /** 1-based number of the attempt about to start, for `retrying` events. */
+    get nextAttemptLabel() {
+        return this.consecutiveFailures + 1;
+    }
+    get maxAttempts() {
+        return this.maxConsecutive;
+    }
+}
+/**
+ * Map raw fetch/network errors to a single user-readable sentence.
+ * Keep these short — the UI shows them inline in a small banner.
+ */
+export function friendlyFetchError(err) {
+    const raw = rawErrorString(err);
+    if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(raw)) {
+        return "Couldn't reach the model host — your internet may be offline";
+    }
+    if (/ECONNREFUSED/i.test(raw)) {
+        return 'Model host refused the connection';
+    }
+    if (/ETIMEDOUT|ETIMEOUT|UND_ERR_CONNECT_TIMEOUT/i.test(raw)) {
+        return 'Connection timed out';
+    }
+    if (/ECONNRESET|UND_ERR_SOCKET|socket hang up/i.test(raw)) {
+        return 'Connection was dropped';
+    }
+    if (/CERT|certificate|self.?signed/i.test(raw)) {
+        return 'TLS certificate error reaching the model host';
+    }
+    return 'Network error reaching the model host';
+}
+export function friendlyStreamError(err) {
+    const raw = rawErrorString(err);
+    if (/ECONNRESET|premature close|aborted/i.test(raw)) {
+        return 'Connection dropped mid-download';
+    }
+    if (/ENOSPC/i.test(raw)) {
+        return 'Out of disk space while downloading';
+    }
+    if (/ETIMEDOUT|UND_ERR_/i.test(raw)) {
+        return 'Connection timed out mid-download';
+    }
+    return 'Download stream failed';
+}
+export function friendlyStatusError(status, statusText, _url) {
+    if (status === 404)
+        return 'Model file not found on the host (404)';
+    if (status === 401 || status === 403) {
+        return `Access denied by the model host (${status}) — gated repo or expired token?`;
+    }
+    if (status === 429)
+        return 'Model host is rate-limiting us (429) — will retry';
+    if (status === 408)
+        return 'Model host timed out (408)';
+    if (status >= 500)
+        return `Model host returned a server error (${status})`;
+    return `Download failed with HTTP ${status} ${statusText || ''}`.trim();
+}
+export function rawErrorString(err) {
+    if (err instanceof Error) {
+        const cause = err.cause;
+        const causeStr = cause instanceof Error ? ` (cause: ${cause.message})` : '';
+        return `${err.name}: ${err.message}${causeStr}`;
+    }
+    return String(err);
+}
+/** Friendly-error helpers so providers that build their own non-fetch error
+ * events can produce consistent copy. */
+export const friendlyErrors = {
+    fetch: friendlyFetchError,
+    stream: friendlyStreamError,
+    status: friendlyStatusError,
+};

package/dist/utils/download-with-retry.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared resumable-download helper used by every model installer.
+ *
+ * Before this existed, llama-cpp / mlx / sd-cpp each had their own
+ * fetch-and-stream-to-file loop with subtly different behavior:
+ *   - none of them implemented HTTP Range resumption, so a 9 GB-of-10 GB
+ *     network failure burned the whole transfer.
+ *   - error messages bubbled out as raw Node errno strings like
+ *     `getaddrinfo ENOTFOUND` or "fetch failed", which the UI then
+ *     rendered verbatim. The user sees "network error" and has no
+ *     useful action.
+ *   - no retry. One transient ECONNRESET = full restart.
+ *
+ * Shared helper:
+ *   - Resumable via `Range: bytes=N-` when the previous partial file
+ *     is present. HuggingFace CDN honors this; falls back gracefully
+ *     when the server replies with `200` instead of `206` (mid-file
+ *     restart).
+ *   - Auto-retry with exponential backoff + jitter. The budget counts
+ *     *consecutive failures that made no headway* (default 5) rather than
+ *     attempts-per-file, so a big transfer over a flaky link keeps resuming
+ *     as long as it is actually advancing. Yields `retrying` events so the UI
+ *     can surface "Retrying in 4s (attempt 3/5)…" instead of a stuck banner.
+ *   - Per-chunk idle-timeout — a stalled connection that returns no
+ *     bytes for `chunkTimeoutMs` aborts and is retried.
+ *   - Friendly error mapping for the common cases (DNS, refused,
+ *     reset, timeout). Raw errors logged at debug; the surfaced
+ *     message is user-readable.
+ *   - Honors `AbortSignal`. On abort: no retry, no `.partial` cleanup
+ *     (leave the file so a resumed run can pick up).
+ *
+ * The helper does NOT do sha256 verification, manifest writes, or
+ * post-download rename. Those stay in the per-provider installer
+ * because they have provider-specific shapes (multi-file MLX, GGUF
+ * metadata extraction for llama-cpp). The helper is purely
+ * "stream this URL to this path, resume if you can, retry if it
+ * fails, yield progress so the caller can stream events".
+ */
+import { type DownloadEvent, type DownloadResult } from './download-common.js';
+export { type DownloadEvent, type DownloadResult, friendlyErrors } from './download-common.js';
+export interface DownloadOptions {
+    url: string;
+    /** Final on-disk path. The helper writes to `${destPath}.partial`
+     * and leaves the rename to the caller (so caller can verify sha256
+     * before publishing). */
+    destPath: string;
+    /** Approximate size from the catalog manifest — used as the
+     * progress denominator when the server doesn't return
+     * Content-Length (e.g. some HF mirrors). */
+    approxSizeBytes: number;
+    /** Hard transfer ceiling. Unlike approxSizeBytes, this is enforced against
+     * Content-Length and streamed bytes and is suitable for untrusted URLs. */
+    maxBytes?: number;
+    fetchImpl?: typeof fetch;
+    /** Give up after this many CONSECUTIVE failed attempts that made no
+     * forward progress. 1 = no retry. Progressing attempts refund the budget,
+     * bounded by `MAX_TOTAL_ATTEMPTS`. */
+    maxRetries?: number;
+    /** Per-chunk idle timeout. */
+    chunkTimeoutMs?: number;
+    /** Caller cancellation. On abort: no retry, no `.partial` cleanup. */
+    signal?: AbortSignal;
+}
+/**
+ * Drive the download. Yields `progress` + `retrying` events; the
+ * async-generator's RETURN value carries the terminal outcome.
+ *
+ * Typical caller pattern:
+ *
+ *   ```ts
+ *   const gen = downloadWithRetry({ url, destPath, approxSizeBytes });
+ *   while (true) {
+ *     const next = await gen.next();
+ *     if (next.done) {
+ *       if (next.value.kind === 'ok') ... finalize, rename, sha256 check, etc.
+ *       if (next.value.kind === 'aborted') ... bail, leave .partial for resume
+ *       if (next.value.kind === 'error') ... yield to caller's SSE
+ *       break;
+ *     }
+ *     // forward progress / retrying event up the chain
+ *     yieldUpstream(next.value);
+ *   }
+ *   ```
+ */
+export declare function downloadWithRetry(opts: DownloadOptions): AsyncGenerator<DownloadEvent, DownloadResult, void>;