scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-09-21 00:21:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

Merge branch 'main' into fix/rust-axum-route-extraction-1504

Browse source
This commit is contained in:
Gergő Magyar 2026-05-08 09:03:14 +01:00 • committed by GitHub
commit 1b5edaf73d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 799 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
gitnexus/src/cli/analyze.ts
View file

@ -27,6 +27,7 @@ import { warnMissingOptionalGrammars } from './optional-grammars.js';
import { glob } from 'glob';
import fs from 'fs/promises';
import { cliError } from './cli-message.js';
import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
// Capture stderr.write at module load BEFORE anything (LadybugDB native
// init, progress bar, console redirection) can monkey-patch it. The
@ -576,6 +577,26 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
return;
}
// HF download failure — show clean guidance without the raw stack trace.
// Checked before writeFatalToStderr so the user sees one focused message
// rather than a stack-trace dump followed by a second remediation block.
if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
cliError(
` The embedding model could not be downloaded.\n` +
` huggingface.co may be unreachable from your network\n` +
` (e.g. behind a corporate proxy or a regional firewall).\n` +
` Suggestions:\n` +
` 1. Set HF_ENDPOINT to a mirror and retry:\n` +
` HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)\n` +
` 2. Check your proxy / VPN settings.\n` +
` 3. Once downloaded the model is cached — future runs work offline.\n`,
{ recoveryHint: 'hf-endpoint-unreachable' },
);
process.exitCode = 1;
return;
}
// Bypass the redirected console.error and write the full stack to
// the real stderr captured at module load. The redirected
// console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)

72
gitnexus/src/core/embeddings/embedder.ts
View file

