@juspay/neurolink 9.93.1 → 9.94.0

package/dist/lib/proxy/socketWorkerRuntime.js

@@ -0,0 +1,294 @@
+import { isProxyWorkerControlMessage } from "./rollingWorkerProtocol.js";
+function isTransferableProxySocket(handle) {
+    if (!handle || typeof handle !== "object") {
+        return false;
+    }
+    const candidate = handle;
+    return (typeof candidate.pause === "function" &&
+        typeof candidate.resume === "function" &&
+        typeof candidate.destroy === "function" &&
+        typeof candidate.end === "function" &&
+        typeof candidate.once === "function");
+}
+function destroyTransferredHandle(handle) {
+    if (handle &&
+        typeof handle === "object" &&
+        typeof handle.destroy === "function") {
+        try {
+            handle.destroy();
+        }
+        catch {
+            // Invalid IPC handles must not crash the serving worker.
+        }
+    }
+}
+/**
+ * Adapts transferred TCP sockets to an HTTP server without opening another
+ * listener. Active responses finish normally; idle keep-alive sockets close as
+ * soon as draining begins.
+ */
+export function createSocketWorkerRuntime(server, options) {
+    const sockets = new Set();
+    const activeBySocket = new Map();
+    const activeResponses = new Set();
+    let draining = false;
+    let drained = false;
+    const maybeFinishDrain = () => {
+        if (draining && !drained && sockets.size === 0) {
+            drained = true;
+            options?.onDrained?.();
+        }
+    };
+    const requestStarted = (request, response) => {
+        const socket = request.socket;
+        activeBySocket.set(socket, (activeBySocket.get(socket) ?? 0) + 1);
+        activeResponses.add(response);
+        if (draining) {
+            response.shouldKeepAlive = false;
+        }
+        let settled = false;
+        const settle = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            activeResponses.delete(response);
+            const remaining = Math.max(0, (activeBySocket.get(socket) ?? 1) - 1);
+            if (remaining === 0) {
+                activeBySocket.delete(socket);
+                if (draining) {
+                    socket.end();
+                }
+            }
+            else {
+                activeBySocket.set(socket, remaining);
+            }
+        };
+        response.once("finish", settle);
+        response.once("close", settle);
+    };
+    server.prependListener("request", requestStarted);
+    const acceptSocket = (socket) => {
+        if (draining) {
+            socket.destroy();
+            return;
+        }
+        sockets.add(socket);
+        socket.once("close", () => {
+            sockets.delete(socket);
+            activeBySocket.delete(socket);
+            maybeFinishDrain();
+        });
+        server.emit("connection", socket);
+        socket.resume();
+    };
+    const drain = () => {
+        if (draining) {
+            return;
+        }
+        draining = true;
+        for (const response of activeResponses) {
+            response.shouldKeepAlive = false;
+        }
+        for (const socket of sockets) {
+            if (!activeBySocket.has(socket)) {
+                socket.end();
+            }
+        }
+        maybeFinishDrain();
+    };
+    return {
+        acceptSocket,
+        drain,
+        close: () => {
+            server.off("request", requestStarted);
+            for (const socket of sockets) {
+                socket.destroy();
+            }
+            sockets.clear();
+            activeBySocket.clear();
+            activeResponses.clear();
+            draining = true;
+            maybeFinishDrain();
+        },
+        snapshot: () => ({
+            draining,
+            sockets: sockets.size,
+            activeRequests: [...activeBySocket.values()].reduce((total, count) => total + count, 0),
+            drained,
+        }),
+    };
+}
+export function attachSocketWorkerProcess(server, input) {
+    let activated = false;
+    let gracefulDrain = false;
+    const pendingSockets = new Map();
+    const send = (message) => {
+        if (!process.connected || !process.send) {
+            return;
+        }
+        try {
+            process.send(message);
+        }
+        catch {
+            // Parent supervision handles the disconnected worker.
+        }
+    };
+    const runtime = createSocketWorkerRuntime(server, {
+        onDrained: () => {
+            send({
+                type: "proxy-worker:drained",
+                generation: input.generation,
+                pid: process.pid,
+            });
+            input.onDrained?.();
+        },
+    });
+    const drainWhenPendingSettled = () => {
+        if (!gracefulDrain || pendingSockets.size > 0) {
+            return;
+        }
+        // Defer to a macrotask so a request buffered on a just-committed socket can
+        // reach the HTTP server before drain() ends idle sockets; draining
+        // synchronously here would truncate that in-flight request.
+        setImmediate(() => runtime.drain());
+    };
+    const onMessage = (message, handle) => {
+        if (message &&
+            typeof message === "object" &&
+            message.type === "proxy-worker:socket") {
+            const socketMessage = message;
+            if (socketMessage.generation === input.generation &&
+                typeof message.socketId === "string" &&
+                message.socketId.length > 0 &&
+                isTransferableProxySocket(handle)) {
+                const socketId = message.socketId;
+                const socket = handle;
+                socket.pause();
+                if (!activated ||
+                    !process.connected ||
+                    !process.send ||
+                    gracefulDrain) {
+                    socket.destroy();
+                    return;
+                }
+                if (pendingSockets.has(socketId)) {
+                    socket.destroy();
+                    return;
+                }
+                pendingSockets.set(socketId, socket);
+                try {
+                    process.send({
+                        type: "proxy-worker:socket-accepted",
+                        generation: input.generation,
+                        pid: process.pid,
+                        socketId,
+                    }, (error) => {
+                        if (error) {
+                            pendingSockets.delete(socketId);
+                            socket.destroy();
+                        }
+                    });
+                }
+                catch {
+                    pendingSockets.delete(socketId);
+                    socket.destroy();
+                }
+            }
+            else {
+                destroyTransferredHandle(handle);
+            }
+            return;
+        }
+        if (handle !== undefined) {
+            destroyTransferredHandle(handle);
+        }
+        if (isProxyWorkerControlMessage(message) &&
+            message.generation === input.generation) {
+            if (message.type === "proxy-worker:activate") {
+                if (!activated) {
+                    try {
+                        input.onActivated?.();
+                        activated = true;
+                        send({
+                            type: "proxy-worker:activated",
+                            generation: input.generation,
+                            pid: process.pid,
+                        });
+                    }
+                    catch (error) {
+                        send({
+                            type: "proxy-worker:fatal",
+                            generation: input.generation,
+                            pid: process.pid,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                        runtime.drain();
+                    }
+                }
+            }
+            else if (message.type === "proxy-worker:socket-commit" ||
+                message.type === "proxy-worker:socket-cancel") {
+                const socket = pendingSockets.get(message.socketId);
+                if (!socket) {
+                    return;
+                }
+                pendingSockets.delete(message.socketId);
+                if (message.type === "proxy-worker:socket-commit") {
+                    runtime.acceptSocket(socket);
+                }
+                else {
+                    socket.destroy();
+                }
+                drainWhenPendingSettled();
+            }
+            else {
+                // Graceful drain: a socket-commit for an already-accepted socket may
+                // still be in flight. Stop admitting new offers and defer the drain
+                // until every pending socket is committed or canceled, so an
+                // acknowledged connection is served instead of silently dropped.
+                gracefulDrain = true;
+                drainWhenPendingSettled();
+            }
+        }
+    };
+    // Terminal shutdown path: the parent IPC channel is gone (disconnect) or the
+    // process is being killed (SIGTERM/SIGINT). Unlike the graceful rolling drain
+    // above, pending offers can no longer be committed, so they are destroyed and
+    // the drain runs immediately — a best-effort close is correct when the process
+    // is exiting. The zero-downtime guarantee applies to the rolling handoff
+    // (control-message) path, not to process termination.
+    const drain = () => {
+        for (const socket of pendingSockets.values()) {
+            socket.destroy();
+        }
+        pendingSockets.clear();
+        runtime.drain();
+    };
+    const onTerminationSignal = () => drain();
+    process.on("message", onMessage);
+    process.once("disconnect", drain);
+    process.once("SIGTERM", onTerminationSignal);
+    process.once("SIGINT", onTerminationSignal);
+    send({
+        type: "proxy-worker:ready",
+        generation: input.generation,
+        pid: process.pid,
+        version: input.version,
+    });
+    return {
+        ...runtime,
+        close: () => {
+            process.off("message", onMessage);
+            process.off("disconnect", drain);
+            process.off("SIGTERM", onTerminationSignal);
+            process.off("SIGINT", onTerminationSignal);
+            for (const socket of pendingSockets.values()) {
+                socket.destroy();
+            }
+            pendingSockets.clear();
+            runtime.close();
+        },
+    };
+}
+//# sourceMappingURL=socketWorkerRuntime.js.map

package/dist/lib/proxy/sseInterceptor.js

@@ -337,7 +337,7 @@ function processEvent(acc, event) {
         const message = nestedError?.message ?? payload.message;
         acc.streamErrorMessage =
             typeof message === "string" && message.trim()
-                ? message.trim()
+                ? truncateString(message.trim(), MAX_EVENT_DATA_BYTES)
                 : truncateString(event.data, MAX_EVENT_DATA_BYTES);
     }
     switch (event.event) {

package/dist/lib/proxy/workerLog.d.ts

@@ -0,0 +1,6 @@
+/** Open a restrictive worker log without making proxy startup depend on it. */
+export declare function openProxyWorkerLog(filename: string, logDir?: string): {
+    stdio: number | "ignore";
+    close: () => void;
+    error?: string;
+};

package/dist/lib/proxy/workerLog.js

@@ -0,0 +1,42 @@
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+/** Open a restrictive worker log without making proxy startup depend on it. */
+export function openProxyWorkerLog(filename, logDir = join(homedir(), ".neurolink", "logs")) {
+    let fd;
+    try {
+        if (basename(filename) !== filename) {
+            throw new Error("worker log filename must not contain a path");
+        }
+        if (!existsSync(logDir)) {
+            mkdirSync(logDir, { recursive: true, mode: 0o700 });
+        }
+        else if (!statSync(logDir).isDirectory()) {
+            throw new Error("worker log path exists but is not a directory");
+        }
+        chmodSync(logDir, 0o700);
+        const path = join(logDir, filename);
+        fd = openSync(path, "a", 0o600);
+        chmodSync(path, 0o600);
+        return {
+            stdio: fd,
+            close: () => closeSync(fd),
+        };
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // The log is optional and startup must remain fail-open.
+            }
+        }
+        return {
+            stdio: "ignore",
+            close: () => undefined,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=workerLog.js.map

package/dist/lib/server/routes/openaiProxyRoutes.d.ts

@@ -12,6 +12,11 @@
  * provider/model pairs (e.g. "gpt-4o" -> vertex/gemini-2.5-pro).
  */
 import type { ModelRouterInterface, ProxyRuntimeConfigProvider, RouteGroup } from "../../types/index.js";
+declare function resolveStreamCancellationLifecycle(terminalStreamError: string | undefined): {
+    status: number;
+    errorType: string;
+    errorMessage: string;
+};
 /**
  * Create OpenAI-compatible proxy routes.
  *
@@ -27,3 +32,7 @@ import type { ModelRouterInterface, ProxyRuntimeConfigProvider, RouteGroup } fro
  * @returns RouteGroup with OpenAI-compatible endpoints.
  */
 export declare function createOpenAIProxyRoutes(modelRouter?: ModelRouterInterface, basePath?: string, loopbackPort?: number, runtimeConfigProvider?: ProxyRuntimeConfigProvider): RouteGroup;
+export declare const __testHooks: {
+    resolveStreamCancellationLifecycle: typeof resolveStreamCancellationLifecycle;
+};
+export {};

package/dist/lib/server/routes/openaiProxyRoutes.js

@@ -27,6 +27,19 @@ const LOOPBACK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes — long enough for slow
 // `createOpenAIProxyRoutes`'s third argument when the actual listener port is
 // known (e.g. when started from the CLI handler).
 const DEFAULT_LOOPBACK_PORT = 55669;
+function resolveStreamCancellationLifecycle(terminalStreamError) {
+    return terminalStreamError
+        ? {
+            status: 502,
+            errorType: "loopback_stream_error",
+            errorMessage: terminalStreamError,
+        }
+        : {
+            status: 499,
+            errorType: "client_cancelled",
+            errorMessage: "Client cancelled the OpenAI-compatible stream",
+        };
+}
 /**
  * Build an OpenAI-shaped error as a typed Response with the intended status.
  *
@@ -188,7 +201,8 @@ async function handleOpenAIToAnthropicBridge(args) {
                     await reader.cancel(reason);
                 }
                 finally {
-                    await finishLifecycle(499, "client_cancelled", "Client cancelled the OpenAI-compatible stream");
+                    const cancellation = resolveStreamCancellationLifecycle(terminalStreamError);
+                    await finishLifecycle(cancellation.status, cancellation.errorType, cancellation.errorMessage);
                 }
             },
         });
@@ -381,4 +395,5 @@ export function createOpenAIProxyRoutes(modelRouter, basePath = "", loopbackPort
         ],
     };
 }
+export const __testHooks = { resolveStreamCancellationLifecycle };
 //# sourceMappingURL=openaiProxyRoutes.js.map

package/dist/lib/types/cli.d.ts

@@ -820,6 +820,42 @@ export type FallbackInfo = {
     provider: string;
     model: string;
 };
+export type ProxyRollingState = {
+    generation: number;
+    active: {
+        pid: number;
+        version: string;
+        generation: number;
+    } | null;
+    candidate: {
+        pid: number;
+        expectedVersion: string;
+        generation: number;
+    } | null;
+    draining: Array<{
+        pid: number;
+        version: string;
+        generation: number;
+    }>;
+    queuedSockets: number;
+    rejectedSockets: number;
+    failedTransfers: number;
+    lastFailure: {
+        at: string;
+        generation: number;
+        version: string;
+        phase: "startup" | "activation" | "runtime" | "transfer";
+        message: string;
+    } | null;
+};
+export type ProxySupervisorState = {
+    pid: number;
+    host: string;
+    port: number;
+    startTime: string;
+    updaterPid?: number;
+    rolling: ProxyRollingState;
+};
 /** Persisted state for a running proxy instance */
 export type ProxyState = {
     pid: number;
@@ -840,6 +876,8 @@ export type ProxyState = {
     guardPid?: number;
     /** Dedicated updater PID for launchd-managed proxy installations. */
     updaterPid?: number;
+    /** Stable listener supervisor PID when requests are served by socket workers. */
+    supervisorPid?: number;
     /** How the proxy was launched — "launchd" if installed as service, "manual" otherwise */
     managedBy?: "launchd" | "manual";
     /** Whether the proxy is running in transparent passthrough mode */

package/dist/lib/types/proxy.d.ts

@@ -1455,6 +1455,162 @@ export type UpdaterWorkerSupervisor = {
     checkNow: () => number | undefined;
     stop: () => void;
 };
+export type ProxyWorkerControlMessage = {
+    type: "proxy-worker:activate";
+    generation: number;
+} | {
+    type: "proxy-worker:drain";
+    generation: number;
+} | {
+    type: "proxy-worker:shutdown";
+    generation: number;
+} | {
+    type: "proxy-worker:socket-commit";
+    generation: number;
+    socketId: string;
+} | {
+    type: "proxy-worker:socket-cancel";
+    generation: number;
+    socketId: string;
+};
+export type ProxyWorkerStatusMessage = {
+    type: "proxy-worker:ready";
+    generation: number;
+    pid: number;
+    version: string;
+} | {
+    type: "proxy-worker:drained";
+    generation: number;
+    pid: number;
+} | {
+    type: "proxy-worker:activated";
+    generation: number;
+    pid: number;
+} | {
+    type: "proxy-worker:fatal";
+    generation: number;
+    pid: number;
+    message: string;
+} | {
+    type: "proxy-worker:socket-accepted";
+    generation: number;
+    pid: number;
+    socketId: string;
+};
+export type ProxyWorkerSocketMessage = {
+    type: "proxy-worker:socket";
+    generation: number;
+    socketId: string;
+};
+export type ProxyWorkerIpcMessage = ProxyWorkerControlMessage | ProxyWorkerStatusMessage | ProxyWorkerSocketMessage;
+export type TransferableProxySocket = Pick<import("node:net").Socket, "destroy" | "end" | "pause" | "resume" | "once">;
+export type RollingWorkerHandle = {
+    pid: number;
+    sendControl: (message: ProxyWorkerControlMessage) => void;
+    sendSocket: (generation: number, socket: TransferableProxySocket, callback: (error?: Error | null) => void) => void;
+    terminate: (signal?: NodeJS.Signals) => void;
+    onMessage: (listener: (message: ProxyWorkerStatusMessage) => void) => () => void;
+    onExit: (listener: (code: number | null, signal: string | null) => void) => () => void;
+};
+export type SpawnProxySocketWorkerOptions = {
+    generation: number;
+    expectedVersion: string;
+    command: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    stdout?: "inherit" | "ignore";
+    stderr?: "inherit" | "ignore";
+    socketAckTimeoutMs?: number;
+};
+export type RollingWorkerSupervisorSnapshot = {
+    generation: number;
+    active: {
+        pid: number;
+        version: string;
+        generation: number;
+    } | null;
+    candidate: {
+        pid: number;
+        expectedVersion: string;
+        generation: number;
+    } | null;
+    draining: Array<{
+        pid: number;
+        version: string;
+        generation: number;
+    }>;
+    queuedSockets: number;
+    rejectedSockets: number;
+    failedTransfers: number;
+    lastFailure: {
+        at: string;
+        generation: number;
+        version: string;
+        phase: "startup" | "activation" | "runtime" | "transfer";
+        message: string;
+    } | null;
+};
+export type RollingWorkerSupervisorOptions = {
+    spawnWorker: (generation: number, expectedVersion: string) => RollingWorkerHandle;
+    readyTimeoutMs?: number;
+    socketQueueLimit?: number;
+    socketQueueTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    onStateChange?: (snapshot: RollingWorkerSupervisorSnapshot) => void;
+    log?: (message: string) => void;
+};
+export type RollingProxyServerOptions = {
+    host: string;
+    port: number;
+    initialVersion: string;
+    spawnWorker: (generation: number, expectedVersion: string) => RollingWorkerHandle;
+    readyTimeoutMs?: number;
+    socketQueueLimit?: number;
+    socketQueueTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    recoveryDelayMs?: number;
+    maxRecoveryDelayMs?: number;
+    onStateChange?: (snapshot: RollingWorkerSupervisorSnapshot) => void;
+    log?: (message: string) => void;
+};
+export type RollingProxyServer = {
+    address: {
+        host: string;
+        port: number;
+    };
+    replace: (expectedVersion: string) => Promise<RollingWorkerSupervisorSnapshot>;
+    snapshot: () => RollingWorkerSupervisorSnapshot;
+    close: () => Promise<void>;
+};
+export type RollingManagedWorker = {
+    handle: RollingWorkerHandle;
+    generation: number;
+    version: string;
+    dispose: () => void;
+};
+export type RollingCandidateWorker = RollingManagedWorker & {
+    expectedVersion: string;
+    activationRequested: boolean;
+    settle: (error?: Error) => void;
+};
+export type RollingQueuedSocket = {
+    socket: TransferableProxySocket;
+    timeout: NodeJS.Timeout;
+};
+export type SocketWorkerRuntime = {
+    acceptSocket: (socket: TransferableProxySocket) => void;
+    drain: () => void;
+    close: () => void;
+    snapshot: () => {
+        draining: boolean;
+        sockets: number;
+        activeRequests: number;
+        drained: boolean;
+    };
+};
+export type SocketWorkerRuntimeOptions = {
+    onDrained?: () => void;
+};
 /** Shape of the dynamically-imported js-yaml module. `dump` is optional —
  *  read-only consumers (proxy config loader) only need `load`; writers
  *  (CLI primary-account commands) check `dump` before calling. */

package/dist/lib/utils/errorHandling.d.ts

@@ -14,6 +14,7 @@ export declare const ERROR_CODES: {
     readonly MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED";
     readonly NETWORK_ERROR: "NETWORK_ERROR";
     readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly PROXY_WORKER_LIFECYCLE_FAILED: "PROXY_WORKER_LIFECYCLE_FAILED";
     readonly PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE";
     readonly PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED";
     readonly PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED";
@@ -247,6 +248,13 @@ export declare class ErrorFactory {
      * Create an evaluation execution failed error
      */
     static evaluationExecutionFailed(operation: string, originalError: Error): NeuroLinkError;
+    /**
+     * Create a proxy rolling-worker lifecycle error. Preserves the caller's exact
+     * message so existing substring-based assertions keep working, while giving
+     * callers a typed `code`/`category` to branch on instead of string-matching
+     * generic `Error` instances.
+     */
+    static proxyWorkerLifecycle(message: string, context?: Record<string, unknown>): NeuroLinkError;
 }
 /**
  * Timeout wrapper for async operations

package/dist/lib/utils/errorHandling.js

@@ -20,6 +20,7 @@ export const ERROR_CODES = {
     MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED",
     NETWORK_ERROR: "NETWORK_ERROR",
     PERMISSION_DENIED: "PERMISSION_DENIED",
+    PROXY_WORKER_LIFECYCLE_FAILED: "PROXY_WORKER_LIFECYCLE_FAILED",
     // Provider errors
     PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE",
     PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
@@ -818,6 +819,25 @@ export class ErrorFactory {
             originalError,
         });
     }
+    // ============================================================================
+    // PROXY ROLLING-WORKER ERRORS
+    // ============================================================================
+    /**
+     * Create a proxy rolling-worker lifecycle error. Preserves the caller's exact
+     * message so existing substring-based assertions keep working, while giving
+     * callers a typed `code`/`category` to branch on instead of string-matching
+     * generic `Error` instances.
+     */
+    static proxyWorkerLifecycle(message, context) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PROXY_WORKER_LIFECYCLE_FAILED,
+            message,
+            category: ErrorCategory.SYSTEM,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: context || {},
+        });
+    }
 }
 /**
  * Timeout wrapper for async operations

package/dist/proxy/globalInstaller.js

@@ -14,7 +14,7 @@ function writableDirectory(path) {
         if (!existsSync(path)) {
             return false;
         }
-        accessSync(path, constants.W_OK);
+        accessSync(path, constants.W_OK | constants.X_OK);
         return true;
     }
     catch {