@juspay/neurolink 12.56.0 → 12.57.0

package/dist/utils/ollamaDiagnostics.d.ts

@@ -0,0 +1,69 @@
+import type { OllamaDiagnosticContext, OllamaDiagnosticGate, OllamaDiagnosticOutcome, OllamaDiagnosticPermit, OllamaDiagnosticSnapshot } from "../types/index.js";
+export declare const OLLAMA_DIAGNOSTIC_RESET_MS = 300000;
+/**
+ * Validate the shared failure threshold once and reuse that first-use value.
+ * Missing or invalid PROVIDER_FAILURE_THRESHOLD values use the existing default
+ * of three; ProviderHealthChecker retains its original initialization point.
+ */
+export declare function getValidatedProviderFailureThreshold(): number;
+/** Return diagnostic error text with URL secrets redacted for logs and status. */
+export declare function getOllamaDiagnosticErrorMessage(error: unknown): string;
+/**
+ * Normalize an endpoint identity without its fragment, retaining path and query.
+ * The key can contain credentials and must remain private like the source URL.
+ */
+export declare function getOllamaDiagnosticEndpointKey(url: string): string;
+/**
+ * Resolve native /api/tags at the configured Ollama origin, independently of a
+ * compatible /v1 base path. OLLAMA_BASE_URL precedes the legacy OLLAMA_API_BASE
+ * alias, then localhost; malformed URLs and non-HTTP(S) schemes are rejected.
+ */
+export declare function resolveOllamaNativeTagsUrl(): string;
+/**
+ * Capture endpoint identity and model before asynchronous diagnostic work.
+ * Later environment changes cannot retarget this context or its health-cache
+ * identity; failure accounting remains shared by endpoint rather than model.
+ */
+export declare function captureOllamaDiagnosticContext(model?: string): OllamaDiagnosticContext;
+/**
+ * Copy the current policy state after applying initialization or timed expiry.
+ * This observation issues no request and records neither failure nor recovery.
+ */
+export declare function getOllamaDiagnosticSnapshot(context: OllamaDiagnosticContext): OllamaDiagnosticSnapshot;
+/**
+ * Admit a native probe or report backoff at the current failure threshold.
+ * Timed expiry is applied before this decision. Admission captures the clear
+ * generation without reserving a request or recording an outcome; callers must
+ * record the actual outcome on completion.
+ */
+export declare function beginOllamaDiagnostic(context: OllamaDiagnosticContext): OllamaDiagnosticGate;
+/**
+ * Apply timed expiry, then an admitted outcome once to the latest endpoint state.
+ * Transport/protocol failures increment its current count; success clears a
+ * nonzero count; not-run records no outcome. Timed expiry preserves permits,
+ * including those admitted before the boundary and completed after it.
+ * Duplicate permits and permits invalidated by explicit clearing are ignored.
+ *
+ * @returns A copy of the resulting state, or undefined for an ignored permit.
+ */
+export declare function completeOllamaDiagnostic(attempt: OllamaDiagnosticPermit, outcome: OllamaDiagnosticOutcome): OllamaDiagnosticSnapshot | undefined;
+/**
+ * Clear every endpoint and advance generation, invalidating in-flight permits.
+ * Unlike timed expiry, this prevents an older completion from repopulating state.
+ */
+export declare function clearOllamaDiagnostics(): void;
+/**
+ * Separate cached health by captured endpoint and model without splitting the
+ * endpoint-wide diagnostic counter. This private key can contain URL secrets.
+ */
+export declare function getOllamaHealthCacheKey(context: OllamaDiagnosticContext): string;
+export declare class OllamaProtocolError extends Error {
+    /** Identify an answered tags response whose models envelope is malformed. */
+    constructor();
+}
+/**
+ * Require an object containing a models array, including an empty array.
+ * Individual model entries are left to existing normalization; a malformed
+ * envelope throws OllamaProtocolError rather than appearing as no models.
+ */
+export declare function readOllamaTagsModels(payload: unknown): unknown[];

package/dist/utils/ollamaDiagnostics.js

