@juspay/neurolink 9.42.0 → 9.43.0

package/dist/proxy/proxyFetch.js

@@ -7,6 +7,7 @@ import { logger } from "../utils/logger.js";
 import { SpanStatusCode, propagation, context } from "@opentelemetry/api";
 import { tracers } from "../telemetry/tracers.js";
 import { shouldBypassProxy } from "./utils/noProxyUtils.js";
+import { createHash } from "node:crypto";
 async function getLangfuseContext() {
     try {
         // Dynamic import to avoid hard dependency — getLangfuseContext is only
@@ -24,7 +25,17 @@ async function getLangfuseContext() {
  * - The NeuroLink proxy to link proxy spans as children of the calling SDK's trace
  * - Conversation-level session/user attribution on proxy spans
  */
-async function injectTraceContext(init) {
+function mergeTraceHeaders(input, init) {
+    const existingHeaders = new Headers(input instanceof Request ? input.headers : undefined);
+    if (init?.headers) {
+        const initHeaders = new Headers(init.headers);
+        for (const [key, value] of initHeaders.entries()) {
+            existingHeaders.set(key, value);
+        }
+    }
+    return existingHeaders;
+}
+async function injectTraceContext(input, init) {
     const carrier = {};
     propagation.inject(context.active(), carrier);
     // Also inject NeuroLink session context from Langfuse AsyncLocalStorage
@@ -41,7 +52,7 @@ async function injectTraceContext(init) {
     if (Object.keys(carrier).length === 0) {
         return init ?? {};
     }
-    const existingHeaders = new Headers(init?.headers);
+    const existingHeaders = mergeTraceHeaders(input, init);
     for (const [key, value] of Object.entries(carrier)) {
         if (!existingHeaders.has(key)) {
             existingHeaders.set(key, value);
@@ -321,6 +332,234 @@ async function createProxyAgent(proxyUrl) {
             throw new Error(`Unsupported proxy protocol: ${parsed.protocol}`);
     }
 }
+function sanitizeProxyUrl(url) {
+    return maskProxyUrl(url) ?? "NOT_SET";
+}
+function getTargetUrl(input) {
+    return typeof input === "string"
+        ? input
+        : input instanceof URL
+            ? input.href
+            : input.url;
+}
+function createDirectFetchHandler() {
+    return async (input, init) => {
+        const enrichedInit = await injectTraceContext(input, init);
+        const reqId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        const startTs = Date.now();
+        const url = getTargetUrl(input);
+        if (logger.shouldLog("debug")) {
+            const { size: bodySize, type: bodyType } = parseBody(enrichedInit?.body);
+            logger.debug("[Observability] HTTP request to LLM provider", {
+                requestId: reqId,
+                url,
+                method: enrichedInit?.method || "POST",
+                bodySize,
+                bodyType,
+            });
+        }
+        try {
+            const response = await fetchWithRetry(input, enrichedInit);
+            if (logger.shouldLog("debug")) {
+                const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
+                logger.debug("[Observability] HTTP response from LLM provider", {
+                    requestId: reqId,
+                    url,
+                    status: response.status,
+                    statusText: response.statusText,
+                    durationMs: Date.now() - startTs,
+                    contentLength: responseSize,
+                    hasContent: !!responseBody,
+                    bodyType: responseType,
+                    responseHeaders,
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            logger.debug("[Observability] HTTP request failed", {
+                requestId: reqId,
+                url,
+                error: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTs,
+            });
+            throw error;
+        }
+    };
+}
+async function executeProxiedFetch(input, init, proxyEnv) {
+    const { httpsProxy, httpProxy, allProxy, socksProxy, noProxy } = proxyEnv;
+    init = await injectTraceContext(input, init);
+    const requestId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    const requestStartTime = Date.now();
+    const targetUrl = getTargetUrl(input);
+    if (logger.shouldLog("debug")) {
+        const { size: bodySize, type: bodyType } = parseBody(init?.body);
+        logger.debug("[Observability] HTTP request to LLM provider", {
+            requestId,
+            url: targetUrl,
+            method: init?.method || "POST",
+            bodySize,
+            bodyType,
+        });
+    }
+    logger.debug(`[Proxy Fetch] ENHANCED REQUEST START`, {
+        requestId,
+        targetUrl,
+        timestamp: new Date().toISOString(),
+        httpProxy: sanitizeProxyUrl(httpProxy),
+        httpsProxy: sanitizeProxyUrl(httpsProxy),
+        allProxy: sanitizeProxyUrl(allProxy),
+        socksProxy: sanitizeProxyUrl(socksProxy),
+        noProxy: noProxy || "NOT_SET",
+        initMethod: init?.method || "GET",
+    });
+    // Clone the request before any proxy attempt so that if the proxy path
+    // consumes the body stream and then fails, the fallback still has an intact
+    // body to send.
+    const requestClone = input instanceof Request ? input.clone() : null;
+    try {
+        const proxyUrl = selectProxyUrl(targetUrl);
+        if (proxyUrl) {
+            const url = new URL(targetUrl);
+            logger.debug(`[Proxy Fetch] 🔗 ENHANCED URL ANALYSIS`, {
+                requestId,
+                targetUrl,
+                urlHostname: url.hostname,
+                urlProtocol: url.protocol,
+                urlPort: url.port,
+                selectedProxyUrl: sanitizeProxyUrl(proxyUrl),
+                timestamp: new Date().toISOString(),
+            });
+            logger.debug(`[Proxy Fetch] 🎯 ENHANCED PROXY AGENT CREATION`, {
+                requestId,
+                proxyUrl: sanitizeProxyUrl(proxyUrl),
+                targetHostname: url.hostname,
+                targetProtocol: url.protocol,
+                aboutToCreateProxyAgent: true,
+                timestamp: new Date().toISOString(),
+            });
+            const globalWithCache = globalThis;
+            if (!globalWithCache.__NL_PROXY_AGENT_CACHE__) {
+                globalWithCache.__NL_PROXY_AGENT_CACHE__ = new Map();
+            }
+            const agentCache = globalWithCache.__NL_PROXY_AGENT_CACHE__;
+            const cacheKey = createHash("sha256")
+                .update(maskProxyUrl(proxyUrl) ?? proxyUrl)
+                .digest("hex");
+            const dispatcher = agentCache.get(cacheKey) || (await createProxyAgent(proxyUrl));
+            agentCache.set(cacheKey, dispatcher);
+            logger.debug(`[Proxy Fetch] ✅ ENHANCED PROXY AGENT CREATED`, {
+                requestId,
+                hasDispatcher: !!dispatcher,
+                dispatcherType: typeof dispatcher,
+                dispatcherConstructor: dispatcher?.constructor?.name || "unknown",
+                timestamp: new Date().toISOString(),
+            });
+            let fetchInput;
+            let fetchInit = { ...init };
+            if (input instanceof Request) {
+                fetchInput = input.url;
+                fetchInit = {
+                    method: input.method,
+                    headers: input.headers,
+                    body: input.body,
+                    ...init,
+                };
+            }
+            else {
+                fetchInput = input;
+            }
+            const undici = await import("undici");
+            const response = await undici.fetch(fetchInput, {
+                ...fetchInit,
+                dispatcher,
+            });
+            if (logger.shouldLog("debug")) {
+                const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
+                logger.debug("[Observability] HTTP response from LLM provider", {
+                    requestId,
+                    url: targetUrl,
+                    status: response?.status,
+                    statusText: response?.statusText,
+                    durationMs: Date.now() - requestStartTime,
+                    contentLength: responseSize,
+                    hasContent: !!responseBody,
+                    bodyType: responseType,
+                    proxied: true,
+                    responseHeaders,
+                });
+            }
+            logger.debug(`[Proxy Fetch] ENHANCED PROXY SUCCESS`, {
+                requestId,
+                responseStatus: response?.status,
+                responseOk: response?.ok,
+                proxyUsed: true,
+                timestamp: new Date().toISOString(),
+            });
+            return response;
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.debug("[Observability] HTTP request failed", {
+            requestId,
+            url: targetUrl,
+            error: errorMessage,
+            durationMs: Date.now() - requestStartTime,
+        });
+        logger.debug(`[Proxy Fetch] ENHANCED ERROR ANALYSIS`, {
+            requestId,
+            error: errorMessage,
+            errorType: error instanceof Error ? error.constructor.name : typeof error,
+            willFallback: true,
+            timestamp: new Date().toISOString(),
+        });
+        logger.warn(`[Proxy Fetch] Enhanced proxy failed (${errorMessage}), falling back to direct connection`);
+    }
+    logger.debug(`[Proxy Fetch] ENHANCED FALLBACK TO STANDARD FETCH`, {
+        requestId,
+        fallbackReason: "No proxy configured or proxy failed",
+        timestamp: new Date().toISOString(),
+    });
+    // Use the cloned request for the fallback so that the body stream is not
+    // already consumed from the proxy attempt above.
+    const fallbackInput = (input instanceof Request ? (requestClone ?? input) : input);
+    try {
+        const response = await fetchWithRetry(fallbackInput, init);
+        if (logger.shouldLog("debug")) {
+            const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
+            logger.debug("[Observability] HTTP response from LLM provider", {
+                requestId,
+                url: targetUrl,
+                status: response.status,
+                statusText: response.statusText,
+                durationMs: Date.now() - requestStartTime,
+                contentLength: responseSize,
+                hasContent: !!responseBody,
+                bodyType: responseType,
+                proxied: false,
+                responseHeaders,
+            });
+        }
+        return response;
+    }
+    catch (fallbackError) {
+        const fallbackMessage = fallbackError instanceof Error
+            ? fallbackError.message
+            : String(fallbackError);
+        logger.debug("[Observability] HTTP request failed", {
+            requestId,
+            url: targetUrl,
+            error: fallbackMessage,
+            durationMs: Date.now() - requestStartTime,
+        });
+        throw fallbackError;
+    }
+}
+function createProxiedFetchHandler(proxyEnv) {
+    return async (input, init) => executeProxiedFetch(input, init, proxyEnv);
+}
 // ==================== ENHANCED PROXY FETCH FUNCTION ====================
 /**
  * Create a proxy-aware fetch function with enhanced capabilities
@@ -333,9 +572,14 @@ export function createProxyFetch() {
     const allProxy = process.env.ALL_PROXY || process.env.all_proxy;
     const socksProxy = process.env.SOCKS_PROXY || process.env.socks_proxy;
     const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+    const proxyEnv = {
+        httpsProxy,
+        httpProxy,
+        allProxy,
+        socksProxy,
+        noProxy,
+    };
     // ENHANCED LOGGING: Capture ALL proxy-related environment variables — credentials redacted
-    // Reuse module-level maskProxyUrl, defaulting to "NOT_SET" for undefined values
-    const sanitizeProxyUrl = (url) => maskProxyUrl(url) ?? "NOT_SET";
     if (logger.shouldLog("debug")) {
         const allProxyRelatedEnvVars = Object.keys(process.env)
             .filter((key) => key.toLowerCase().includes("proxy"))
@@ -358,54 +602,7 @@ export function createProxyFetch() {
     // If no proxy configured, return instrumented standard fetch
     if (!httpsProxy && !httpProxy && !allProxy && !socksProxy) {
         logger.debug("[Proxy Fetch] No proxy environment variables found - using standard fetch");
-        return async (input, init) => {
-            // Inject OTel traceparent so the proxy can link to this trace
-            const enrichedInit = await injectTraceContext(init);
-            const reqId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
-            const startTs = Date.now();
-            const url = typeof input === "string"
-                ? input
-                : input instanceof URL
-                    ? input.href
-                    : input.url;
-            if (logger.shouldLog("debug")) {
-                const { size: bodySize, type: bodyType } = parseBody(enrichedInit?.body);
-                logger.debug("[Observability] HTTP request to LLM provider", {
-                    requestId: reqId,
-                    url,
-                    method: enrichedInit?.method || "POST",
-                    bodySize,
-                    bodyType,
-                });
-            }
-            try {
-                const response = await fetchWithRetry(input, enrichedInit);
-                if (logger.shouldLog("debug")) {
-                    const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
-                    logger.debug("[Observability] HTTP response from LLM provider", {
-                        requestId: reqId,
-                        url,
-                        status: response.status,
-                        statusText: response.statusText,
-                        durationMs: Date.now() - startTs,
-                        contentLength: responseSize,
-                        hasContent: !!responseBody,
-                        bodyType: responseType,
-                        responseHeaders,
-                    });
-                }
-                return response;
-            }
-            catch (error) {
-                logger.debug("[Observability] HTTP request failed", {
-                    requestId: reqId,
-                    url,
-                    error: error instanceof Error ? error.message : String(error),
-                    durationMs: Date.now() - startTs,
-                });
-                throw error;
-            }
-        };
+        return createDirectFetchHandler();
     }
     logger.debug(`[Proxy Fetch] Configuring enhanced proxy with multiple protocol support`);
     logger.debug(`[Proxy Fetch] HTTP_PROXY: ${sanitizeProxyUrl(httpProxy)}`);
@@ -413,176 +610,7 @@ export function createProxyFetch() {
     logger.debug(`[Proxy Fetch] ALL_PROXY: ${sanitizeProxyUrl(allProxy)}`);
     logger.debug(`[Proxy Fetch] SOCKS_PROXY: ${sanitizeProxyUrl(socksProxy)}`);
     logger.debug(`[Proxy Fetch] NO_PROXY: ${noProxy || "not set"}`);
-    // Return enhanced proxy-aware fetch function
-    return async (input, init) => {
-        // Inject OTel traceparent so the proxy can link to this trace
-        init = await injectTraceContext(init);
-        const requestId = `req-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
-        const requestStartTime = Date.now();
-        // Determine target URL
-        const targetUrl = typeof input === "string"
-            ? input
-            : input instanceof URL
-                ? input.href
-                : input.url;
-        // Request logging with sensitive header redaction — gated behind debug check
-        if (logger.shouldLog("debug")) {
-            const { size: bodySize, type: bodyType } = parseBody(init?.body);
-            logger.debug("[Observability] HTTP request to LLM provider", {
-                requestId,
-                url: targetUrl,
-                method: init?.method || "POST",
-                bodySize,
-                bodyType,
-            });
-        }
-        logger.debug(`[Proxy Fetch] ENHANCED REQUEST START`, {
-            requestId,
-            targetUrl,
-            timestamp: new Date().toISOString(),
-            httpProxy: sanitizeProxyUrl(httpProxy),
-            httpsProxy: sanitizeProxyUrl(httpsProxy),
-            allProxy: sanitizeProxyUrl(allProxy),
-            socksProxy: sanitizeProxyUrl(socksProxy),
-            initMethod: init?.method || "GET",
-        });
-        try {
-            // Enhanced proxy selection with NO_PROXY bypass and multiple protocols
-            const proxyUrl = selectProxyUrl(targetUrl);
-            if (proxyUrl) {
-                const url = new URL(targetUrl);
-                const sanitizedProxy = sanitizeProxyUrl(proxyUrl);
-                logger.debug(`[Proxy Fetch] 🔗 ENHANCED URL ANALYSIS`, {
-                    requestId,
-                    targetUrl,
-                    urlHostname: url.hostname,
-                    urlProtocol: url.protocol,
-                    urlPort: url.port,
-                    selectedProxyUrl: sanitizedProxy,
-                    timestamp: new Date().toISOString(),
-                });
-                logger.debug(`[Proxy Fetch] 🎯 ENHANCED PROXY AGENT CREATION`, {
-                    requestId,
-                    proxyUrl: sanitizedProxy,
-                    targetHostname: url.hostname,
-                    targetProtocol: url.protocol,
-                    aboutToCreateProxyAgent: true,
-                    timestamp: new Date().toISOString(),
-                });
-                // Create/reuse proxy agent (HTTP/HTTPS/SOCKS)
-                const agentCache = globalThis.__NL_PROXY_AGENT_CACHE__ ??
-                    (globalThis.__NL_PROXY_AGENT_CACHE__ = new Map());
-                const cacheKey = maskProxyUrl(proxyUrl) ?? proxyUrl; // mask credentials in cache key
-                const dispatcher = agentCache.get(cacheKey) || (await createProxyAgent(proxyUrl));
-                agentCache.set(cacheKey, dispatcher);
-                logger.debug(`[Proxy Fetch] ✅ ENHANCED PROXY AGENT CREATED`, {
-                    requestId,
-                    hasDispatcher: !!dispatcher,
-                    dispatcherType: typeof dispatcher,
-                    dispatcherConstructor: dispatcher?.constructor?.name || "unknown",
-                    timestamp: new Date().toISOString(),
-                });
-                // Handle Request objects by extracting URL and merging properties
-                let fetchInput;
-                let fetchInit = { ...init };
-                if (input instanceof Request) {
-                    fetchInput = input.url;
-                    fetchInit = {
-                        method: input.method,
-                        headers: input.headers,
-                        body: input.body,
-                        ...init, // Allow init to override Request properties
-                    };
-                }
-                else {
-                    fetchInput = input;
-                }
-                // Use undici fetch with enhanced dispatcher (supports HTTP/HTTPS/SOCKS)
-                const undici = await import("undici");
-                const response = await undici.fetch(fetchInput, {
-                    ...fetchInit,
-                    dispatcher: dispatcher,
-                });
-                if (logger.shouldLog("debug")) {
-                    const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
-                    logger.debug("[Observability] HTTP response from LLM provider", {
-                        requestId,
-                        url: targetUrl,
-                        status: response?.status,
-                        statusText: response?.statusText,
-                        durationMs: Date.now() - requestStartTime,
-                        contentLength: responseSize,
-                        hasContent: !!responseBody,
-                        bodyType: responseType,
-                        proxied: true,
-                        responseHeaders,
-                    });
-                }
-                logger.debug(`[Proxy Fetch] ENHANCED PROXY SUCCESS`, {
-                    requestId,
-                    responseStatus: response?.status,
-                    responseOk: response?.ok,
-                    proxyUsed: true,
-                    timestamp: new Date().toISOString(),
-                });
-                return response;
-            }
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.debug("[Observability] HTTP request failed", {
-                requestId,
-                url: targetUrl,
-                error: errorMessage,
-                durationMs: Date.now() - requestStartTime,
-            });
-            logger.debug(`[Proxy Fetch] ENHANCED ERROR ANALYSIS`, {
-                requestId,
-                error: errorMessage,
-                errorType: error instanceof Error ? error.constructor.name : typeof error,
-                willFallback: true,
-                timestamp: new Date().toISOString(),
-            });
-            logger.warn(`[Proxy Fetch] Enhanced proxy failed (${errorMessage}), falling back to direct connection`);
-        }
-        // Fallback to standard fetch
-        logger.debug(`[Proxy Fetch] ENHANCED FALLBACK TO STANDARD FETCH`, {
-            requestId,
-            fallbackReason: "No proxy configured or proxy failed",
-            timestamp: new Date().toISOString(),
-        });
-        try {
-            const response = await fetchWithRetry(input, init);
-            if (logger.shouldLog("debug")) {
-                const { parsed: responseBody, size: responseSize, type: responseType, headers: responseHeaders, } = await readResponseBody(response);
-                logger.debug("[Observability] HTTP response from LLM provider", {
-                    requestId,
-                    url: targetUrl,
-                    status: response.status,
-                    statusText: response.statusText,
-                    durationMs: Date.now() - requestStartTime,
-                    contentLength: responseSize,
-                    hasContent: !!responseBody,
-                    bodyType: responseType,
-                    proxied: false,
-                    responseHeaders,
-                });
-            }
-            return response;
-        }
-        catch (fallbackError) {
-            const fallbackMessage = fallbackError instanceof Error
-                ? fallbackError.message
-                : String(fallbackError);
-            logger.debug("[Observability] HTTP request failed", {
-                requestId,
-                url: targetUrl,
-                error: fallbackMessage,
-                durationMs: Date.now() - requestStartTime,
-            });
-            throw fallbackError;
-        }
-    };
+    return createProxiedFetchHandler(proxyEnv);
 }
 /**
  * Mask credentials in a proxy URL for safe logging/reporting.

package/dist/proxy/proxyHealth.d.ts

@@ -0,0 +1,17 @@
+import type { ProxyHealthResponse, ProxyReadinessState } from "../types/index.js";
+export type { ProxyHealthResponse, ProxyReadinessState };
+export declare function createProxyReadinessState(startTimeMs?: number): ProxyReadinessState;
+export declare function markProxyReady(state: ProxyReadinessState, readyAtMs?: number): void;
+export declare function buildProxyHealthResponse(state: ProxyReadinessState, options: {
+    strategy: string;
+    passthrough: boolean;
+    version: string;
+    now?: number;
+}): ProxyHealthResponse;
+export declare function waitForProxyReadiness(args: {
+    host: string;
+    port: number;
+    timeoutMs?: number;
+    intervalMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<void>;

package/dist/proxy/proxyHealth.js

@@ -0,0 +1,54 @@
+export function createProxyReadinessState(startTimeMs = Date.now()) {
+    return {
+        startTimeMs,
+        acceptingConnections: false,
+        ready: false,
+    };
+}
+export function markProxyReady(state, readyAtMs = Date.now()) {
+    state.acceptingConnections = true;
+    state.ready = true;
+    state.readyAtMs = readyAtMs;
+}
+export function buildProxyHealthResponse(state, options) {
+    const now = options.now ?? Date.now();
+    return {
+        status: state.ready ? "ok" : "starting",
+        ready: state.ready,
+        acceptingConnections: state.acceptingConnections,
+        strategy: options.strategy,
+        passthrough: options.passthrough,
+        version: options.version,
+        startedAt: new Date(state.startTimeMs).toISOString(),
+        readyAt: state.readyAtMs ? new Date(state.readyAtMs).toISOString() : null,
+        uptime: Math.max(0, (now - state.startTimeMs) / 1000),
+        healthPath: "/health",
+        statusPath: "/status",
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function waitForProxyReadiness(args) {
+    const timeoutMs = args.timeoutMs ?? 5_000;
+    const intervalMs = args.intervalMs ?? 100;
+    const fetchImpl = args.fetchImpl ?? fetch;
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetchImpl(`http://${args.host}:${args.port}/health`, {
+                signal: AbortSignal.timeout(Math.min(intervalMs * 4, 1_000)),
+            });
+            if (response.ok) {
+                return;
+            }
+            lastError = `health endpoint returned ${response.status}`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await sleep(intervalMs);
+    }
+    throw new Error(`Proxy failed readiness check on http://${args.host}:${args.port}/health within ${timeoutMs}ms${lastError ? ` (${lastError})` : ""}`);
+}