@juspay/neurolink 9.93.2 → 9.94.1

package/dist/lib/proxy/rollingWorkerProcess.js

@@ -0,0 +1,194 @@
+import { spawn } from "node:child_process";
+import { ErrorFactory } from "../utils/errorHandling.js";
+import { isProxyWorkerStatusMessage, PROXY_SOCKET_WORKER_ENV, } from "./rollingWorkerProtocol.js";
+export function spawnProxySocketWorker(options) {
+    const socketAckTimeoutMs = Math.max(1, options.socketAckTimeoutMs ?? 5_000);
+    let nextSocketId = 0;
+    const pendingSockets = new Map();
+    const statusListeners = new Set();
+    const pendingStatusMessages = [];
+    let spawnError;
+    const child = spawn(options.command, options.args, {
+        env: {
+            ...process.env,
+            ...options.env,
+            [PROXY_SOCKET_WORKER_ENV]: "1",
+            NEUROLINK_PROXY_WORKER_GENERATION: String(options.generation),
+            NEUROLINK_PROXY_WORKER_EXPECTED_VERSION: options.expectedVersion,
+        },
+        stdio: [
+            "ignore",
+            options.stdout ?? "inherit",
+            options.stderr ?? "inherit",
+            "ipc",
+        ],
+    });
+    const childPid = child.pid;
+    const publishStatus = (message) => {
+        if (statusListeners.size === 0) {
+            if (pendingStatusMessages.length >= 32) {
+                pendingStatusMessages.shift();
+            }
+            pendingStatusMessages.push(message);
+            return;
+        }
+        for (const listener of statusListeners) {
+            listener(message);
+        }
+    };
+    child.once("error", (error) => {
+        spawnError = error;
+        if (!childPid) {
+            return;
+        }
+        publishStatus({
+            type: "proxy-worker:fatal",
+            generation: options.generation,
+            pid: childPid,
+            message: error.message,
+        });
+    });
+    if (!childPid) {
+        child.kill("SIGTERM");
+        throw ErrorFactory.proxyWorkerLifecycle("proxy worker spawn did not return a pid");
+    }
+    const settleSocket = (socketId, error) => {
+        const pending = pendingSockets.get(socketId);
+        if (!pending) {
+            return;
+        }
+        pendingSockets.delete(socketId);
+        clearTimeout(pending.timeout);
+        if (!error) {
+            pending.socket.destroy();
+        }
+        pending.callback(error);
+    };
+    const onInternalMessage = (message) => {
+        if (isProxyWorkerStatusMessage(message) &&
+            message.type === "proxy-worker:socket-accepted" &&
+            message.generation === options.generation &&
+            message.pid === childPid) {
+            const pending = pendingSockets.get(message.socketId);
+            if (!pending || pending.accepted) {
+                return;
+            }
+            pending.accepted = true;
+            try {
+                child.send({
+                    type: "proxy-worker:socket-commit",
+                    generation: options.generation,
+                    socketId: message.socketId,
+                }, (error) => settleSocket(message.socketId, error ?? undefined));
+            }
+            catch (error) {
+                settleSocket(message.socketId, error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    };
+    child.on("message", (message) => {
+        onInternalMessage(message);
+        if (isProxyWorkerStatusMessage(message)) {
+            publishStatus(message);
+        }
+    });
+    child.once("exit", () => {
+        for (const socketId of [...pendingSockets.keys()]) {
+            settleSocket(socketId, new Error(`proxy worker ${childPid} exited before accepting socket`));
+        }
+    });
+    const sendControl = (message) => {
+        if (!child.connected) {
+            throw new Error(`proxy worker ${childPid} IPC channel is closed`);
+        }
+        child.send(message, (error) => {
+            if (error && child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGTERM");
+            }
+        });
+    };
+    return {
+        pid: childPid,
+        sendControl,
+        sendSocket: (generation, socket, callback) => {
+            if (!child.connected) {
+                callback(new Error(`proxy worker ${childPid} IPC channel is closed`));
+                return;
+            }
+            const socketId = `${generation}:${++nextSocketId}`;
+            const timeout = setTimeout(() => {
+                if (child.connected) {
+                    try {
+                        child.send({
+                            type: "proxy-worker:socket-cancel",
+                            generation,
+                            socketId,
+                        });
+                    }
+                    catch {
+                        // The worker is terminated after the failed transfer is reported.
+                    }
+                }
+                settleSocket(socketId, new Error(`proxy worker ${childPid} did not accept socket within ${socketAckTimeoutMs}ms`));
+            }, socketAckTimeoutMs);
+            timeout.unref?.();
+            pendingSockets.set(socketId, {
+                socket,
+                callback,
+                timeout,
+                accepted: false,
+            });
+            try {
+                child.send({ type: "proxy-worker:socket", generation, socketId }, socket, { keepOpen: true }, (error) => {
+                    if (error) {
+                        settleSocket(socketId, error);
+                    }
+                });
+            }
+            catch (error) {
+                settleSocket(socketId, error instanceof Error ? error : new Error(String(error)));
+            }
+        },
+        terminate: (signal = "SIGTERM") => {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill(signal);
+            }
+        },
+        onMessage: (listener) => {
+            statusListeners.add(listener);
+            if (pendingStatusMessages.length > 0) {
+                const buffered = pendingStatusMessages.splice(0);
+                queueMicrotask(() => {
+                    if (statusListeners.has(listener)) {
+                        for (const message of buffered) {
+                            listener(message);
+                        }
+                    }
+                });
+            }
+            else if (spawnError) {
+                const error = spawnError;
+                queueMicrotask(() => {
+                    if (statusListeners.has(listener)) {
+                        listener({
+                            type: "proxy-worker:fatal",
+                            generation: options.generation,
+                            pid: childPid,
+                            message: error.message,
+                        });
+                    }
+                });
+            }
+            return () => statusListeners.delete(listener);
+        },
+        onExit: (listener) => {
+            if (child.exitCode !== null || child.signalCode !== null) {
+                queueMicrotask(() => listener(child.exitCode, child.signalCode));
+                return () => undefined;
+            }
+            child.on("exit", listener);
+            return () => child.off("exit", listener);
+        },
+    };
+}
+//# sourceMappingURL=rollingWorkerProcess.js.map

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

@@ -0,0 +1,5 @@
+import type { ProxyWorkerControlMessage, ProxyWorkerStatusMessage } from "../types/index.js";
+export declare const PROXY_SOCKET_WORKER_ENV = "NEUROLINK_PROXY_SOCKET_WORKER";
+export declare const PROXY_ROLLING_SUPERVISOR_ENV = "NEUROLINK_PROXY_ROLLING_SUPERVISOR";
+export declare function isProxyWorkerControlMessage(value: unknown): value is ProxyWorkerControlMessage;
+export declare function isProxyWorkerStatusMessage(value: unknown): value is ProxyWorkerStatusMessage;

package/dist/lib/proxy/rollingWorkerProtocol.js

@@ -0,0 +1,43 @@
+export const PROXY_SOCKET_WORKER_ENV = "NEUROLINK_PROXY_SOCKET_WORKER";
+export const PROXY_ROLLING_SUPERVISOR_ENV = "NEUROLINK_PROXY_ROLLING_SUPERVISOR";
+export function isProxyWorkerControlMessage(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const message = value;
+    if (!Number.isSafeInteger(message.generation) ||
+        Number(message.generation) <= 0) {
+        return false;
+    }
+    if (message.type === "proxy-worker:socket-commit" ||
+        message.type === "proxy-worker:socket-cancel") {
+        return typeof message.socketId === "string" && message.socketId.length > 0;
+    }
+    return (message.type === "proxy-worker:drain" ||
+        message.type === "proxy-worker:activate" ||
+        message.type === "proxy-worker:shutdown");
+}
+export function isProxyWorkerStatusMessage(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const message = value;
+    if (!Number.isSafeInteger(message.generation) ||
+        Number(message.generation) <= 0 ||
+        !Number.isSafeInteger(message.pid) ||
+        Number(message.pid) <= 0) {
+        return false;
+    }
+    if (message.type === "proxy-worker:ready") {
+        return typeof message.version === "string" && message.version.length > 0;
+    }
+    if (message.type === "proxy-worker:activated" ||
+        message.type === "proxy-worker:drained") {
+        return true;
+    }
+    if (message.type === "proxy-worker:socket-accepted") {
+        return typeof message.socketId === "string" && message.socketId.length > 0;
+    }
+    return (message.type === "proxy-worker:fatal" && typeof message.message === "string");
+}
+//# sourceMappingURL=rollingWorkerProtocol.js.map

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

@@ -0,0 +1,39 @@
+import type { RollingWorkerSupervisorOptions, RollingWorkerSupervisorSnapshot, TransferableProxySocket } from "../types/index.js";
+/**
+ * Owns worker generations while the caller owns the public listening socket.
+ * Sockets are transferred once to the active worker, so response bytes never
+ * traverse a supervisor-side proxy hop.
+ */
+export declare class RollingWorkerSupervisor {
+    private readonly options;
+    private generation;
+    private active;
+    private candidate;
+    private readonly draining;
+    private readonly queuedSockets;
+    private replacement;
+    private rejectedSockets;
+    private failedTransfers;
+    private lastFailure;
+    private closed;
+    private shutdownPromise;
+    private readonly shutdownWaiters;
+    constructor(options: RollingWorkerSupervisorOptions);
+    snapshot(): RollingWorkerSupervisorSnapshot;
+    start(expectedVersion: string): Promise<RollingWorkerSupervisorSnapshot>;
+    replace(expectedVersion: string): Promise<RollingWorkerSupervisorSnapshot>;
+    acceptSocket(socket: TransferableProxySocket): void;
+    private queueSocket;
+    close(): Promise<void>;
+    private closeWorkers;
+    private requestWorkerShutdown;
+    private forceTerminateWorkers;
+    private notifyShutdownWaiters;
+    private spawnCandidate;
+    private flushQueuedSockets;
+    private transferSocket;
+    private handleTransferFailure;
+    private rejectSocket;
+    private recordFailure;
+    private publishState;
+}

package/dist/lib/proxy/rollingWorkerSupervisor.js

@@ -0,0 +1,402 @@
+import { ErrorFactory } from "../utils/errorHandling.js";
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+const DEFAULT_SOCKET_QUEUE_LIMIT = 1_024;
+const DEFAULT_SOCKET_QUEUE_TIMEOUT_MS = 30_000;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+/**
+ * Owns worker generations while the caller owns the public listening socket.
+ * Sockets are transferred once to the active worker, so response bytes never
+ * traverse a supervisor-side proxy hop.
+ */
+export class RollingWorkerSupervisor {
+    options;
+    generation = 0;
+    active = null;
+    candidate = null;
+    draining = new Map();
+    queuedSockets = [];
+    replacement = null;
+    rejectedSockets = 0;
+    failedTransfers = 0;
+    lastFailure = null;
+    closed = false;
+    shutdownPromise = null;
+    shutdownWaiters = new Set();
+    constructor(options) {
+        this.options = {
+            ...options,
+            readyTimeoutMs: options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+            socketQueueLimit: options.socketQueueLimit ?? DEFAULT_SOCKET_QUEUE_LIMIT,
+            socketQueueTimeoutMs: options.socketQueueTimeoutMs ?? DEFAULT_SOCKET_QUEUE_TIMEOUT_MS,
+            shutdownTimeoutMs: options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
+        };
+    }
+    snapshot() {
+        return {
+            generation: this.generation,
+            active: this.active
+                ? {
+                    pid: this.active.handle.pid,
+                    version: this.active.version,
+                    generation: this.active.generation,
+                }
+                : null,
+            candidate: this.candidate
+                ? {
+                    pid: this.candidate.handle.pid,
+                    expectedVersion: this.candidate.expectedVersion,
+                    generation: this.candidate.generation,
+                }
+                : null,
+            draining: [...this.draining.values()].map((worker) => ({
+                pid: worker.handle.pid,
+                version: worker.version,
+                generation: worker.generation,
+            })),
+            queuedSockets: this.queuedSockets.length,
+            rejectedSockets: this.rejectedSockets,
+            failedTransfers: this.failedTransfers,
+            lastFailure: this.lastFailure,
+        };
+    }
+    start(expectedVersion) {
+        if (this.active) {
+            return this.active.version === expectedVersion
+                ? Promise.resolve(this.snapshot())
+                : this.replace(expectedVersion);
+        }
+        return this.replace(expectedVersion);
+    }
+    replace(expectedVersion) {
+        if (this.closed) {
+            return Promise.reject(ErrorFactory.proxyWorkerLifecycle("rolling worker supervisor is closed"));
+        }
+        if (!/^\d+\.\d+\.\d+$/.test(expectedVersion)) {
+            return Promise.reject(ErrorFactory.proxyWorkerLifecycle(`invalid expected worker version: ${expectedVersion}`, { expectedVersion }));
+        }
+        if (this.replacement) {
+            return this.candidate?.expectedVersion === expectedVersion
+                ? this.replacement
+                : Promise.reject(ErrorFactory.proxyWorkerLifecycle(`worker replacement for v${this.candidate?.expectedVersion ?? "unknown"} is already in progress`, { requestedVersion: expectedVersion }));
+        }
+        this.lastFailure = null;
+        this.replacement = this.spawnCandidate(expectedVersion).finally(() => {
+            this.replacement = null;
+        });
+        return this.replacement;
+    }
+    acceptSocket(socket) {
+        socket.pause();
+        if (this.closed) {
+            this.rejectSocket(socket);
+            return;
+        }
+        if (this.active) {
+            this.transferSocket(this.active, socket);
+            return;
+        }
+        this.queueSocket(socket);
+    }
+    queueSocket(socket) {
+        if (this.queuedSockets.length >= this.options.socketQueueLimit) {
+            this.rejectSocket(socket);
+            return;
+        }
+        const queued = {
+            socket,
+            timeout: setTimeout(() => {
+                const index = this.queuedSockets.indexOf(queued);
+                if (index >= 0) {
+                    this.queuedSockets.splice(index, 1);
+                    this.rejectSocket(socket);
+                }
+            }, this.options.socketQueueTimeoutMs),
+        };
+        queued.timeout.unref?.();
+        this.queuedSockets.push(queued);
+        this.publishState();
+    }
+    close() {
+        if (this.shutdownPromise) {
+            return this.shutdownPromise;
+        }
+        this.closed = true;
+        this.shutdownPromise = this.closeWorkers();
+        return this.shutdownPromise;
+    }
+    async closeWorkers() {
+        for (const queued of this.queuedSockets.splice(0)) {
+            clearTimeout(queued.timeout);
+            this.rejectSocket(queued.socket);
+        }
+        if (this.candidate) {
+            this.candidate.settle(new Error("rolling worker supervisor closed during replacement"));
+        }
+        if (this.active) {
+            this.requestWorkerShutdown(this.active);
+        }
+        for (const worker of this.draining.values()) {
+            this.requestWorkerShutdown(worker);
+        }
+        this.publishState();
+        if (!this.active && this.draining.size === 0) {
+            return;
+        }
+        await new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timeout);
+                this.shutdownWaiters.delete(finish);
+                resolve();
+            };
+            const timeout = setTimeout(() => {
+                this.forceTerminateWorkers();
+                finish();
+            }, this.options.shutdownTimeoutMs);
+            timeout.unref?.();
+            this.shutdownWaiters.add(finish);
+        });
+    }
+    requestWorkerShutdown(worker) {
+        try {
+            worker.handle.sendControl({
+                type: "proxy-worker:shutdown",
+                generation: worker.generation,
+            });
+        }
+        catch {
+            worker.handle.terminate("SIGTERM");
+        }
+    }
+    forceTerminateWorkers() {
+        if (this.active) {
+            this.active.handle.terminate("SIGTERM");
+            this.active.dispose();
+            this.active = null;
+        }
+        for (const worker of this.draining.values()) {
+            worker.handle.terminate("SIGTERM");
+            worker.dispose();
+        }
+        this.draining.clear();
+        this.publishState();
+    }
+    notifyShutdownWaiters() {
+        if (!this.closed || this.active || this.draining.size > 0) {
+            return;
+        }
+        for (const finish of [...this.shutdownWaiters]) {
+            finish();
+        }
+    }
+    spawnCandidate(expectedVersion) {
+        const generation = ++this.generation;
+        let handle;
+        try {
+            handle = this.options.spawnWorker(generation, expectedVersion);
+        }
+        catch (error) {
+            this.recordFailure(generation, expectedVersion, "startup", error instanceof Error ? error.message : String(error));
+            this.publishState();
+            return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (error, phase = "startup") => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(readyTimeout);
+                if (error) {
+                    if (!this.closed) {
+                        this.recordFailure(generation, expectedVersion, phase, error.message);
+                    }
+                    if (this.candidate?.generation === generation) {
+                        this.candidate = null;
+                    }
+                    handle.terminate("SIGTERM");
+                    dispose();
+                    this.publishState();
+                    reject(error);
+                    return;
+                }
+                resolve(this.snapshot());
+            };
+            const offMessage = handle.onMessage((message) => {
+                if (message.generation !== generation || message.pid !== handle.pid) {
+                    return;
+                }
+                if (message.type === "proxy-worker:fatal") {
+                    const error = new Error(`worker ${handle.pid} failed: ${message.message}`);
+                    if (this.candidate?.generation === generation) {
+                        finish(error);
+                    }
+                    else if (this.active?.generation === generation) {
+                        this.active.dispose();
+                        this.active = null;
+                        handle.terminate("SIGTERM");
+                        this.recordFailure(generation, expectedVersion, "runtime", message.message);
+                        this.options.log?.(`[proxy-supervisor] active worker reported fatal generation=${generation} pid=${handle.pid}: ${message.message}`);
+                        this.publishState();
+                        this.notifyShutdownWaiters();
+                    }
+                    return;
+                }
+                if (message.type === "proxy-worker:ready") {
+                    if (message.version !== expectedVersion) {
+                        finish(new Error(`worker ${handle.pid} reported v${message.version}; expected v${expectedVersion}`));
+                        return;
+                    }
+                    const candidate = this.candidate;
+                    if (!candidate) {
+                        return;
+                    }
+                    if (!candidate.activationRequested) {
+                        try {
+                            handle.sendControl({
+                                type: "proxy-worker:activate",
+                                generation,
+                            });
+                            candidate.activationRequested = true;
+                        }
+                        catch (error) {
+                            finish(error instanceof Error ? error : new Error(String(error)), "activation");
+                        }
+                    }
+                    return;
+                }
+                if (message.type !== "proxy-worker:activated") {
+                    return;
+                }
+                if (!this.candidate?.activationRequested) {
+                    finish(new Error(`worker ${handle.pid} acknowledged activation before readiness`), "activation");
+                    return;
+                }
+                const previous = this.active;
+                const activated = {
+                    handle,
+                    generation,
+                    version: expectedVersion,
+                    dispose,
+                };
+                this.active = activated;
+                this.candidate = null;
+                this.flushQueuedSockets();
+                if (previous) {
+                    this.draining.set(previous.generation, previous);
+                    try {
+                        previous.handle.sendControl({
+                            type: "proxy-worker:drain",
+                            generation: previous.generation,
+                        });
+                    }
+                    catch {
+                        previous.handle.terminate("SIGTERM");
+                    }
+                }
+                this.options.log?.(`[proxy-supervisor] activated generation=${generation} pid=${handle.pid} version=${expectedVersion}`);
+                this.publishState();
+                finish();
+            });
+            const offExit = handle.onExit((code, signal) => {
+                if (this.candidate?.generation === generation) {
+                    finish(new Error(`worker ${handle.pid} exited before readiness (code=${code ?? "none"}, signal=${signal ?? "none"})`));
+                    return;
+                }
+                if (this.active?.generation === generation) {
+                    this.active.dispose();
+                    this.active = null;
+                    if (!this.closed) {
+                        this.recordFailure(generation, expectedVersion, "runtime", `worker exited (code=${code ?? "none"}, signal=${signal ?? "none"})`);
+                    }
+                    this.options.log?.(`[proxy-supervisor] active worker exited generation=${generation} pid=${handle.pid}`);
+                }
+                const drained = this.draining.get(generation);
+                if (drained) {
+                    drained.dispose();
+                    this.draining.delete(generation);
+                }
+                this.publishState();
+                this.notifyShutdownWaiters();
+            });
+            const dispose = () => {
+                offMessage();
+                offExit();
+            };
+            const readyTimeout = setTimeout(() => {
+                finish(new Error(`worker ${handle.pid} did not become ready within ${this.options.readyTimeoutMs}ms`));
+            }, this.options.readyTimeoutMs);
+            readyTimeout.unref?.();
+            this.candidate = {
+                handle,
+                generation,
+                version: expectedVersion,
+                expectedVersion,
+                activationRequested: false,
+                dispose,
+                settle: finish,
+            };
+            this.publishState();
+        });
+    }
+    flushQueuedSockets() {
+        // Capture the active worker once: a synchronous sendSocket failure inside
+        // transferSocket can clear this.active mid-loop, and re-reading it would
+        // pass null into transferSocket and strand the queued socket.
+        const worker = this.active;
+        if (!worker) {
+            return;
+        }
+        for (const queued of this.queuedSockets.splice(0)) {
+            clearTimeout(queued.timeout);
+            this.transferSocket(worker, queued.socket);
+        }
+    }
+    transferSocket(worker, socket) {
+        try {
+            worker.handle.sendSocket(worker.generation, socket, (error) => {
+                if (error) {
+                    this.handleTransferFailure(worker, socket);
+                }
+            });
+        }
+        catch {
+            this.handleTransferFailure(worker, socket);
+        }
+    }
+    handleTransferFailure(worker, socket) {
+        this.failedTransfers += 1;
+        this.recordFailure(worker.generation, worker.version, "transfer", `worker ${worker.handle.pid} failed to accept a transferred socket`);
+        if (this.active?.generation === worker.generation && !this.closed) {
+            // Do not let worker-side graceful shutdown call shutdown(2) on an
+            // offered-but-uncommitted duplicate descriptor.
+            worker.dispose();
+            worker.handle.terminate("SIGKILL");
+            this.active = null;
+        }
+        this.rejectSocket(socket);
+    }
+    rejectSocket(socket) {
+        this.rejectedSockets += 1;
+        socket.destroy();
+        this.publishState();
+    }
+    recordFailure(generation, version, phase, message) {
+        this.lastFailure = {
+            at: new Date().toISOString(),
+            generation,
+            version,
+            phase,
+            message: message.slice(0, 1_000),
+        };
+    }
+    publishState() {
+        try {
+            this.options.onStateChange?.(this.snapshot());
+        }
+        catch (error) {
+            this.options.log?.(`[proxy-supervisor] failed to persist supervisor state: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=rollingWorkerSupervisor.js.map