@@ -0,0 +1,192 @@
+/** Internal native-diagnostic policy; inference and provider selection are separate. */
+import { logger } from "./logger.js";
+import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
+import { redactUrlsInText } from "./logSanitize.js";
+export const OLLAMA_DIAGNOSTIC_RESET_MS = 300000;
+let validatedFailureThreshold;
+/**
+ * Validate the shared failure threshold once and reuse that first-use value.
+ * Missing or invalid PROVIDER_FAILURE_THRESHOLD values use the existing default
+ * of three; ProviderHealthChecker retains its original initialization point.
+ */
+export function getValidatedProviderFailureThreshold() {
+    if (validatedFailureThreshold !== undefined) {
+        return validatedFailureThreshold;
+    }
+    const envValue = process.env.PROVIDER_FAILURE_THRESHOLD;
+    if (!envValue) {
+        validatedFailureThreshold = 3;
+        return validatedFailureThreshold;
+    }
+    const parsed = Number(envValue);
+    if (isNaN(parsed) || parsed <= 0 || parsed > 10) {
+        logger.warn(`Invalid PROVIDER_FAILURE_THRESHOLD: ${envValue} (must be between 1 and 10), using default: 3`);
+        validatedFailureThreshold = 3;
+        return validatedFailureThreshold;
+    }
+    validatedFailureThreshold = parsed;
+    return validatedFailureThreshold;
+}
+/** Return diagnostic error text with URL secrets redacted for logs and status. */
+export function getOllamaDiagnosticErrorMessage(error) {
+    return redactUrlsInText(error instanceof Error ? error.message : String(error));
+}
+const states = new Map();
+const completed = new WeakSet();
+let clearGeneration = 0;
+/**
+ * Normalize an endpoint identity without its fragment, retaining path and query.
+ * The key can contain credentials and must remain private like the source URL.
+ */
+export function getOllamaDiagnosticEndpointKey(url) {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    return parsed.toString();
+}
+/**
+ * Resolve native /api/tags at the configured Ollama origin, independently of a
+ * compatible /v1 base path. OLLAMA_BASE_URL precedes the legacy OLLAMA_API_BASE
+ * alias, then localhost; malformed URLs and non-HTTP(S) schemes are rejected.
+ */
+export function resolveOllamaNativeTagsUrl() {
+    const base = process.env.OLLAMA_BASE_URL ||
+        process.env.OLLAMA_API_BASE ||
+        "http://localhost:11434";
+    const resolved = new URL("/api/tags", base);
+    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") {
+        throw new Error("Invalid OLLAMA_BASE_URL format (OLLAMA_API_BASE is still accepted as a legacy alias)");
+    }
+    resolved.hash = "";
+    return resolved.toString();
+}
+/**
+ * Capture endpoint identity and model before asynchronous diagnostic work.
+ * Later environment changes cannot retarget this context or its health-cache
+ * identity; failure accounting remains shared by endpoint rather than model.
+ */
+export function captureOllamaDiagnosticContext(model = process.env.OLLAMA_MODEL || DEFAULT_OLLAMA_MODEL) {
+    const url = resolveOllamaNativeTagsUrl();
+    return { url, key: getOllamaDiagnosticEndpointKey(url), model };
+}
+/**
+ * Initialize endpoint state or expire failures five minutes after the latest one.
+ * Expiry clears the count/timestamp and advances revision, retaining generation
+ * so existing in-flight permits remain valid. Only an explicit clear changes
+ * generation and invalidates those permits.
+ */
+function getState(context) {
+    let state = states.get(context.key);
+    if (!state) {
+        state = {
+            count: 0,
+            lastFailureAt: undefined,
+            revision: 0,
+            generation: clearGeneration,
+        };
+        states.set(context.key, state);
+    }
+    if (state.lastFailureAt !== undefined &&
+        Date.now() - state.lastFailureAt >= OLLAMA_DIAGNOSTIC_RESET_MS) {
+        // This is a fixed-window expiry, not an outcome from a cache hit/probe.
+        state.count = 0;
+        state.lastFailureAt = undefined;
+        state.revision++;
+    }
+    return state;
+}
+/**
+ * Copy the current policy state after applying initialization or timed expiry.
+ * This observation issues no request and records neither failure nor recovery.
+ */
+export function getOllamaDiagnosticSnapshot(context) {
+    return { ...getState(context) };
+}
+/**
+ * Admit a native probe or report backoff at the current failure threshold.
+ * Timed expiry is applied before this decision. Admission captures the clear
+ * generation without reserving a request or recording an outcome; callers must
+ * record the actual outcome on completion.
+ */
+export function beginOllamaDiagnostic(context) {
+    const state = getState(context);
+    if (state.count >= getValidatedProviderFailureThreshold()) {
+        return {
+            kind: "suppressed",
+            count: state.count,
+            reason: `Ollama native diagnostic backed off after ${state.count} consecutive transport failures`,
+            generation: state.generation,
+        };
+    }
+    return { kind: "allowed", context, generation: state.generation };
+}
+/**
+ * Apply timed expiry, then an admitted outcome once to the latest endpoint state.
+ * Transport/protocol failures increment its current count; success clears a
+ * nonzero count; not-run records no outcome. Timed expiry preserves permits,
+ * including those admitted before the boundary and completed after it.
+ * Duplicate permits and permits invalidated by explicit clearing are ignored.
+ *
+ * @returns A copy of the resulting state, or undefined for an ignored permit.
+ */
+export function completeOllamaDiagnostic(attempt, outcome) {
+    if (completed.has(attempt)) {
+        return undefined;
+    }
+    completed.add(attempt);
+    const storedState = states.get(attempt.context.key);
+    if (!storedState || storedState.generation !== attempt.generation) {
+        return undefined; // Explicit clearing invalidated this in-flight token.
+    }
+    const state = getState(attempt.context);
+    if (outcome === "transport-failure" || outcome === "protocol-failure") {
+        // Read and increment the latest completed state, never the starting count.
+        state.count++;
+        state.lastFailureAt = Date.now();
+        state.revision++;
+    }
+    else if (outcome === "success" && state.count !== 0) {
+        state.count = 0;
+        state.lastFailureAt = undefined;
+        state.revision++;
+    }
+    // Only admitted probes may reach this function. not-run cannot claim failure
+    // or recovery; genuine success while already clear retains the cache revision.
+    return { ...state };
+}
+/**
+ * Clear every endpoint and advance generation, invalidating in-flight permits.
+ * Unlike timed expiry, this prevents an older completion from repopulating state.
+ */
+export function clearOllamaDiagnostics() {
+    clearGeneration++;
+    states.clear();
+}
+/**
+ * Separate cached health by captured endpoint and model without splitting the
+ * endpoint-wide diagnostic counter. This private key can contain URL secrets.
+ */
+export function getOllamaHealthCacheKey(context) {
+    return JSON.stringify(["ollama", context.key, context.model]);
+}
+export class OllamaProtocolError extends Error {
+    /** Identify an answered tags response whose models envelope is malformed. */
+    constructor() {
+        super("Invalid models format from Ollama API");
+        this.name = "OllamaProtocolError";
+    }
+}
+/**
+ * Require an object containing a models array, including an empty array.
+ * Individual model entries are left to existing normalization; a malformed
+ * envelope throws OllamaProtocolError rather than appearing as no models.
+ */
+export function readOllamaTagsModels(payload) {
+    if (payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload) ||
+        !("models" in payload) ||
+        !Array.isArray(payload.models)) {
+        throw new OllamaProtocolError();
+    }
+    return payload.models;
+}