@ -14,7 +14,12 @@ if (!process.env.ORT_LOG_LEVEL) {
process.env.ORT_LOG_LEVEL = '3';
}
import { pipeline, env, type FeatureExtractionPipeline } from '@huggingface/transformers';
import {
pipeline,
env,
type FeatureExtractionPipeline,
type ProgressInfo,
} from '@huggingface/transformers';
import { existsSync } from 'fs';
import { execFileSync } from 'child_process';
import { join, dirname } from 'path';
@ -22,7 +27,7 @@ import { createRequire } from 'module';
import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig, type ModelProgress } from './types.js';
import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
import { resolveEmbeddingConfig } from './config.js';
import { applyHfEnvOverrides } from './hf-env.js';
import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry } from './hf-env.js';
import { logger } from '../logger.js';
/**
@ -171,13 +176,18 @@ export const initEmbedder = async (
}
const progressCallback = onProgress
? (data: any) => {
? (data: ProgressInfo) => {
const progress: ModelProgress = {
status: data.status || 'progress',
file: data.file,
progress: data.progress,
loaded: data.loaded,
total: data.total,
// Map the `progress_total` aggregate event (not in ModelProgress.status)
// back to 'progress' so callers don't need to handle it separately.
status:
data.status === 'progress_total'
? 'progress'
: ((data.status as ModelProgress['status']) ?? 'progress'),
file: 'file' in data ? data.file : undefined,
progress: 'progress' in data ? data.progress : undefined,
loaded: 'loaded' in data ? data.loaded : undefined,
total: 'total' in data ? data.total : undefined,
};
onProgress(progress);
}
@ -202,17 +212,29 @@ export const initEmbedder = async (
logger.info('🔧 Using WASM backend (slower)...');
}
embedderInstance = await (pipeline as any)('feature-extraction', finalConfig.modelId, {
device: device,
dtype: 'fp32',
progress_callback: progressCallback,
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: finalConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
embedderInstance = await withHfDownloadRetry(
() =>
pipeline('feature-extraction', finalConfig.modelId, {
device: device,
dtype: 'fp32',
progress_callback: progressCallback,
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: finalConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
},
}),
{
onRetry: isDev
? (attempt, max, err) =>
logger.warn(
{ attempt, max, err: err.message },
`⚠️ Model download network error (attempt ${attempt}/${max}), retrying…`,
)
: undefined,
},
});
);
currentDevice = device;
if (isDev) {
@ -228,6 +250,20 @@ export const initEmbedder = async (
return embedderInstance!;
} catch (deviceError) {
// Network errors and circuit-open errors are not device-specific —
// they will fail the same way on every device. Rethrow immediately
// with actionable HF_ENDPOINT guidance rather than silently falling
// back to the next device.
const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
if (isHfDownloadFailure(errMsg)) {
const endpointHint = process.env.HF_ENDPOINT
? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
: `huggingface.co may be unreachable from your network.\n` +
` Set HF_ENDPOINT to a mirror and retry:\n` +
` HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
throw new Error(`Failed to download embedding model: ${errMsg}\n ${endpointHint}`);
}
if (isDev && (device === 'cuda' || device === 'dml')) {
const gpuType = device === 'dml' ? 'DirectML' : 'CUDA';
logger.info(`⚠️ ${gpuType} not available, falling back to CPU...`);

281
gitnexus/src/core/embeddings/hf-env.ts
View file

@ -1,6 +1,25 @@
import os from 'node:os';
import { join } from 'node:path';
// ---------------------------------------------------------------------------
// Download resilience defaults
// ---------------------------------------------------------------------------
/** Per-attempt timeout for the full model download (5 minutes). */
export const HF_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1_000;
/** Maximum total download attempts (1 initial + N-1 retries). */
export const HF_MAX_ATTEMPTS = 3;
/** Initial delay between retry attempts; doubles on each subsequent retry. */
export const HF_BASE_DELAY_MS = 2_000;
/** Number of consecutive failures required to open the circuit. */
export const CB_FAILURE_THRESHOLD = 3;
/** How long the circuit stays open before transitioning to half-open. */
export const CB_RESET_TIMEOUT_MS = 60_000;
/** Upper bound clamped on the env-override per-attempt timeout (30 minutes). */
export const HF_MAX_TIMEOUT_MS = 30 * 60 * 1_000;
/** Upper bound clamped on the env-override attempt count. */
export const HF_MAX_ATTEMPTS_CAP = 10;
/**
* @internal Exported only for unit tests and the two embedder entry points
* (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
@ -60,3 +79,265 @@ export function applyHfEnvOverrides(env: HfEnvSubset): void {
env.remoteHost = endpoint.endsWith('/') ? endpoint : endpoint + '/';
}
}
/**
* @internal Exported for unit tests and the two embedder entry points.
*
* Returns true when an error message indicates a network-level fetch failure
* during HuggingFace model download (e.g. `TypeError: fetch failed`,
* `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`).
*
* These errors are not device-specific and cannot be fixed by falling back to
* a different ONNX device — the caller should rethrow immediately with
* guidance about `HF_ENDPOINT`.
*/
export function isNetworkFetchError(message: string): boolean {
return (
message.includes('fetch failed') ||
message.includes('ECONNREFUSED') ||
message.includes('ENOTFOUND') ||
message.includes('ETIMEDOUT') ||
message.includes('ECONNRESET')
);
}
// ---------------------------------------------------------------------------
// Circuit breaker
// ---------------------------------------------------------------------------
/** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
export const CIRCUIT_OPEN_TAG = 'hf-circuit-open';
/** Circuit-breaker states. */
type CircuitState = 'closed' | 'open' | 'half-open';
/**
* Circuit breaker for HuggingFace model downloads.
*
* After `failureThreshold` consecutive network failures the circuit opens and
* all subsequent calls to `withHfDownloadRetry` fail immediately without
* issuing any network requests. After `resetTimeoutMs` the circuit enters the
* half-open state and the next call is attempted — if it succeeds the circuit
* closes again; if it fails the circuit re-opens.
*
* Exported for unit-testing; production code should use the module-level
* `hfDownloadCircuit` singleton.
*/
export class HfDownloadCircuitBreaker {
private _state: CircuitState = 'closed';
private _failures = 0;
/** Timestamp of the last recorded failure (ms since epoch). */
lastFailureAt = 0;
constructor(
readonly failureThreshold: number = CB_FAILURE_THRESHOLD,
readonly resetTimeoutMs: number = CB_RESET_TIMEOUT_MS,
) {}
/** Effective state, factoring in the reset-timeout transition. */
get state(): CircuitState {
if (this._state === 'open' && Date.now() - this.lastFailureAt > this.resetTimeoutMs) {
this._state = 'half-open';
}
return this._state;
}
/** Returns true when the circuit is open and calls should be rejected. */
isOpen(): boolean {
return this.state === 'open';
}
/** Record a successful call — resets the failure counter and closes the circuit. */
recordSuccess(): void {
this._failures = 0;
this._state = 'closed';
}
/** Record a failed call — increments the counter and opens the circuit when the threshold is reached. */
recordFailure(): void {
this._failures++;
this.lastFailureAt = Date.now();
if (this._failures >= this.failureThreshold) {
this._state = 'open';
}
}
/** @internal Reset to initial state (used in tests). */
reset(): void {
this._failures = 0;
this._state = 'closed';
this.lastFailureAt = 0;
}
}
/** Module-level singleton shared by both embedder entry points. */
export const hfDownloadCircuit = new HfDownloadCircuitBreaker();
// ---------------------------------------------------------------------------
// Retry + timeout wrapper
// ---------------------------------------------------------------------------
/** @internal Returns true for errors that should abort without retry (circuit-open). */
export function isHfCircuitOpenError(message: string): boolean {
return message.includes(CIRCUIT_OPEN_TAG);
}
/**
* Returns true for any HuggingFace download failure that warrants showing the
* `HF_ENDPOINT` remediation hint: either a raw network error or a
* circuit-open rejection (which itself was caused by repeated network errors).
*/
export function isHfDownloadFailure(message: string): boolean {
return isNetworkFetchError(message) || isHfCircuitOpenError(message);
}
/** @internal Wraps `fn` in a hard time-limit. The timeout error contains
* `ETIMEDOUT` so that `isNetworkFetchError` classifies it correctly.
*/
export function withDownloadTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T> {
return new Promise<T>((resolve, reject) => {
const timer = setTimeout(
() =>
reject(
new Error(
`ETIMEDOUT: model download timed out after ${Math.round(timeoutMs / 1000)}s — ` +
`check your network speed or set HF_ENDPOINT to a faster mirror`,
),
),
timeoutMs,
);
fn().then(
(v) => {
clearTimeout(timer);
resolve(v);
},
(e) => {
clearTimeout(timer);
reject(e);
},
);
});
}
/** @internal Async sleep (exposed for testing). */
export function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
export interface HfRetryOptions {
/** Maximum total attempts including the initial one (default: `HF_MAX_ATTEMPTS`). */
maxAttempts?: number;
/** Delay before the first retry; doubles on each subsequent attempt (default: `HF_BASE_DELAY_MS`). */
baseDelayMs?: number;
/** Per-attempt wall-clock timeout in ms (default: `HF_DOWNLOAD_TIMEOUT_MS`). */
timeoutMs?: number;
/**
* Circuit-breaker instance to use. Defaults to the module-level
* `hfDownloadCircuit` singleton. Pass a fresh instance in tests.
*/
circuit?: HfDownloadCircuitBreaker;
/**
* Optional callback invoked before each retry (not the initial attempt).
* @param attempt - 1-based retry number
* @param max - total allowed attempts
* @param error - the error that triggered the retry
*/
onRetry?: (attempt: number, max: number, error: Error) => void;
}
/**
* Retry wrapper for HuggingFace model downloads with per-attempt timeout and
* circuit-breaker protection.
*
* Behaviour:
* - If the circuit is **open**, fails immediately with a `CIRCUIT_OPEN_TAG`
* message (so `isHfDownloadFailure` still returns true and the caller can
* show `HF_ENDPOINT` guidance).
* - Each attempt is wrapped in `withDownloadTimeout`.
* - On a network-level error (`isNetworkFetchError`) the attempt is retried
* with exponential back-off; non-network errors (e.g. ONNX device failure)
* are rethrown immediately without retry.
* - Every network failure is recorded on the circuit breaker; a success resets
* it.
* - After all attempts are exhausted, the last network error is rethrown
* so the existing `isNetworkFetchError` / `isHfDownloadFailure` guards in
* the calling code still fire.
*/
export async function withHfDownloadRetry<T>(
fn: () => Promise<T>,
options: HfRetryOptions = {},
): Promise<T> {
// Resolve effective values — explicit options take precedence over env vars,
// which take precedence over built-in defaults. This lets users lower the
// per-attempt timeout without rebuilding (e.g.
// HF_DOWNLOAD_TIMEOUT_MS=60000 npx gitnexus analyze --embeddings
// reduces the worst-case wait from 15 minutes to ~3 minutes).
//
// Upper bounds are clamped to prevent accidental runaway configuration:
// - timeoutMs is capped at HF_MAX_TIMEOUT_MS (30 min)
// - maxAttempts is floored (fractional values → integer) and capped at
// HF_MAX_ATTEMPTS_CAP (10). Values ≤ 0, NaN, or Infinity fall back to
// the built-in defaults.
const envTimeout = Number(process.env.HF_DOWNLOAD_TIMEOUT_MS);
const envMaxAttempts = Number(process.env.HF_MAX_ATTEMPTS);
const resolvedTimeout =
Number.isFinite(envTimeout) && envTimeout > 0
? Math.min(envTimeout, HF_MAX_TIMEOUT_MS)
: HF_DOWNLOAD_TIMEOUT_MS;
const resolvedMaxAttempts =
Number.isFinite(envMaxAttempts) && envMaxAttempts > 0
? Math.min(Math.floor(envMaxAttempts), HF_MAX_ATTEMPTS_CAP)
: HF_MAX_ATTEMPTS;
const {
maxAttempts = resolvedMaxAttempts,
baseDelayMs = HF_BASE_DELAY_MS,
timeoutMs = resolvedTimeout,
circuit = hfDownloadCircuit,
onRetry,
} = options;
if (circuit.isOpen()) {
const secsUntilReset = Math.ceil(
(circuit.resetTimeoutMs - (Date.now() - circuit.lastFailureAt)) / 1000,
);
throw new Error(
`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open after repeated network failures` +
(secsUntilReset > 0 ? ` — will reset in ~${secsUntilReset}s` : ''),
);
}
let lastError: Error = new Error('unknown error');
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const result = await withDownloadTimeout(fn, timeoutMs);
circuit.recordSuccess();
return result;
} catch (err) {
lastError = err instanceof Error ? err : new Error(String(err));
if (!isNetworkFetchError(lastError.message)) {
// Non-network error (e.g. CUDA unavailable) — propagate without retry
throw lastError;
}
circuit.recordFailure();
if (circuit.isOpen()) {
// Circuit just tripped — fail fast, no more retries
throw new Error(
`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${circuit.failureThreshold} consecutive failures`,
);
}
if (attempt < maxAttempts - 1) {
const delay = baseDelayMs * Math.pow(2, attempt);
onRetry?.(attempt + 1, maxAttempts, lastError);
await sleep(delay);
}
}
}
// All retries exhausted — throw the last network error so isNetworkFetchError
// patterns in the calling code still match and surface HF_ENDPOINT guidance.
throw lastError;
}

