@juspay/neurolink 12.17.1 → 12.17.3

package/dist/proxy/otlpLogTransport.js

@@ -0,0 +1,334 @@
+/**
+ * OTLP/HTTP JSON transport with response-aware acknowledgement. The SDK's HTTP
+ * exporter reports SUCCESS even for partialSuccess or malformed responses, so
+ * its callback cannot establish that every record in our batch was accepted.
+ * Serialization stays with the official OpenTelemetry implementation.
+ */
+import { readFileSync } from "node:fs";
+import { Agent as HttpAgent, request as httpRequest, validateHeaderName, validateHeaderValue, } from "node:http";
+import { Agent as HttpsAgent, request as httpsRequest } from "node:https";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import { gzip } from "node:zlib";
+import { ExportResultCode, parseKeyPairsIntoRecord } from "@opentelemetry/core";
+import { JsonLogsSerializer } from "@opentelemetry/otlp-transformer";
+const gzipAsync = promisify(gzip);
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const MAX_EXPORT_ATTEMPTS = 5;
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+const RETRYABLE_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EPIPE",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "ENOTFOUND",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+]);
+class ProxyOtlpResponseError extends Error {
+    retryable;
+    retryAfterMs;
+    constructor(message, retryable = false, retryAfterMs) {
+        super(message);
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "ProxyOtlpResponseError";
+    }
+}
+function signalSetting(suffix) {
+    return (process.env[`OTEL_EXPORTER_OTLP_LOGS_${suffix}`]?.trim() ||
+        process.env[`OTEL_EXPORTER_OTLP_${suffix}`]?.trim() ||
+        undefined);
+}
+function certificate(suffix) {
+    const path = signalSetting(suffix);
+    if (!path) {
+        return undefined;
+    }
+    try {
+        return readFileSync(path);
+    }
+    catch {
+        // File paths, headers, backend bodies and native TLS errors can contain
+        // credentials. Export diagnostics intentionally expose only fixed reasons.
+        throw new Error(`Proxy OTLP ${suffix} file could not be read`);
+    }
+}
+function retryAfter(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (/^\d+$/.test(value.trim())) {
+        return Number(value) * 1000;
+    }
+    const at = Date.parse(value);
+    return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined;
+}
+function validateAcknowledgement(bytes) {
+    let payload;
+    try {
+        payload = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        // Empty JSON is not a serialized ExportLogsServiceResponse. Its valid
+        // empty message is {}, unlike the zero-byte protobuf representation.
+        throw new ProxyOtlpResponseError("OTLP response JSON is empty or malformed");
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new ProxyOtlpResponseError("OTLP response must be a JSON object");
+    }
+    if (Object.keys(payload).some((key) => key !== "partialSuccess" && key !== "partial_success")) {
+        throw new ProxyOtlpResponseError("OTLP response has unexpected fields");
+    }
+    if ("partialSuccess" in payload && "partial_success" in payload) {
+        throw new ProxyOtlpResponseError("OTLP response has ambiguous field aliases");
+    }
+    const partial = "partialSuccess" in payload
+        ? payload.partialSuccess
+        : "partial_success" in payload
+            ? payload.partial_success
+            : undefined;
+    if (partial === null || partial === undefined) {
+        return;
+    }
+    if (typeof partial !== "object" || Array.isArray(partial)) {
+        throw new ProxyOtlpResponseError("OTLP partial success response is malformed");
+    }
+    const allowedFields = new Set([
+        "rejectedLogRecords",
+        "rejected_log_records",
+        "errorMessage",
+        "error_message",
+    ]);
+    if (Object.keys(partial).some((key) => !allowedFields.has(key))) {
+        throw new ProxyOtlpResponseError("OTLP partial success response has unexpected fields");
+    }
+    if (("rejectedLogRecords" in partial && "rejected_log_records" in partial) ||
+        ("errorMessage" in partial && "error_message" in partial)) {
+        throw new ProxyOtlpResponseError("OTLP partial success has ambiguous field aliases");
+    }
+    const message = "errorMessage" in partial
+        ? partial.errorMessage
+        : "error_message" in partial
+            ? partial.error_message
+            : undefined;
+    if (message !== null &&
+        message !== undefined &&
+        typeof message !== "string") {
+        throw new ProxyOtlpResponseError("OTLP partial success response is malformed");
+    }
+    const rejected = "rejectedLogRecords" in partial
+        ? partial.rejectedLogRecords
+        : "rejected_log_records" in partial
+            ? partial.rejected_log_records
+            : 0;
+    // ProtoJSON accepts integer strings or numbers; null is the absent default.
+    if (rejected === null || rejected === 0 || rejected === "0") {
+        return;
+    }
+    const integer = typeof rejected === "string" && /^\d+$/.test(rejected)
+        ? BigInt(rejected)
+        : typeof rejected === "number" &&
+            Number.isSafeInteger(rejected) &&
+            rejected >= 0
+            ? BigInt(rejected)
+            : undefined;
+    if (integer === undefined || integer > 9223372036854775807n) {
+        throw new ProxyOtlpResponseError("OTLP rejected record count is malformed");
+    }
+    if (integer > 0n) {
+        // We cannot identify the rejected subset. Mark the entire batch uncertain;
+        // replaying a known partial response would duplicate its accepted subset.
+        throw new ProxyOtlpResponseError("OTLP partial success rejected log records");
+    }
+}
+/** Both proxy queues use this transport; success is not backend persistence. */
+export function createProxyOtlpLogTransport(endpoint, timeoutMillis) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error("Proxy OTLP endpoint is invalid");
+    }
+    if (!new Set(["http:", "https:"]).has(url.protocol)) {
+        throw new Error("Proxy OTLP endpoint must use HTTP or HTTPS");
+    }
+    if (url.username || url.password) {
+        throw new Error("Proxy OTLP endpoint credentials must use OTLP headers");
+    }
+    const compression = signalSetting("COMPRESSION") ?? "none";
+    if (compression !== "none" && compression !== "gzip") {
+        throw new Error("Proxy OTLP compression must be none or gzip");
+    }
+    const headers = {};
+    try {
+        for (const raw of [
+            process.env.OTEL_EXPORTER_OTLP_HEADERS,
+            process.env.OTEL_EXPORTER_OTLP_LOGS_HEADERS,
+        ]) {
+            for (const [key, value] of Object.entries(parseKeyPairsIntoRecord(raw))) {
+                validateHeaderName(key);
+                validateHeaderValue(key, value);
+                headers[key.toLowerCase()] = value;
+            }
+        }
+    }
+    catch {
+        throw new Error("Proxy OTLP headers are invalid");
+    }
+    // These describe the serialized wire payload, irrespective of user headers.
+    headers["content-type"] = "application/json";
+    headers["accept"] = "application/json";
+    headers["accept-encoding"] = "identity";
+    delete headers["content-encoding"];
+    if (compression === "gzip") {
+        headers["content-encoding"] = "gzip";
+    }
+    const tls = {
+        ca: certificate("CERTIFICATE"),
+        cert: certificate("CLIENT_CERTIFICATE"),
+        key: certificate("CLIENT_KEY"),
+    };
+    if (Boolean(tls.cert) !== Boolean(tls.key)) {
+        throw new Error("Proxy OTLP client certificate and key must be set together");
+    }
+    const agent = url.protocol === "https:"
+        ? new HttpsAgent({ keepAlive: true, maxSockets: 30, ...tls })
+        : new HttpAgent({ keepAlive: true, maxSockets: 30 });
+    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
+    let closed = false;
+    const active = new Set();
+    const sendOnce = (data, signal) => new Promise((resolve, reject) => {
+        let receivedResponse = false;
+        const req = request(url, {
+            method: "POST",
+            agent,
+            signal,
+            headers: { ...headers, "content-length": String(data.byteLength) },
+        }, (response) => {
+            receivedResponse = true;
+            const status = response.statusCode ?? 0;
+            const fail = (error) => {
+                reject(error);
+                response.destroy();
+            };
+            // An HTTP status, a partial response or a broken success response must
+            // never be mistaken for an acknowledgement of individual log records.
+            if (status !== 200) {
+                fail(new ProxyOtlpResponseError(`OTLP HTTP ${status}`, RETRYABLE_STATUSES.has(status), retryAfter(response.headers["retry-after"])));
+                return;
+            }
+            const encoding = response.headers["content-encoding"];
+            if (encoding && encoding !== "identity") {
+                fail(new ProxyOtlpResponseError("OTLP response encoding is unsupported"));
+                return;
+            }
+            const contentType = response.headers["content-type"];
+            if (contentType &&
+                contentType.split(";", 1)[0].trim().toLowerCase() !==
+                    "application/json") {
+                fail(new ProxyOtlpResponseError("OTLP response content type is not JSON"));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > MAX_RESPONSE_BYTES) {
+                    fail(new ProxyOtlpResponseError("OTLP response exceeds 64 KiB limit"));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on("aborted", () => reject(new ProxyOtlpResponseError("OTLP success response was interrupted")));
+            response.on("error", () => reject(new ProxyOtlpResponseError("OTLP success response could not be read")));
+            response.on("end", () => {
+                try {
+                    validateAcknowledgement(Buffer.concat(chunks));
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        req.on("error", (error) => reject(new ProxyOtlpResponseError(signal.aborted
+            ? "OTLP export deadline exceeded"
+            : "OTLP transport failed", !signal.aborted &&
+            !receivedResponse &&
+            RETRYABLE_NETWORK_CODES.has(error.code ?? ""))));
+        req.end(data);
+    });
+    const send = async (records) => {
+        const controller = new AbortController();
+        const deadlineAt = Date.now() + timeoutMillis;
+        const deadline = setTimeout(() => controller.abort(), timeoutMillis);
+        deadline.unref();
+        try {
+            const serialized = JsonLogsSerializer.serializeRequest(records);
+            if (!serialized) {
+                throw new ProxyOtlpResponseError("OTLP serialization produced no payload");
+            }
+            // Serialize and compress once, so ambiguous retries retain byte-for-byte
+            // event identities and payloads for query-side deduplication.
+            const bytes = compression === "gzip" ? await gzipAsync(serialized) : serialized;
+            let attempt = 0;
+            while (!controller.signal.aborted && Date.now() < deadlineAt) {
+                attempt++;
+                try {
+                    await sendOnce(bytes, controller.signal);
+                    return;
+                }
+                catch (error) {
+                    if (!(error instanceof ProxyOtlpResponseError) || !error.retryable) {
+                        throw error;
+                    }
+                    if (attempt >= MAX_EXPORT_ATTEMPTS) {
+                        throw new ProxyOtlpResponseError("OTLP retry attempt limit reached");
+                    }
+                    const exponential = Math.min(5000, 1000 * 2 ** Math.min(attempt - 1, 3));
+                    // Retry-After is a lower bound, never permission to hammer a busy
+                    // collector. Even Retry-After: 0 retains exponential backoff+jitter.
+                    const wait = Math.max(error.retryAfterMs ?? 0, exponential * (0.8 + Math.random() * 0.4));
+                    if (wait >= deadlineAt - Date.now()) {
+                        throw new ProxyOtlpResponseError("OTLP retry exceeds export deadline");
+                    }
+                    await delay(wait, undefined, { signal: controller.signal });
+                }
+            }
+            throw new ProxyOtlpResponseError("OTLP export deadline exceeded");
+        }
+        catch (error) {
+            if (error instanceof ProxyOtlpResponseError) {
+                throw error;
+            }
+            throw new ProxyOtlpResponseError(controller.signal.aborted
+                ? "OTLP export deadline exceeded"
+                : "OTLP export failed");
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    };
+    return {
+        export(records, callback) {
+            if (closed) {
+                callback({
+                    code: ExportResultCode.FAILED,
+                    error: new Error("OTLP transport is shut down"),
+                });
+                return;
+            }
+            const operation = send(records).then(() => callback({ code: ExportResultCode.SUCCESS }), (error) => callback({ code: ExportResultCode.FAILED, error }));
+            active.add(operation);
+            void operation.finally(() => active.delete(operation)).catch(() => { });
+        },
+        async shutdown() {
+            closed = true;
+            await Promise.allSettled(active);
+            agent.destroy();
+        },
+    };
+}

package/dist/proxy/proxyActivity.d.ts

@@ -1,7 +1,27 @@
 import type { ProxyActivitySnapshot, ProxyResponseTrackingObserver, RequestLogEntry, RequestAttemptLogEntry } from "../types/index.js";
+export declare function getProxyBridgeResult(requestId: string): RequestLogEntry | undefined;
+export declare function registerInternalProxyRequest(parentRequestId: string): {
+    token: `${string}-${string}-${string}-${string}-${string}`;
+    requestId: `${string}-${string}-${string}-${string}-${string}`;
+    dispose(): void;
+};
+export declare function consumeInternalProxyRequest(token: string | null): {
+    parentRequestId: string;
+    requestId: string;
+} | undefined;
+export declare function getProxyRequestAccounting(requestId: string): {
+    parentRequestId?: string;
+    accountingScope?: "client" | "internal";
+    usageOwnerRequestId?: string;
+} | undefined;
+export declare function releaseProxyRequestAccounting(requestId: string): void;
+/** Deferred native callbacks retain this owner even after transport cleanup. */
+export declare function withProxyFinalLogOwnership<T>(requestId: string, run: () => T): T;
 /** Join route accounting to the HTTP lifecycle without relying on write order. */
 export declare function observeProxyFinalLog(requestId: string, observer: (entry: RequestLogEntry) => void, attemptObserver?: (entry: RequestAttemptLogEntry) => void): () => void;
-export declare function notifyProxyFinalLog(entry: RequestLogEntry): void;
+/** Check without claiming: aggregate accounting must not revive a cancelled request. */
+export declare function isProxyRequestFinalized(requestId: string): boolean;
+export declare function notifyProxyFinalLog(entry: RequestLogEntry): boolean;
 /** Retain only the last attempt for a currently observed HTTP request. */
 export declare function notifyProxyAttemptLog(entry: RequestAttemptLogEntry): void;
 export declare function registerProxyResponseObserver(metadata: object, observer: ProxyResponseTrackingObserver): void;
@@ -11,5 +31,5 @@ export declare function beginProxyRequest(): () => void;
 export declare function getProxyActivitySnapshot(): ProxyActivitySnapshot;
 export declare function isProxyActivityQuiet(snapshot: ProxyActivitySnapshot, quietThresholdMs: number, nowMs?: number): boolean;
 /** Keep activity open until the response body completes, errors, or is cancelled. */
-export declare function trackProxyResponse(response: Response, finishRequest: () => void, observer?: ProxyResponseTrackingObserver): Response;
+export declare function trackProxyResponse(response: Response, finishRequest: () => void, observer?: ProxyResponseTrackingObserver, abortSignal?: AbortSignal): Response;
 export declare function resetProxyActivityForTests(): void;

package/dist/proxy/proxyActivity.js

@@ -1,6 +1,68 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { withTimeout } from "../utils/async/withTimeout.js";
 import { logger } from "../utils/logger.js";
 const PROXY_RESPONSE_CANCEL_TIMEOUT_MS = 1_000;
+// Bridge identity is registered by this process, never trusted from an inbound
+// parent-id header. One-use capabilities expire even if loopback dispatch fails.
+const internalRequests = new Map();
+const bridgeResults = new Map();
+export function getProxyBridgeResult(requestId) {
+    return bridgeResults.get(requestId);
+}
+const requestAccounting = new Map();
+export function registerInternalProxyRequest(parentRequestId) {
+    if (internalRequests.size >= 5000) {
+        throw Object.assign(new Error("Internal proxy dispatch capacity is full"), {
+            status: 503,
+            code: "PROXY_INTERNAL_CAPACITY",
+            retryable: false,
+        });
+    }
+    const token = crypto.randomUUID();
+    const requestId = crypto.randomUUID();
+    internalRequests.set(token, { parentRequestId, requestId });
+    requestAccounting.set(parentRequestId, {
+        accountingScope: "client",
+        usageOwnerRequestId: requestId,
+    });
+    const timer = setTimeout(() => {
+        if (internalRequests.delete(token)) {
+            requestAccounting.delete(parentRequestId);
+            bridgeResults.delete(parentRequestId);
+        }
+    }, 300_000);
+    timer.unref?.();
+    return {
+        token,
+        requestId,
+        dispose() {
+            clearTimeout(timer);
+            internalRequests.delete(token);
+        },
+    };
+}
+export function consumeInternalProxyRequest(token) {
+    if (!token) {
+        return undefined;
+    }
+    const result = internalRequests.get(token);
+    internalRequests.delete(token);
+    if (result) {
+        requestAccounting.set(result.requestId, {
+            parentRequestId: result.parentRequestId,
+            accountingScope: "internal",
+            usageOwnerRequestId: result.requestId,
+        });
+    }
+    return result;
+}
+export function getProxyRequestAccounting(requestId) {
+    return requestAccounting.get(requestId);
+}
+export function releaseProxyRequestAccounting(requestId) {
+    requestAccounting.delete(requestId);
+    bridgeResults.delete(requestId);
+}
 let activeRequests = 0;
 let lastActivityAtMs = null;
 // Route handlers can attach terminal observers to their request context without
@@ -8,11 +70,19 @@ let lastActivityAtMs = null;
 // response through one tracker, which fans these observers out at the point
 // where bytes actually leave the proxy.
 const responseObserversByMetadata = new WeakMap();
+const finalOwnership = new Map();
+const finalOwnershipContext = new AsyncLocalStorage();
+/** Deferred native callbacks retain this owner even after transport cleanup. */
+export function withProxyFinalLogOwnership(requestId, run) {
+    const owner = finalOwnership.get(requestId);
+    return owner ? finalOwnershipContext.run(owner, run) : run();
+}
 const finalLogObservers = new Map();
 const attemptLogObservers = new Map();
 /** Join route accounting to the HTTP lifecycle without relying on write order. */
 export function observeProxyFinalLog(requestId, observer, attemptObserver) {
     finalLogObservers.set(requestId, observer);
+    finalOwnership.set(requestId, { requestId, finalized: false });
     if (attemptObserver) {
         attemptLogObservers.set(requestId, attemptObserver);
     }
@@ -22,12 +92,35 @@ export function observeProxyFinalLog(requestId, observer, attemptObserver) {
     return () => {
         if (finalLogObservers.get(requestId) === observer) {
             finalLogObservers.delete(requestId);
+            finalOwnership.delete(requestId);
             attemptLogObservers.delete(requestId);
         }
     };
 }
+/** Check without claiming: aggregate accounting must not revive a cancelled request. */
+export function isProxyRequestFinalized(requestId) {
+    const contextual = finalOwnershipContext.getStore();
+    return ((contextual?.requestId === requestId
+        ? contextual
+        : finalOwnership.get(requestId))?.finalized ?? false);
+}
 export function notifyProxyFinalLog(entry) {
+    const contextual = finalOwnershipContext.getStore();
+    const owner = contextual?.requestId === entry.requestId
+        ? contextual
+        : finalOwnership.get(entry.requestId);
+    if (owner) {
+        if (owner.finalized) {
+            return false;
+        }
+        owner.finalized = true;
+    }
+    const parent = requestAccounting.get(entry.requestId)?.parentRequestId;
+    if (parent && requestAccounting.has(parent)) {
+        bridgeResults.set(parent, entry);
+    }
     finalLogObservers.get(entry.requestId)?.(entry);
+    return true;
 }
 /** Retain only the last attempt for a currently observed HTTP request. */
 export function notifyProxyAttemptLog(entry) {
@@ -99,7 +192,7 @@ export function isProxyActivityQuiet(snapshot, quietThresholdMs, nowMs = Date.no
     return nowMs - snapshot.lastActivityAt.getTime() >= quietThresholdMs;
 }
 /** Keep activity open until the response body completes, errors, or is cancelled. */
-export function trackProxyResponse(response, finishRequest, observer) {
+export function trackProxyResponse(response, finishRequest, observer, abortSignal) {
     if (!response.body) {
         try {
             const notified = observer?.onTerminal?.({
@@ -107,7 +200,7 @@ export function trackProxyResponse(response, finishRequest, observer) {
                 observedBodyBytes: 0,
                 responseChunks: 0,
             });
-            void Promise.resolve(notified).then(finishRequest, finishRequest);
+            void withTimeout(Promise.resolve(notified), 4000, "Timed out finalizing proxy response accounting").then(finishRequest, finishRequest);
         }
         catch {
             finishRequest();
@@ -119,17 +212,12 @@ export function trackProxyResponse(response, finishRequest, observer) {
     let responseChunks = 0;
     let settled = false;
     let sourceClosed = false;
-    // A framework can cancel its adapter after the upstream stream has already
-    // closed. Snapshot reader.closed before cancel() so that normal cleanup is
-    // not recorded as a client-aborted request.
-    void reader.closed.then(() => {
-        sourceClosed = true;
-    }, () => undefined);
     const settle = (outcome, error) => {
         if (settled) {
             return;
         }
         settled = true;
+        abortSignal?.removeEventListener("abort", onAbort);
         // Keep drain accounting open through bounded terminal bookkeeping, but
         // never hold back the client's response body while telemetry is written.
         try {
@@ -139,12 +227,29 @@ export function trackProxyResponse(response, finishRequest, observer) {
                 observedBodyBytes,
                 responseChunks,
             });
-            void Promise.resolve(notified).then(finishRequest, finishRequest);
+            void withTimeout(Promise.resolve(notified), 4000, "Timed out finalizing proxy response accounting").then(finishRequest, finishRequest);
         }
         catch {
             finishRequest();
         }
     };
+    const onAbort = () => {
+        settle(abortSignal?.reason?.name === "TimeoutError"
+            ? "stream_error"
+            : "client_cancelled", abortSignal?.reason);
+        void withTimeout(reader.cancel(abortSignal?.reason), PROXY_RESPONSE_CANCEL_TIMEOUT_MS, "Timed out cancelling the upstream proxy response").catch(() => undefined);
+    };
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+    if (abortSignal?.aborted) {
+        onAbort();
+    }
+    // A failed source cannot be observed only on a future downstream pull: a
+    // stalled reader might never pull again, leaving admission/drain open forever.
+    void reader.closed.then(() => {
+        sourceClosed = true;
+    }, (error) => {
+        settle("stream_error", error);
+    });
     const trackedBody = new ReadableStream({
         async pull(controller) {
             try {