package/dist/utils/providerHealth.d.ts

@@ -1,7 +1,3 @@
-/**
- * Provider Health Checking System
- * Prevents 500 errors by validating provider availability and configuration
- */
 import { AIProviderName } from "../constants/enums.js";
 import type { ProviderHealthCheckOptions, ProviderHealthStatusOptions } from "../types/index.js";
 export declare class ProviderHealthChecker {
@@ -9,20 +5,16 @@ export declare class ProviderHealthChecker {
     private static readonly DEFAULT_TIMEOUT;
     private static readonly DEFAULT_CACHE_AGE;
     /**
-     * Fixed backoff window for the circuit breaker below, in milliseconds.
-     * Deliberately NOT the per-call `maxCacheAge` option: `consecutiveFailures`
-     * is a single process-wide map keyed only by provider name, shared by every
-     * caller (e.g. `checkFallbackProviderAvailability` hard-codes a 15s
-     * `maxCacheAge` for its own health-status cache). Evicting the breaker
-     * entry using whichever caller happens to read it next would let a
-     * short-TTL caller silently erase a backoff another caller is relying on
-     * — see `checkProviderHealth`. This constant governs breaker expiry alone
-     * and is intentionally independent of `maxCacheAge`/`DEFAULT_CACHE_AGE`.
+     * Fixed backoff for the existing non-Ollama provider breaker. Ollama uses
+     * the same fixed window in ollamaDiagnostics, shared by every native caller.
+     * Neither window depends on a caller's maxCacheAge: expiring a health cache
+     * must not silently erase a transport backoff owned by another caller.
      */
     private static readonly CIRCUIT_BREAKER_RESET_MS;
     private static readonly CONSECUTIVE_FAILURE_THRESHOLD;
     /**
-     * Circuit breaker state, keyed by provider.
+     * Non-Ollama circuit breaker state, keyed by provider. Ollama's separate
+     * native policy captures the actual endpoint and records aggregate outcomes.
      *
      * `count` is a count of consecutive failed CONNECTIVITY PROBES (plus the
      * rare case of the check itself throwing) — never of "the provider is
@@ -56,11 +48,14 @@ export declare class ProviderHealthChecker {
      */
     private static readonly MAX_CONCURRENT_HEALTH_CHECKS;
     /**
-     * Validate and return a safe failure threshold value
+     * Preserve the validated threshold's original first-use initialization.
      */
     private static getValidatedFailureThreshold;
     /**
-     * Comprehensive health check for a provider
+     * Check configuration and optional connectivity/model availability.
+     * Ollama captures its endpoint/model once and records only probes that run;
+     * a cache hit or missing configured model does not invent a transport failure.
+     * Its cached result must match the current diagnostic revision/generation.
      */
     static checkProviderHealth(providerName: AIProviderName, options?: ProviderHealthCheckOptions): Promise<ProviderHealthStatusOptions>;
     /**
@@ -189,18 +184,33 @@ export declare class ProviderHealthChecker {
     private static getLiteLLMModelsUrl;
     private static getConfiguredLiteLLMModel;
     private static getOllamaBaseUrl;
+    /** Resolve the shared native tags URL rather than the compatible models URL. */
     private static getOllamaTagsUrl;
     private static getConfiguredOllamaModel;
     private static fetchJsonWithTimeout;
     private static normalizeModelList;
     private static hasRequestedModel;
+    /**
+     * Fetch native tags from the captured endpoint and normalize its models.
+     * A malformed envelope rejects; a valid empty list remains an empty result.
+     */
     private static getOllamaAvailableModels;
     private static getLiteLLMAvailableModels;
+    /**
+     * Check a requested model against native tags while keeping diagnostic outcome
+     * separate from model availability. An answered valid list is diagnostic
+     * success even if that model is absent; malformed JSON/envelopes are protocol
+     * failures. A caller recording an aggregate health probe disables recording
+     * here so its admitted permit is completed only once at the outer boundary.
+     */
     private static checkOllamaAvailability;
     private static checkLiteLLMAvailability;
     private static checkLiteLLMConfig;
     /**
-     * Check Ollama configuration
+     * Report Ollama configuration and model availability using the captured context.
+     * Backoff can suppress native work; a missing installed model is a configuration
+     * issue after a successful probe. Return actual probe activity/failure for the
+     * enclosing health check to record, without completing a second policy permit.
      */
     private static checkOllamaConfig;
     /**
@@ -208,7 +218,9 @@ export declare class ProviderHealthChecker {
      */
     private static getCommonModelsForProvider;
     /**
-     * Get cached health status if still valid
+     * Return health within the caller's TTL and, for Ollama, the captured identity.
+     * Ollama revision/generation changes invalidate cached status; reading the
+     * snapshot may apply timed expiry but never records a probe outcome.
      */
     private static getCachedHealth;
     /**
@@ -267,7 +279,9 @@ export declare class ProviderHealthChecker {
      */
     static initializeBackgroundHealthChecks(): void;
     /**
-     * Clear health cache for a provider or all providers
+     * Clear cached health and failure state for one provider or every provider.
+     * Clearing Ollama removes all endpoint/model cache entries and explicitly
+     * advances diagnostic generation so older in-flight permits cannot commit.
      */
     static clearHealthCache(providerName?: AIProviderName): void;
     static checkFallbackProviderAvailability(providerName: string, model: string): Promise<{