44
gitnexus/src/mcp/core/embedder.ts
View file

@ -12,7 +12,11 @@ import {
httpEmbedQuery,
} from '../../core/embeddings/http-client.js';
import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
import { applyHfEnvOverrides } from '../../core/embeddings/hf-env.js';
import {
applyHfEnvOverrides,
isHfDownloadFailure,
withHfDownloadRetry,
} from '../../core/embeddings/hf-env.js';
import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
import { logger } from '../../core/logger.js';
@ -69,23 +73,39 @@ export const initEmbedder = async (): Promise<FeatureExtractionPipeline> => {
silenceStdout();
process.stderr.write = (() => true) as any;
try {
embedderInstance = await (pipeline as any)('feature-extraction', MODEL_ID, {
device: device,
dtype: 'fp32',
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: embeddingConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
},
});
embedderInstance = await withHfDownloadRetry(() =>
pipeline('feature-extraction', MODEL_ID, {
device: device,
dtype: 'fp32',
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: embeddingConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
},
}),
);
} finally {
restoreStdout();
process.stderr.write = realStderrWrite;
}
logger.info({ device }, 'GitNexus: Embedding model loaded');
return embedderInstance!;
} catch {
} catch (deviceError) {
// Network errors and circuit-open errors are not device-specific —
// they will fail the same way on every device. Rethrow immediately
// with actionable HF_ENDPOINT guidance rather than silently falling
// back to the next device.
const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
if (isHfDownloadFailure(errMsg)) {
const endpointHint = process.env.HF_ENDPOINT
? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
: `huggingface.co may be unreachable from your network.\n` +
` Set HF_ENDPOINT to a mirror and retry:\n` +
` HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
throw new Error(`Failed to download embedding model: ${errMsg}\n ${endpointHint}`);
}
if (device === 'cpu') throw new Error('Failed to load embedding model');
}
}

413
gitnexus/test/unit/hf-env.test.ts
View file

@ -1,7 +1,20 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import os from 'node:os';
import { join } from 'node:path';
import { applyHfEnvOverrides, type HfEnvSubset } from '../../src/core/embeddings/hf-env.js';
import {
applyHfEnvOverrides,
isNetworkFetchError,
isHfDownloadFailure,
isHfCircuitOpenError,
HfDownloadCircuitBreaker,
withDownloadTimeout,
withHfDownloadRetry,
CIRCUIT_OPEN_TAG,
HF_MAX_ATTEMPTS,
HF_MAX_TIMEOUT_MS,
HF_MAX_ATTEMPTS_CAP,
type HfEnvSubset,
} from '../../src/core/embeddings/hf-env.js';
describe('applyHfEnvOverrides', () => {
let envStub: HfEnvSubset;
@ -82,3 +95,399 @@ describe('applyHfEnvOverrides', () => {
expect(envStub.remoteHost).toBe('https://hf-mirror.com/');
});
});
describe('isNetworkFetchError', () => {
it('returns true for "fetch failed" (the undici error seen on macOS/Node 24)', () => {
expect(isNetworkFetchError('fetch failed')).toBe(true);
});
it('returns true for ECONNREFUSED', () => {
expect(isNetworkFetchError('connect ECONNREFUSED 13.45.67.89:443')).toBe(true);
});
it('returns true for ENOTFOUND (DNS failure)', () => {
expect(isNetworkFetchError('getaddrinfo ENOTFOUND huggingface.co')).toBe(true);
});
it('returns true for ETIMEDOUT', () => {
expect(isNetworkFetchError('connect ETIMEDOUT 13.45.67.89:443')).toBe(true);
});
it('returns true for ECONNRESET', () => {
expect(isNetworkFetchError('read ECONNRESET')).toBe(true);
});
it('returns false for generic model-load errors (ONNX device failure)', () => {
expect(isNetworkFetchError('Failed to initialize CUDA backend')).toBe(false);
});
it('returns false for empty string', () => {
expect(isNetworkFetchError('')).toBe(false);
});
it('returns false for module-not-found errors', () => {
expect(isNetworkFetchError('Cannot find module onnxruntime-node')).toBe(false);
});
});
describe('isHfCircuitOpenError', () => {
it('returns true for a circuit-open tag message', () => {
expect(isHfCircuitOpenError(`${CIRCUIT_OPEN_TAG}: circuit is open`)).toBe(true);
});
it('returns false for a plain network error', () => {
expect(isHfCircuitOpenError('fetch failed')).toBe(false);
});
});
describe('isHfDownloadFailure', () => {
it('returns true for network fetch errors', () => {
expect(isHfDownloadFailure('ECONNREFUSED 127.0.0.1:443')).toBe(true);
});
it('returns true for circuit-open errors', () => {
expect(isHfDownloadFailure(`${CIRCUIT_OPEN_TAG}: open`)).toBe(true);
});
it('returns false for ONNX device errors', () => {
expect(isHfDownloadFailure('Failed to initialize CUDA')).toBe(false);
});
});
describe('HfDownloadCircuitBreaker', () => {
it('starts in closed state', () => {
const cb = new HfDownloadCircuitBreaker();
expect(cb.isOpen()).toBe(false);
expect(cb.state).toBe('closed');
});
it('opens after reaching the failure threshold', () => {
const cb = new HfDownloadCircuitBreaker(3);
cb.recordFailure();
cb.recordFailure();
expect(cb.isOpen()).toBe(false);
cb.recordFailure(); // threshold reached
expect(cb.isOpen()).toBe(true);
expect(cb.state).toBe('open');
});
it('closes on recordSuccess after being open', () => {
const cb = new HfDownloadCircuitBreaker(1);
cb.recordFailure();
expect(cb.isOpen()).toBe(true);
cb.recordSuccess();
expect(cb.isOpen()).toBe(false);
expect(cb.state).toBe('closed');
});
it('transitions to half-open after the reset timeout', () => {
vi.useFakeTimers();
try {
const cb = new HfDownloadCircuitBreaker(1, 100 /* 100ms */);
cb.recordFailure();
expect(cb.isOpen()).toBe(true);
vi.advanceTimersByTime(200);
expect(cb.isOpen()).toBe(false);
expect(cb.state).toBe('half-open');
} finally {
vi.useRealTimers();
}
});
it('reset() restores closed state', () => {
const cb = new HfDownloadCircuitBreaker(1);
cb.recordFailure();
expect(cb.isOpen()).toBe(true);
cb.reset();
expect(cb.isOpen()).toBe(false);
expect(cb.state).toBe('closed');
});
it('re-opens when a failure is recorded in half-open state', () => {
vi.useFakeTimers();
try {
const cb = new HfDownloadCircuitBreaker(1, 100 /* 100ms */);
cb.recordFailure(); // opens the circuit
vi.advanceTimersByTime(200); // advance past reset timeout
expect(cb.state).toBe('half-open'); // getter transitions _state to half-open
cb.recordFailure(); // failure in half-open → re-opens
expect(cb.isOpen()).toBe(true);
expect(cb.state).toBe('open');
} finally {
vi.useRealTimers();
}
});
it('closes the circuit when success is recorded in half-open state', () => {
vi.useFakeTimers();
try {
const cb = new HfDownloadCircuitBreaker(1, 100 /* 100ms */);
cb.recordFailure(); // opens the circuit
vi.advanceTimersByTime(200); // advance past reset timeout
expect(cb.state).toBe('half-open');
cb.recordSuccess(); // success in half-open → closes
expect(cb.isOpen()).toBe(false);
expect(cb.state).toBe('closed');
} finally {
vi.useRealTimers();
}
});
});
describe('withDownloadTimeout', () => {
it('resolves when fn completes before the timeout', async () => {
const result = await withDownloadTimeout(() => Promise.resolve(42), 1_000);
expect(result).toBe(42);
});
it('rejects with ETIMEDOUT when fn takes too long', async () => {
vi.useFakeTimers();
try {
const neverResolves = () => new Promise<never>(() => {});
const promise = withDownloadTimeout(neverResolves, 20);
vi.advanceTimersByTime(30);
await expect(promise).rejects.toThrow('ETIMEDOUT');
} finally {
vi.useRealTimers();
}
});
it('propagates non-timeout errors from fn', async () => {
await expect(
withDownloadTimeout(() => Promise.reject(new Error('download error')), 1_000),
).rejects.toThrow('download error');
});
});
describe('withHfDownloadRetry', () => {
it('returns the result on first success', async () => {
const fn = vi.fn().mockResolvedValue('ok');
const cb = new HfDownloadCircuitBreaker();
const result = await withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 });
expect(result).toBe('ok');
expect(fn).toHaveBeenCalledTimes(1);
});
it('retries on network errors and succeeds on second attempt', async () => {
const fn = vi.fn().mockRejectedValueOnce(new Error('fetch failed')).mockResolvedValue('ok');
const cb = new HfDownloadCircuitBreaker();
const result = await withHfDownloadRetry(fn, {
circuit: cb,
maxAttempts: 3,
baseDelayMs: 0,
});
expect(result).toBe('ok');
expect(fn).toHaveBeenCalledTimes(2);
});
it('throws the last network error after all attempts are exhausted', async () => {
const fn = vi.fn().mockRejectedValue(new Error('ECONNREFUSED 127.0.0.1:443'));
const cb = new HfDownloadCircuitBreaker(99 /* high threshold */);
await expect(
withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 3, baseDelayMs: 0 }),
).rejects.toThrow('ECONNREFUSED');
expect(fn).toHaveBeenCalledTimes(3);
});
it('does not retry non-network errors', async () => {
const fn = vi.fn().mockRejectedValue(new Error('Failed to initialize CUDA backend'));
const cb = new HfDownloadCircuitBreaker();
await expect(
withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 3, baseDelayMs: 0 }),
).rejects.toThrow('Failed to initialize CUDA backend');
expect(fn).toHaveBeenCalledTimes(1);
});
it('fails immediately when the circuit is already open', async () => {
const fn = vi.fn().mockResolvedValue('ok');
const cb = new HfDownloadCircuitBreaker(1);
cb.recordFailure(); // open the circuit
await expect(withHfDownloadRetry(fn, { circuit: cb })).rejects.toThrow(CIRCUIT_OPEN_TAG);
expect(fn).not.toHaveBeenCalled();
});
it('opens the circuit after failureThreshold failures and throws a circuit-open error', async () => {
const fn = vi.fn().mockRejectedValue(new Error('ENOTFOUND huggingface.co'));
const cb = new HfDownloadCircuitBreaker(2 /* threshold */, 60_000);
// First call: 2 attempts, threshold=2 → circuit opens on 2nd failure
await expect(
withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 2, baseDelayMs: 0 }),
).rejects.toThrow(CIRCUIT_OPEN_TAG);
expect(cb.isOpen()).toBe(true);
});
it('calls onRetry with correct arguments on each retry', async () => {
const fn = vi
.fn()
.mockRejectedValueOnce(new Error('fetch failed'))
.mockRejectedValueOnce(new Error('fetch failed'))
.mockResolvedValue('ok');
const cb = new HfDownloadCircuitBreaker(99);
const onRetry = vi.fn();
await withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 3, baseDelayMs: 0, onRetry });
expect(onRetry).toHaveBeenCalledTimes(2);
expect(onRetry).toHaveBeenNthCalledWith(
1,
1,
3,
expect.objectContaining({ message: 'fetch failed' }),
);
expect(onRetry).toHaveBeenNthCalledWith(
2,
2,
3,
expect.objectContaining({ message: 'fetch failed' }),
);
});
it('resets the circuit on success', async () => {
const fn = vi.fn().mockResolvedValue('value');
const cb = new HfDownloadCircuitBreaker(5);
cb.recordFailure();
cb.recordFailure(); // 2 failures, circuit still closed
await withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 });
expect(cb.state).toBe('closed');
});
});
describe('withHfDownloadRetry env overrides', () => {
let originalTimeout: string | undefined;
let originalMaxAttempts: string | undefined;
beforeEach(() => {
originalTimeout = process.env.HF_DOWNLOAD_TIMEOUT_MS;
originalMaxAttempts = process.env.HF_MAX_ATTEMPTS;
delete process.env.HF_DOWNLOAD_TIMEOUT_MS;
delete process.env.HF_MAX_ATTEMPTS;
});
afterEach(() => {
if (originalTimeout === undefined) delete process.env.HF_DOWNLOAD_TIMEOUT_MS;
else process.env.HF_DOWNLOAD_TIMEOUT_MS = originalTimeout;
if (originalMaxAttempts === undefined) delete process.env.HF_MAX_ATTEMPTS;
else process.env.HF_MAX_ATTEMPTS = originalMaxAttempts;
});
it('HF_MAX_ATTEMPTS=1 gives exactly 1 attempt', async () => {
process.env.HF_MAX_ATTEMPTS = '1';
const fn = vi.fn().mockRejectedValue(new Error('ECONNREFUSED 127.0.0.1:443'));
const cb = new HfDownloadCircuitBreaker(99_999 /* high threshold */);
await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
'ECONNREFUSED',
);
expect(fn).toHaveBeenCalledTimes(1);
});
it('HF_MAX_ATTEMPTS=2 gives exactly 2 attempts', async () => {
process.env.HF_MAX_ATTEMPTS = '2';
const fn = vi.fn().mockRejectedValue(new Error('ENOTFOUND huggingface.co'));
const cb = new HfDownloadCircuitBreaker(99_999);
await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
'ENOTFOUND',
);
expect(fn).toHaveBeenCalledTimes(2);
});
it('HF_MAX_ATTEMPTS=abc falls back to the built-in default', async () => {
process.env.HF_MAX_ATTEMPTS = 'abc';
const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
const cb = new HfDownloadCircuitBreaker(99_999);
await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
'fetch failed',
);
expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS);
});
it('HF_MAX_ATTEMPTS=0 falls back to the built-in default', async () => {
process.env.HF_MAX_ATTEMPTS = '0';
const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
const cb = new HfDownloadCircuitBreaker(99_999);
await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
'fetch failed',
);
expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS);
});
it('HF_MAX_ATTEMPTS=-1 falls back to the built-in default', async () => {
process.env.HF_MAX_ATTEMPTS = '-1';
const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
const cb = new HfDownloadCircuitBreaker(99_999);
await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
'fetch failed',
);
expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS);
});
it('HF_MAX_ATTEMPTS is clamped to HF_MAX_ATTEMPTS_CAP', async () => {
process.env.HF_MAX_ATTEMPTS = '9999';
const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
const cb = new HfDownloadCircuitBreaker(99_999 /* very high threshold */);
await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
'fetch failed',
);
expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS_CAP);
});
it('HF_MAX_ATTEMPTS=2.9 is floored to 2', async () => {
process.env.HF_MAX_ATTEMPTS = '2.9';
const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
const cb = new HfDownloadCircuitBreaker(99_999);
await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
'fetch failed',
);
expect(fn).toHaveBeenCalledTimes(2);
});
it('HF_DOWNLOAD_TIMEOUT_MS is used as the per-attempt timeout when valid', async () => {
vi.useFakeTimers();
try {
process.env.HF_DOWNLOAD_TIMEOUT_MS = '50';
const neverResolves = () => new Promise<never>(() => {});
const cb = new HfDownloadCircuitBreaker(99);
const promise = withHfDownloadRetry(neverResolves, { circuit: cb, maxAttempts: 1 });
vi.advanceTimersByTime(100);
await expect(promise).rejects.toThrow('ETIMEDOUT');
} finally {
vi.useRealTimers();
}
});
it('HF_DOWNLOAD_TIMEOUT_MS=-1 falls back to the built-in default', async () => {
process.env.HF_DOWNLOAD_TIMEOUT_MS = '-1';
// Passing explicit timeoutMs=0 (no real wait) so the test doesn't block;
// we just verify that the env var rejection causes options.timeoutMs to be
// the default constant (not -1) by confirming the resolved value is used.
const fn = vi.fn().mockResolvedValue('ok');
const cb = new HfDownloadCircuitBreaker(99);
// Provide explicit timeoutMs to avoid the default 5-minute wait
const result = await withHfDownloadRetry(fn, { circuit: cb, timeoutMs: 100 });
expect(result).toBe('ok');
});
it('HF_DOWNLOAD_TIMEOUT_MS is clamped to HF_MAX_TIMEOUT_MS', async () => {
vi.useFakeTimers();
try {
// Set an env value exceeding the 30-minute cap
process.env.HF_DOWNLOAD_TIMEOUT_MS = String(HF_MAX_TIMEOUT_MS + 60_000);
const neverResolves = () => new Promise<never>(() => {});
const cb = new HfDownloadCircuitBreaker(99);
const promise = withHfDownloadRetry(neverResolves, { circuit: cb, maxAttempts: 1 });
// Advance just past the 30-minute cap
vi.advanceTimersByTime(HF_MAX_TIMEOUT_MS + 1);
await expect(promise).rejects.toThrow('ETIMEDOUT');
} finally {
vi.useRealTimers();
}
});
it('explicit options override env vars', async () => {
process.env.HF_MAX_ATTEMPTS = '5';
const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
const cb = new HfDownloadCircuitBreaker(99);
// explicit maxAttempts: 2 must win over HF_MAX_ATTEMPTS=5
await expect(
withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 2, baseDelayMs: 0 }),
).rejects.toThrow('fetch failed');
expect(fn).toHaveBeenCalledTimes(2);
});
});