@juspay/neurolink 9.92.3 → 9.93.0

package/dist/proxy/proxyLifecycle.js

@@ -0,0 +1,332 @@
+import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { logger } from "../utils/logger.js";
+const SCHEMA_VERSION = 1;
+const DEFAULT_QUEUE_CAPACITY = 10_000;
+const DEFAULT_BATCH_SIZE = 256;
+const DEFAULT_FLUSH_INTERVAL_MS = 25;
+const LIFECYCLE_APPEND_TIMEOUT_MS = 2_000;
+const MAX_SHORT_FIELD_LENGTH = 256;
+const SESSION_KEY_FILE = ".proxy-lifecycle-session-key";
+let loggerEnabled = false;
+let lifecycleLogDir;
+let queueCapacity = DEFAULT_QUEUE_CAPACITY;
+let batchSize = DEFAULT_BATCH_SIZE;
+let flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
+let processInstanceId = randomUUID();
+let sessionHashKey = randomBytes(32);
+let nextSequence = 1;
+let attempted = 0;
+let enqueued = 0;
+let written = 0;
+let dropped = 0;
+let queueDrops = 0;
+let invalidDrops = 0;
+let writeDrops = 0;
+let writeFailures = 0;
+let inFlight = 0;
+let queue = [];
+let flushTimer;
+let flushInFlight;
+function positiveInteger(value, fallback) {
+    return Number.isInteger(value) && (value ?? 0) > 0
+        ? value
+        : fallback;
+}
+function clip(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    return value.length <= MAX_SHORT_FIELD_LENGTH
+        ? value
+        : value.slice(0, MAX_SHORT_FIELD_LENGTH);
+}
+function finiteNonNegative(value) {
+    return value !== undefined && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+function nonNegativeInteger(value) {
+    const finite = finiteNonNegative(value);
+    return finite === undefined ? undefined : Math.floor(finite);
+}
+function formatTimestamp(timestampMs) {
+    const candidate = typeof timestampMs === "number" && Number.isFinite(timestampMs)
+        ? timestampMs
+        : Date.now();
+    const date = new Date(candidate);
+    return Number.isFinite(date.getTime())
+        ? date.toISOString()
+        : new Date().toISOString();
+}
+function readPersistedSessionHashKey(path) {
+    try {
+        const key = Buffer.from(readFileSync(path, "utf8").trim(), "base64");
+        if (key.length !== 32) {
+            throw new Error("persisted lifecycle session key must contain 32 bytes");
+        }
+        chmodSync(path, 0o600);
+        return key;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function resolveSessionHashKey(logDir) {
+    const configuredSecret = process.env.NEUROLINK_PROXY_SESSION_SECRET?.trim();
+    if (configuredSecret) {
+        return createHash("sha256").update(configuredSecret).digest();
+    }
+    const keyPath = join(logDir, SESSION_KEY_FILE);
+    const existing = readPersistedSessionHashKey(keyPath);
+    if (existing) {
+        return existing;
+    }
+    const generated = randomBytes(32);
+    try {
+        writeFileSync(keyPath, generated.toString("base64"), {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        return generated;
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            const concurrentlyCreated = readPersistedSessionHashKey(keyPath);
+            if (concurrentlyCreated) {
+                return concurrentlyCreated;
+            }
+        }
+        throw error;
+    }
+}
+export function hashProxyLifecycleSessionId(sessionId) {
+    if (!sessionId) {
+        return undefined;
+    }
+    return createHmac("sha256", sessionHashKey)
+        .update(sessionId)
+        .digest("hex")
+        .slice(0, 24);
+}
+function clearScheduledFlush() {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = undefined;
+    }
+}
+function scheduleFlush() {
+    if (flushTimer || flushInFlight || queue.length === 0) {
+        return;
+    }
+    flushTimer = setTimeout(() => {
+        flushTimer = undefined;
+        void startFlush();
+    }, flushIntervalMs);
+    flushTimer.unref?.();
+}
+async function flushBatch() {
+    if (queue.length === 0) {
+        return;
+    }
+    const batch = queue.splice(0, batchSize);
+    inFlight += batch.length;
+    try {
+        const byPath = new Map();
+        for (const item of batch) {
+            const path = join(item.logDir, `proxy-lifecycle-${item.date}.jsonl`);
+            const lines = byPath.get(path) ?? [];
+            lines.push(`${JSON.stringify(item.record)}\n`);
+            byPath.set(path, lines);
+        }
+        for (const [path, lines] of byPath) {
+            try {
+                // This best-effort telemetry sink intentionally avoids fsync so request
+                // throughput is not coupled to storage latency. Loss is surfaced by
+                // writeDrops/writeFailures rather than delaying proxy responses.
+                await withTimeout(appendFile(path, lines.join(""), { mode: 0o600 }), LIFECYCLE_APPEND_TIMEOUT_MS, "Timed out writing proxy lifecycle metadata");
+                written += lines.length;
+            }
+            catch (error) {
+                dropped += lines.length;
+                writeDrops += lines.length;
+                writeFailures += 1;
+                logger.warn("[proxy] lifecycle metadata write failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    finally {
+        inFlight = Math.max(0, inFlight - batch.length);
+    }
+}
+function startFlush() {
+    if (flushInFlight) {
+        return flushInFlight;
+    }
+    const currentFlush = flushBatch();
+    flushInFlight = currentFlush;
+    void currentFlush.then(() => {
+        if (flushInFlight === currentFlush) {
+            flushInFlight = undefined;
+        }
+        scheduleFlush();
+    }, () => {
+        if (flushInFlight === currentFlush) {
+            flushInFlight = undefined;
+        }
+        scheduleFlush();
+    });
+    return currentFlush;
+}
+export function configureProxyLifecycleLogger(options) {
+    clearScheduledFlush();
+    loggerEnabled = false;
+    lifecycleLogDir = undefined;
+    queueCapacity = positiveInteger(options.queueCapacity, DEFAULT_QUEUE_CAPACITY);
+    batchSize = positiveInteger(options.batchSize, DEFAULT_BATCH_SIZE);
+    flushIntervalMs = positiveInteger(options.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS);
+    if (options.enabled && options.logDir) {
+        try {
+            mkdirSync(options.logDir, { recursive: true, mode: 0o700 });
+            sessionHashKey = resolveSessionHashKey(options.logDir);
+            lifecycleLogDir = options.logDir;
+            loggerEnabled = true;
+        }
+        catch (error) {
+            logger.warn("[proxy] lifecycle metadata logging disabled", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // Queued records retain their enqueue-time destination. Reconfiguration is
+    // therefore atomic for new events while an in-flight or pending batch safely
+    // drains to its original directory.
+    scheduleFlush();
+}
+/** Enqueue fixed-size lifecycle metadata without awaiting filesystem work. */
+export function logProxyLifecycleEvent(input) {
+    if (!loggerEnabled || !lifecycleLogDir) {
+        return;
+    }
+    try {
+        attempted += 1;
+        const sequence = nextSequence++;
+        if (queue.length >= queueCapacity) {
+            dropped += 1;
+            queueDrops += 1;
+            return;
+        }
+        const timestamp = formatTimestamp(input.timestampMs);
+        const monotonicMs = finiteNonNegative(input.monotonicMs) ?? performance.now();
+        const toolCount = nonNegativeInteger(input.toolCount);
+        const requestBytes = nonNegativeInteger(input.requestBytes);
+        const responseStatus = nonNegativeInteger(input.responseStatus);
+        const observedBodyBytes = nonNegativeInteger(input.observedBodyBytes);
+        const responseChunks = nonNegativeInteger(input.responseChunks);
+        const elapsedMs = finiteNonNegative(input.elapsedMs);
+        const model = clip(input.model);
+        const sessionHash = clip(input.sessionHash);
+        const terminalOutcome = clip(input.terminalOutcome);
+        const errorType = clip(input.errorType);
+        const errorCode = clip(input.errorCode);
+        const record = {
+            schemaVersion: SCHEMA_VERSION,
+            timestamp,
+            monotonicMs: Number(monotonicMs.toFixed(3)),
+            processInstanceId,
+            sequence,
+            event: clip(input.event) ?? "unknown",
+            requestId: clip(input.requestId) ?? "unknown",
+            method: clip(input.method) ?? "unknown",
+            path: clip(input.path) ?? "unknown",
+            ...(model !== undefined ? { model } : {}),
+            ...(input.stream !== undefined ? { stream: input.stream } : {}),
+            ...(toolCount !== undefined ? { toolCount } : {}),
+            ...(sessionHash !== undefined ? { sessionHash } : {}),
+            ...(requestBytes !== undefined ? { requestBytes } : {}),
+            ...(responseStatus !== undefined ? { responseStatus } : {}),
+            ...(observedBodyBytes !== undefined ? { observedBodyBytes } : {}),
+            ...(responseChunks !== undefined ? { responseChunks } : {}),
+            ...(elapsedMs !== undefined
+                ? { elapsedMs: Number(elapsedMs.toFixed(3)) }
+                : {}),
+            ...(terminalOutcome !== undefined ? { terminalOutcome } : {}),
+            ...(errorType !== undefined ? { errorType } : {}),
+            ...(errorCode !== undefined ? { errorCode } : {}),
+        };
+        queue.push({
+            logDir: lifecycleLogDir,
+            date: String(record.timestamp).slice(0, 10),
+            record,
+        });
+        enqueued += 1;
+        scheduleFlush();
+    }
+    catch {
+        dropped += 1;
+        invalidDrops += 1;
+    }
+}
+export async function flushProxyLifecycleEvents() {
+    clearScheduledFlush();
+    while (queue.length > 0 || flushInFlight) {
+        if (flushInFlight) {
+            await flushInFlight;
+        }
+        else {
+            await startFlush();
+        }
+        clearScheduledFlush();
+    }
+}
+export function getProxyLifecycleLoggerSnapshot() {
+    return {
+        enabled: loggerEnabled,
+        schemaVersion: SCHEMA_VERSION,
+        processInstanceId,
+        nextSequence,
+        attempted,
+        enqueued,
+        written,
+        dropped,
+        queueDrops,
+        invalidDrops,
+        writeDrops,
+        writeFailures,
+        pending: queue.length,
+        inFlight,
+        flushing: flushInFlight !== undefined,
+    };
+}
+export function resetProxyLifecycleLoggerForTests() {
+    clearScheduledFlush();
+    loggerEnabled = false;
+    lifecycleLogDir = undefined;
+    queueCapacity = DEFAULT_QUEUE_CAPACITY;
+    batchSize = DEFAULT_BATCH_SIZE;
+    flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
+    processInstanceId = randomUUID();
+    sessionHashKey = randomBytes(32);
+    nextSequence = 1;
+    attempted = 0;
+    enqueued = 0;
+    written = 0;
+    dropped = 0;
+    queueDrops = 0;
+    invalidDrops = 0;
+    writeDrops = 0;
+    writeFailures = 0;
+    inFlight = 0;
+    queue = [];
+    flushInFlight = undefined;
+}

package/dist/proxy/requestLogger.js

@@ -15,6 +15,7 @@ import { promisify } from "util";
 import { gzip as gzipCallback } from "zlib";
 import { OtelBridge } from "../observability/otelBridge.js";
 import { SeverityNumber } from "@opentelemetry/api-logs";
+import { configureProxyLifecycleLogger } from "./proxyLifecycle.js";
 let logDir = null;
 let logEnabled = false;
 /**
@@ -45,8 +46,11 @@ const SENSITIVE_HEADER_PATTERN = /token|secret|key|password|credential/i;
 /** JSON keys whose values should be redacted in request/response bodies. */
 const SENSITIVE_BODY_KEYS = /("(?:password|access_token|refresh_token|api_key|apiKey|secret|authorization|token|credential|x-api-key)"\s*:\s*)"(?:[^"\\]|\\.)*"/gi;
 export function initRequestLogger(enabled = true, customLogsDir) {
+    // Lifecycle metadata deliberately shares the request logger's enablement,
+    // directory permissions, retention boundary, and operator privacy control.
     logEnabled = enabled;
     if (!enabled) {
+        configureProxyLifecycleLogger({ enabled: false });
         return;
     }
     try {
@@ -55,10 +59,12 @@ export function initRequestLogger(enabled = true, customLogsDir) {
             mkdirSync(logDir, { recursive: true, mode: 0o700 });
         }
         chmodSync(logDir, 0o700);
+        configureProxyLifecycleLogger({ enabled: true, logDir });
     }
     catch (err) {
         logEnabled = false;
         logDir = null;
+        configureProxyLifecycleLogger({ enabled: false });
         logger.warn(`[proxy] Request logging disabled — failed to create log directory: ${err instanceof Error ? err.message : String(err)}`);
     }
 }

package/dist/server/routes/claudeProxyRoutes.js

@@ -3062,7 +3062,10 @@ async function handleAnthropicAuthRetry(args) {
                 : String(retryFetchErr);
             authRetryError = `network error on retry ${authRetry + 1}: ${message}`;
             currentLastError = authRetryError;
-            retryLogAttempt(502, "network_error", message, { retryable: true });
+            retryLogAttempt(502, "network_error", message, {
+                retryable: isRetryableNetworkError(retryFetchErr),
+                errorCode: getErrorCode(retryFetchErr) ?? "unknown",
+            });
             logger.debug(`[proxy] ${authRetryError}`);
             break;
         }
@@ -3437,6 +3440,7 @@ function createAnthropicAttemptLogger(args) {
             responseTimeMs: Date.now() - requestStart,
             ...(errorType ? { errorType } : {}),
             ...(errorMessage ? { errorMessage } : {}),
+            ...(extra?.errorCode ? { errorCode: extra.errorCode } : {}),
             ...(extra?.inputTokens !== undefined
                 ? { inputTokens: extra.inputTokens }
                 : {}),
@@ -3651,19 +3655,27 @@ async function fetchAnthropicAccountResponse(args) {
         });
     }
     catch (fetchErr) {
-        if (!isRetryableNetworkError(fetchErr)) {
-            throw fetchErr;
-        }
+        const retryable = isRetryableNetworkError(fetchErr);
+        // Every dispatched upstream request is an attempt, including terminal
+        // transport failures. Record it once before preserving the throw behavior.
         sawNetworkError = true;
         recordAttemptError(account.label, account.type, 502);
         const errorCode = getErrorCode(fetchErr) ?? "unknown";
         const errorMessage = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
         lastError = errorMessage;
-        logger.always(`[proxy] fetch error account=${account.label} code=${errorCode} (retryable): ${errorMessage}`);
-        logAttempt(502, "network_error", errorMessage);
+        logger.always(`[proxy] fetch error account=${account.label} code=${errorCode} (${retryable ? "retryable" : "terminal"}): ${errorMessage}`);
+        logAttempt(502, "network_error", errorMessage, {
+            retryable,
+            errorCode,
+        });
         tracer?.setError("network_error", errorMessage);
-        tracer?.recordRetry(account.label, "network_error");
+        if (retryable) {
+            tracer?.recordRetry(account.label, "network_error");
+        }
         currentUpstreamSpan?.end();
+        if (!retryable) {
+            throw fetchErr;
+        }
         return {
             continueLoop: true,
             retrySameAccount: true,
@@ -4469,16 +4481,13 @@ function describeTransportError(error) {
  */
 function isRetryableNetworkError(error) {
     const code = getErrorCode(error);
-    // Check non-retryable codes FIRST — before the string-based heuristic
-    // which could false-positive on error messages containing these strings.
-    const NON_RETRYABLE_CODES = ["ENOTFOUND"];
-    if (code && NON_RETRYABLE_CODES.includes(code)) {
-        return false;
-    }
     if (code &&
         [
             "ECONNREFUSED",
             "ECONNRESET",
+            // The Anthropic host is fixed, so ENOTFOUND can be a transient resolver
+            // outage. Keep it inside the existing bounded same-account retry budget.
+            "ENOTFOUND",
             "ETIMEDOUT",
             "EHOSTUNREACH",
             "UND_ERR_CONNECT_TIMEOUT",
@@ -4490,13 +4499,9 @@ function isRetryableNetworkError(error) {
     }
     const message = error instanceof Error ? error.message : String(error);
     const normalized = message.toLowerCase();
-    // Exclude ENOTFOUND from string-based heuristic — DNS failures are permanent
-    // and rotating accounts won't help since they all hit the same host.
-    if (normalized.includes("enotfound")) {
-        return false;
-    }
     return (normalized.includes("econnrefused") ||
         normalized.includes("econnreset") ||
+        normalized.includes("enotfound") ||
         normalized.includes("etimedout") ||
         normalized.includes("timed out") ||
         normalized.includes("connection error") ||

package/dist/types/proxy.d.ts

@@ -437,6 +437,8 @@ export type RequestLogEntry = {
     responseTimeMs: number;
     errorType?: string;
     errorMessage?: string;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
@@ -461,6 +463,8 @@ export type RequestAttemptLogEntry = {
     responseTimeMs: number;
     errorType?: string;
     errorMessage?: string;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     /** Whether this failed attempt may be retried without changing the request. */
     retryable?: boolean;
     /** Distinguishes short-lived admission throttles from exhausted quota windows. */
@@ -514,6 +518,8 @@ export type AnthropicAttemptLogger = (status: number, errorType?: string, errorM
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
     retryable?: boolean;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     rateLimitKind?: "transient" | "quota";
     cooldownReason?: "transient" | "session" | "weekly" | "unified";
     /** Override used when one account selection performs an OAuth retry fetch. */
@@ -945,6 +951,80 @@ export type ProxyRuntimeActivity = {
     activeRequests: number;
     lastActivityAt: string | null;
 };
+/** Terminal state observed while the HTTP adapter relays a response body. */
+export type ProxyResponseTerminalOutcome = "completed" | "bodyless" | "client_cancelled" | "stream_error";
+/** Non-blocking callbacks for response lifecycle metadata. */
+export type ProxyResponseTrackingObserver = {
+    onFirstChunk?: (details: {
+        /** Decoded response-body bytes observed by the adapter. */
+        observedBodyBytes: number;
+        responseChunks: 1;
+    }) => void;
+    onTerminal?: (details: {
+        outcome: ProxyResponseTerminalOutcome;
+        /** Decoded response-body bytes observed by the adapter. */
+        observedBodyBytes: number;
+        responseChunks: number;
+    }) => void;
+};
+/** Versioned lifecycle event names persisted by the proxy adapter. */
+export type ProxyLifecycleEventName = "request_accepted" | "response_headers" | "response_first_chunk" | "request_terminal";
+/** Client-facing terminal classifications recorded by lifecycle metadata. */
+export type ProxyLifecycleTerminalOutcome = ProxyResponseTerminalOutcome | "handler_error";
+/** Content-free lifecycle event accepted by the bounded metadata logger. */
+export type ProxyLifecycleEventInput = {
+    event: ProxyLifecycleEventName;
+    requestId: string;
+    method: string;
+    path: string;
+    model?: string;
+    stream?: boolean;
+    toolCount?: number;
+    sessionHash?: string;
+    requestBytes?: number;
+    responseStatus?: number;
+    /** Decoded response-body bytes observed by the adapter. */
+    observedBodyBytes?: number;
+    responseChunks?: number;
+    elapsedMs?: number;
+    terminalOutcome?: ProxyLifecycleTerminalOutcome;
+    errorType?: string;
+    errorCode?: string;
+    timestampMs?: number;
+    monotonicMs?: number;
+};
+/** Data-quality counters for the bounded lifecycle metadata sink. */
+export type ProxyLifecycleLoggerSnapshot = {
+    enabled: boolean;
+    schemaVersion: number;
+    processInstanceId: string;
+    nextSequence: number;
+    attempted: number;
+    enqueued: number;
+    written: number;
+    dropped: number;
+    queueDrops: number;
+    invalidDrops: number;
+    writeDrops: number;
+    writeFailures: number;
+    pending: number;
+    inFlight: number;
+    flushing: boolean;
+};
+/** Lifecycle logger configuration. Queue overrides are used by stress tests. */
+export type ProxyLifecycleLoggerOptions = {
+    enabled: boolean;
+    logDir?: string;
+    queueCapacity?: number;
+    batchSize?: number;
+    flushIntervalMs?: number;
+};
+/** Serialized lifecycle line awaiting a bounded batch write. */
+export type QueuedProxyLifecycleEvent = {
+    logDir: string;
+    date: string;
+    record: Record<string, unknown>;
+};
 /** Request metadata retained by the HTTP adapter for terminal error logging. */
 export type RuntimeRequestMetadata = {
     requestId: string;
@@ -954,6 +1034,8 @@ export type RuntimeRequestMetadata = {
     model: string;
     stream: boolean;
     toolCount: number;
+    terminalErrorType?: string;
+    terminalErrorCode?: string;
 };
 /** Accumulated upstream body capture from a raw stream. */
 export type RawStreamCapture = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.92.3",
+  "version": "9.93.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {