@juspay/neurolink 12.12.9 → 12.12.10

package/dist/proxy/proxyLifecycle.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { withTimeout } from "../utils/async/withTimeout.js";
 import { logger } from "../utils/logger.js";
+import { startProxyRuntimeMetrics } from "./proxyRuntimeMetrics.js";
 const SCHEMA_VERSION = 1;
 const DEFAULT_QUEUE_CAPACITY = 10_000;
 const DEFAULT_BATCH_SIZE = 256;
@@ -14,8 +15,12 @@ const MAX_WRITE_RETRY_DELAY_MS = 1_000;
 const LIFECYCLE_APPEND_TIMEOUT_MS = 2_000;
 const MAX_SHORT_FIELD_LENGTH = 256;
 const SESSION_KEY_FILE = ".proxy-lifecycle-session-key";
+let chmodLifecycleDirectory = chmodSync;
 let loggerEnabled = false;
+let loggerRequired = false;
+let stopRuntimeMetrics;
 let lifecycleLogDir;
+let filePrefix = "proxy-lifecycle";
 let queueCapacity = DEFAULT_QUEUE_CAPACITY;
 let batchSize = DEFAULT_BATCH_SIZE;
 let flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
@@ -141,6 +146,10 @@ function scheduleFlush(delayMs = flushIntervalMs) {
     }, delayMs);
     flushTimer.unref?.();
 }
+/**
+ * Append a bounded metadata batch and confirm each admission without
+ * replaying ambiguous writes.
+ */
 async function flushBatch() {
     if (queue.length === 0) {
         return;
@@ -150,7 +159,7 @@ async function flushBatch() {
     try {
         const byPath = new Map();
         for (const item of batch) {
-            const path = join(item.logDir, `proxy-lifecycle-${item.date}.jsonl`);
+            const path = join(item.logDir, `${item.filePrefix ?? "proxy-lifecycle"}-${item.date}.jsonl`);
             const items = byPath.get(path) ?? [];
             items.push(item);
             byPath.set(path, items);
@@ -167,11 +176,13 @@ async function flushBatch() {
             }, LIFECYCLE_APPEND_TIMEOUT_MS);
             timeout.unref?.();
             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.
+                // OS-acknowledged append survives serving-process death. This is not
+                // an fsync/power-loss guarantee. Admission waits on its own record.
                 await appendLifecycleFile(path, lines.join(""), { mode: 0o600 });
                 written += lines.length;
+                for (const item of items) {
+                    item.onPersisted?.(true);
+                }
             }
             catch (error) {
                 writeFailures += 1;
@@ -189,6 +200,9 @@ async function flushBatch() {
                 ]).has(code ?? "");
                 if (!definitelyNotWritten) {
                     unconfirmedWrites += items.length;
+                    for (const item of items) {
+                        item.onPersisted?.(false);
+                    }
                     logger.warn("[proxy] lifecycle metadata append outcome is uncertain", {
                         path,
                         records: items.length,
@@ -211,6 +225,11 @@ async function flushBatch() {
                 if (exhausted > 0) {
                     dropped += exhausted;
                     writeDrops += exhausted;
+                    for (const item of items) {
+                        if (item.writeRetries >= maxWriteRetries) {
+                            item.onPersisted?.(false);
+                        }
+                    }
                 }
                 logger.warn("[proxy] lifecycle metadata write failed", {
                     path,
@@ -234,6 +253,10 @@ async function flushBatch() {
         inFlight = Math.max(0, inFlight - batch.length);
     }
 }
+/**
+ * Serialize batch ownership so timeouts cannot create overlapping append
+ * retries.
+ */
 function startFlush() {
     if (flushInFlight) {
         return flushInFlight;
@@ -257,10 +280,18 @@ function startFlush() {
     });
     return currentFlush;
 }
+/**
+ * Configure private journal storage while retaining required admission
+ * when initialization fails.
+ */
 export function configureProxyLifecycleLogger(options) {
+    stopRuntimeMetrics?.();
+    stopRuntimeMetrics = undefined;
     clearScheduledFlush();
     nextFlushDelayMs = undefined;
     loggerEnabled = false;
+    loggerRequired = options.enabled;
+    filePrefix = options.filePrefix ?? "proxy-lifecycle";
     lifecycleLogDir = undefined;
     queueCapacity = positiveInteger(options.queueCapacity, DEFAULT_QUEUE_CAPACITY);
     batchSize = positiveInteger(options.batchSize, DEFAULT_BATCH_SIZE);
@@ -269,9 +300,21 @@ export function configureProxyLifecycleLogger(options) {
     if (options.enabled && options.logDir) {
         try {
             mkdirSync(options.logDir, { recursive: true, mode: 0o700 });
+            // mkdir mode does not harden an existing directory. Keep admission
+            // required but the sink disabled if its privacy boundary cannot be set.
+            chmodLifecycleDirectory(options.logDir, 0o700);
             sessionHashKey = resolveSessionHashKey(options.logDir);
             lifecycleLogDir = options.logDir;
             loggerEnabled = true;
+            stopRuntimeMetrics = startProxyRuntimeMetrics((runtimeSample) => {
+                logProxyLifecycleEvent({
+                    event: "runtime_sample",
+                    requestId: "-",
+                    method: "-",
+                    path: "-",
+                    runtimeSample,
+                });
+            });
         }
         catch (error) {
             logger.warn("[proxy] lifecycle metadata logging disabled", {
@@ -286,15 +329,24 @@ export function configureProxyLifecycleLogger(options) {
 }
 /** Enqueue fixed-size lifecycle metadata without awaiting filesystem work. */
 export function logProxyLifecycleEvent(input) {
+    enqueueLifecycleEvent(input);
+}
+/**
+ * Enqueue bounded metadata and resolve admission failure immediately when
+ * capacity is unavailable.
+ */
+function enqueueLifecycleEvent(input, onPersisted) {
     if (!loggerEnabled || !lifecycleLogDir) {
+        onPersisted?.(false);
         return;
     }
     try {
         attempted += 1;
         const sequence = nextSequence++;
-        if (queue.length >= queueCapacity) {
+        if (queue.length + inFlight >= queueCapacity) {
             dropped += 1;
             queueDrops += 1;
+            onPersisted?.(false);
             return;
         }
         const timestamp = formatTimestamp(input.timestampMs);
@@ -344,12 +396,23 @@ export function logProxyLifecycleEvent(input) {
             ...(terminalOutcome !== undefined ? { terminalOutcome } : {}),
             ...(errorType !== undefined ? { errorType } : {}),
             ...(errorCode !== undefined ? { errorCode } : {}),
+            ...(input.supervisorEvent
+                ? {
+                    supervisorEvent: {
+                        ...input.supervisorEvent,
+                        reason: clip(input.supervisorEvent.reason),
+                    },
+                }
+                : {}),
+            ...(input.runtimeSample ? { runtimeSample: input.runtimeSample } : {}),
         };
         queue.push({
+            filePrefix,
             logDir: lifecycleLogDir,
             date: String(record.timestamp).slice(0, 10),
             record,
             writeRetries: 0,
+            onPersisted,
         });
         enqueued += 1;
         scheduleFlush();
@@ -357,6 +420,28 @@ export function logProxyLifecycleEvent(input) {
     catch {
         dropped += 1;
         invalidDrops += 1;
+        onPersisted?.(false);
+    }
+}
+/** Confirm admission before upstream dispatch, without waiting for later traffic.
+ * Disabled logging is explicit; an enabled but unhealthy sink refuses dispatch.
+ * A timeout never retries an ambiguous provider request or the pending append.
+ */
+export async function persistProxyLifecycleAcceptance(input, timeoutMs = LIFECYCLE_APPEND_TIMEOUT_MS) {
+    if (!loggerRequired) {
+        return;
+    }
+    const confirmed = new Promise((resolve) => {
+        enqueueLifecycleEvent({ ...input, event: "request_accepted" }, resolve);
+    });
+    // Yield one turn for concurrent admissions to share a bounded batch.
+    clearScheduledFlush();
+    scheduleFlush(0);
+    const persisted = await withTimeout(confirmed, timeoutMs, "Proxy admission metadata append is still pending").catch(() => false);
+    if (!persisted) {
+        throw Object.assign(new Error("Proxy admission metadata could not be confirmed"), {
+            code: "PROXY_TELEMETRY_UNAVAILABLE",
+        });
     }
 }
 export async function flushProxyLifecycleEvents(timeoutMs = 5_000) {
@@ -370,6 +455,10 @@ export async function flushProxyLifecycleEvents(timeoutMs = 5_000) {
         }
     }
 }
+/**
+ * Expose journal accounting, process identity, and outstanding writes
+ * without changing them.
+ */
 export function getProxyLifecycleLoggerSnapshot() {
     return {
         enabled: loggerEnabled,
@@ -392,9 +481,16 @@ export function getProxyLifecycleLoggerSnapshot() {
         flushing: flushInFlight !== undefined,
     };
 }
+/**
+ * Reset timers, accounting, and injected I/O after isolated tests have
+ * drained their work.
+ */
 export function resetProxyLifecycleLoggerForTests() {
+    stopRuntimeMetrics?.();
+    stopRuntimeMetrics = undefined;
     clearScheduledFlush();
     loggerEnabled = false;
+    loggerRequired = false;
     lifecycleLogDir = undefined;
     queueCapacity = DEFAULT_QUEUE_CAPACITY;
     batchSize = DEFAULT_BATCH_SIZE;
@@ -419,9 +515,19 @@ export function resetProxyLifecycleLoggerForTests() {
     flushInFlight = undefined;
     nextFlushDelayMs = undefined;
     appendLifecycleFile = appendFile;
+    chmodLifecycleDirectory = chmodSync;
 }
 /** Isolated failure injection for lifecycle durability tests. */
 export const __proxyLifecycleTestHooks = {
+    /**
+     * Inject directory-hardening failures without altering real filesystem permissions.
+     */
+    setChmodForTests(chmod) {
+        chmodLifecycleDirectory = chmod;
+    },
+    /**
+     * Inject controlled append outcomes while preserving the production admission and queue paths.
+     */
     setAppendFileForTests(append) {
         appendLifecycleFile = append;
     },

package/dist/proxy/proxyRequestKind.d.ts

@@ -0,0 +1,2 @@
+/** These metadata endpoints finish as HTTP responses, without model generation. */
+export declare function isProxyAuxiliaryRequest(method: string, path: string): boolean;

package/dist/proxy/proxyRequestKind.js

@@ -0,0 +1,6 @@
+/** These metadata endpoints finish as HTTP responses, without model generation. */
+export function isProxyAuxiliaryRequest(method, path) {
+    return ((method === "POST" && path === "/v1/messages/count_tokens") ||
+        (method === "GET" &&
+            (path === "/backend-api/codex/models" || path === "/v1/models")));
+}

package/dist/proxy/proxyRuntimeMetrics.d.ts

@@ -0,0 +1,3 @@
+import type { ProxyRuntimeSample } from "../types/index.js";
+/** Samples use actual elapsed time, including delayed timers under host load. */
+export declare function startProxyRuntimeMetrics(emit: (sample: ProxyRuntimeSample) => void): () => void;

package/dist/proxy/proxyRuntimeMetrics.js

@@ -0,0 +1,34 @@
+import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+import { availableParallelism, loadavg } from "node:os";
+/** Samples use actual elapsed time, including delayed timers under host load. */
+export function startProxyRuntimeMetrics(emit) {
+    const histogram = monitorEventLoopDelay({ resolution: 20 });
+    histogram.enable();
+    let previousCpu = process.cpuUsage();
+    let previousTime = performance.now();
+    const timer = setInterval(() => {
+        const now = performance.now();
+        const cpu = process.cpuUsage();
+        const intervalMs = now - previousTime;
+        emit({
+            intervalMs,
+            cpuPercentOneCore: ((cpu.user - previousCpu.user + cpu.system - previousCpu.system) /
+                (intervalMs * 1000)) *
+                100,
+            rssBytes: process.memoryUsage().rss,
+            heapUsedBytes: process.memoryUsage().heapUsed,
+            eventLoopDelayP99Ms: histogram.count ? histogram.percentile(99) / 1e6 : 0,
+            eventLoopDelayMaxMs: histogram.count ? histogram.max / 1e6 : 0,
+            hostLoad1m: loadavg()[0],
+            availableParallelism: availableParallelism(),
+        });
+        previousCpu = cpu;
+        previousTime = now;
+        histogram.reset();
+    }, 10_000);
+    timer.unref();
+    return () => {
+        clearInterval(timer);
+        histogram.disable();
+    };
+}

package/dist/proxy/requestLogger.d.ts

@@ -6,9 +6,15 @@
  * Useful for debugging and auditing proxy traffic.
  */
 import type { ProxyBodyCaptureEntry, RequestAttemptLogEntry, RequestLogEntry, ProxyRequestLoggerSnapshot } from "../types/index.js";
+/**
+ * Expose independent metadata-sink and body-capture counters for incident reconciliation.
+ */
 export declare function getRequestLoggerSnapshot(): ProxyRequestLoggerSnapshot;
 /** Wait, up to a bounded deadline, for admitted request/body writes to settle. */
 export declare function flushRequestLogs(timeoutMs?: number): Promise<void>;
+/**
+ * Initialize private request logs and preserve required lifecycle admission on startup failures.
+ */
 export declare function initRequestLogger(enabled?: boolean, customLogsDir?: string): void;
 export declare function logRequest(entry: RequestLogEntry): Promise<void>;
 /**
@@ -18,19 +24,17 @@ export declare function logRequest(entry: RequestLogEntry): Promise<void>;
  */
 export declare function logRequestAttempt(entry: RequestAttemptLogEntry): Promise<void>;
 export declare function getLogDir(): string | null;
-/** Shared redaction used by offline replay exports and direct comparisons. */
-export declare function redactProxyHeadersForLogging(headers: Record<string, string> | undefined): Record<string, string> | undefined;
 /**
- * Apply the same bounded body redaction used by persisted proxy captures.
- * `value` and `bytes` are omitted only when the input is null or undefined.
- * This performs serialization immediately, so callers must keep it off proxy
- * hot paths unless body processing has already been explicitly requested.
+ * Redact sensitive header values in-place.
  */
+export declare function redactProxyHeadersForLogging(headers: Record<string, string> | undefined): Record<string, string> | undefined;
+/** Return a redacted body representation suitable for persisted request diagnostics. */
 export declare function prepareProxyBodyForLogging(body: unknown): {
     value?: string;
     bytes?: number;
     truncated: boolean;
 };
+/** Capture an owned request body with bounded processing and tracked index/export publication. */
 export declare function logBodyCapture(entry: ProxyBodyCaptureEntry): Promise<void>;
 /**
  * Log the FULL raw request and response for debugging.