@juspay/neurolink 12.17.1 → 12.17.2

package/dist/proxy/globalInstaller.js

@@ -1,7 +1,9 @@
-import { execFileSync as nodeExecFileSync } from "node:child_process";
-import { accessSync, constants, existsSync, realpathSync } from "node:fs";
+import { execFileSync as nodeExecFileSync, spawn as nodeSpawn, } from "node:child_process";
+import { accessSync, constants, existsSync, realpathSync, readFileSync, mkdirSync, writeFileSync, renameSync, chmodSync, rmSync, } from "node:fs";
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, isAbsolute, join, resolve, relative, } from "node:path";
 function runText(execFileSync, bin, args) {
     return String(execFileSync(bin, args, {
         encoding: "utf8",
@@ -246,3 +248,384 @@ export function describeInstallFailure(error) {
         .filter(Boolean)
         .join("\n");
 }
+/** Read package metadata without importing the CLI/provider/telemetry graph. */
+export function inspectProxyPackage(entryScript, nodePath = process.execPath) {
+    const entry = realpathSync(entryScript);
+    let directory = dirname(entry);
+    while (true) {
+        const manifestPath = join(directory, "package.json");
+        if (existsSync(manifestPath)) {
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            if (manifest.name === "@juspay/neurolink") {
+                if (typeof manifest.version !== "string" ||
+                    !/^\d+\.\d+\.\d+$/.test(manifest.version)) {
+                    throw new Error("Invalid proxy package version");
+                }
+                return { version: manifest.version, entryScript: entry, nodePath };
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            throw new Error("Proxy entrypoint has no package manifest");
+        }
+        directory = parent;
+    }
+}
+function validateProxyPackageSelection(value) {
+    try {
+        if (!value || typeof value !== "object") {
+            return null;
+        }
+        const selection = value;
+        if (typeof selection.entryScript !== "string" ||
+            typeof selection.nodePath !== "string" ||
+            !isAbsolute(selection.entryScript) ||
+            !isAbsolute(selection.nodePath)) {
+            return null;
+        }
+        const actual = inspectProxyPackage(selection.entryScript, selection.nodePath);
+        return actual.version === selection.version ? actual : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read active and rollback selections from one committed generation. */
+function readProxyPackageSelections(packagesDir) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(join(packagesDir, "selections.json"), "utf8"));
+    }
+    catch (error) {
+        // Legacy migration is allowed only when no atomic record has ever been
+        // published. Invalid/unreadable committed state must not revive stale files.
+        if (error.code !== "ENOENT") {
+            return null;
+        }
+        const readLegacy = (file) => {
+            try {
+                return validateProxyPackageSelection(JSON.parse(readFileSync(join(packagesDir, file), "utf8")));
+            }
+            catch {
+                return null;
+            }
+        };
+        return {
+            schemaVersion: 1,
+            active: readLegacy("active.json"),
+            previous: readLegacy("previous.json"),
+        };
+    }
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const state = value;
+    if (state.schemaVersion !== 1 ||
+        !("active" in state) ||
+        !("previous" in state)) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        active: validateProxyPackageSelection(state.active),
+        previous: validateProxyPackageSelection(state.previous),
+    };
+}
+export function readProxyPackageSelection(packagesDir, previous = false) {
+    const state = readProxyPackageSelections(packagesDir);
+    return (previous ? state?.previous : state?.active) ?? null;
+}
+/** Resolve immutable selections before consulting an older mutable global entry. */
+export function resolveProxyWorkerPackage(options) {
+    const state = readProxyPackageSelections(options.packagesDir);
+    for (const selection of [state?.active, state?.previous]) {
+        if (selection?.version === options.expectedVersion) {
+            return selection;
+        }
+    }
+    try {
+        const original = inspectProxyPackage(options.entryScript);
+        if (original.version === options.expectedVersion) {
+            return original;
+        }
+    }
+    catch {
+        // A global upgrade/removal may invalidate the original entry while an
+        // already selected private package remains the valid recovery target.
+    }
+    throw new Error(`No validated package selection for worker v${options.expectedVersion}`);
+}
+function assertPackageSelectionOwner(isCurrentOwner) {
+    if (isCurrentOwner && !isCurrentOwner()) {
+        throw new Error("Proxy update owner changed; package selection was not modified");
+    }
+}
+/** Persist only package selection; runtime env, config and launchd settings are untouched. */
+export function selectProxyPackage(packagesDir, selection, isCurrentOwner) {
+    assertPackageSelectionOwner(isCurrentOwner);
+    mkdirSync(packagesDir, { recursive: true, mode: 0o700 });
+    const current = readProxyPackageSelections(packagesDir);
+    if (!current) {
+        throw new Error("Proxy package selection state is unreadable or invalid");
+    }
+    // Manifest reads can outlive a service owner, even before private staging.
+    assertPackageSelectionOwner(isCurrentOwner);
+    const state = {
+        schemaVersion: 1,
+        active: selection,
+        previous: current.active && current.active.version !== selection.version
+            ? current.active
+            : current.previous,
+    };
+    const temporary = join(packagesDir, `selections-${process.pid}-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, JSON.stringify(state), {
+            mode: 0o600,
+            flag: "wx",
+        });
+        assertPackageSelectionOwner(isCurrentOwner);
+        // One rename publishes both versions. A stale owner never mutates rollback
+        // state independently, and must never attempt to restore a newer owner's state.
+        renameSync(temporary, join(packagesDir, "selections.json"));
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/** No startup probes: IPC descriptors and OTel initialization belong to the real process. */
+export function writeProxyPackageLauncher(path, selection, isCurrentOwner) {
+    assertPackageSelectionOwner(isCurrentOwner);
+    const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    // --version reads the manifest in a tiny isolated Node process. This proves
+    // the selected files still exist without cold-loading every provider twice.
+    const probe = `const fs=require('node:fs');let p=${JSON.stringify(dirname(selection.entryScript))};for(;;){const f=p+'/package.json';if(fs.existsSync(f)){const m=JSON.parse(fs.readFileSync(f,'utf8'));if(m.name==='@juspay/neurolink'){if(m.version!==${JSON.stringify(selection.version)})process.exit(1);console.log(m.version);break;}}const q=require('node:path').dirname(p);if(q===p)process.exit(1);p=q;}`;
+    const script = `#!/bin/sh\n# Generated proxy package selection. Service environment is inherited.\n[ -f ${quote(selection.entryScript)} ] || exit 127\nif [ "$#" = "1" ] && [ "$1" = "--version" ]; then\n  exec ${quote(selection.nodePath)} -e ${quote(probe)}\nfi\nexec ${quote(selection.nodePath)} ${quote(selection.entryScript)} "$@"\n`;
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, script, { mode: 0o755 });
+    chmodSync(temporary, 0o755);
+    assertPackageSelectionOwner(isCurrentOwner);
+    renameSync(temporary, path);
+}
+/** Install in a private tree, then publish the immutable directory after validation. */
+export async function installStagedProxyPackage(options) {
+    if (!/^\d+\.\d+\.\d+$/.test(options.version)) {
+        throw new Error("Invalid proxy package version");
+    }
+    await mkdir(options.packagesDir, { recursive: true, mode: 0o700 });
+    const destination = join(options.packagesDir, options.version);
+    const validate = (root) => {
+        const packageRoot = join(root, "node_modules", "@juspay", "neurolink");
+        const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.neurolink;
+        if (!bin) {
+            throw new Error("Candidate package is missing its neurolink executable");
+        }
+        const entry = realpathSync(resolve(packageRoot, bin));
+        const rel = relative(realpathSync(packageRoot), entry);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            throw new Error("Candidate executable escapes its package");
+        }
+        const selection = inspectProxyPackage(entry);
+        if (selection.version !== options.version) {
+            throw new Error(`Candidate version ${selection.version} does not match ${options.version}`);
+        }
+        (options.execFileSync ?? nodeExecFileSync)(selection.nodePath, ["--check", selection.entryScript], { timeout: 10_000, stdio: "pipe" });
+        return selection;
+    };
+    if (existsSync(destination)) {
+        return validate(destination);
+    }
+    const staging = await mkdtemp(join(options.packagesDir, `.install-${options.version}-`));
+    try {
+        await writeFile(join(staging, "package.json"), JSON.stringify({ private: true }), { mode: 0o600 });
+        const spec = `@juspay/neurolink@${options.version}`;
+        const args = options.installer.kind === "npm"
+            ? [
+                "install",
+                "--prefix",
+                staging,
+                "--no-save",
+                "--package-lock=false",
+                "--no-audit",
+                "--no-fund",
+                "--omit=dev",
+                "--loglevel=http",
+                spec,
+            ]
+            : [
+                "add",
+                "--dir",
+                staging,
+                "--no-lockfile",
+                "--prod",
+                "--reporter=ndjson",
+                spec,
+            ];
+        await new Promise((resolveInstall, rejectInstall) => {
+            const started = Date.now();
+            let lastProgress = started;
+            let bytes = 0;
+            let failureCode;
+            let failure;
+            let killTimer;
+            const child = (options.spawn ?? nodeSpawn)(options.installer.bin, args, {
+                cwd: staging,
+                env: { ...process.env, npm_config_update_notifier: "false" },
+                stdio: ["ignore", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+            });
+            const progress = (chunk) => {
+                bytes += Buffer.byteLength(chunk);
+                lastProgress = Date.now();
+                // Retain a machine code only: npm output can include authenticated URLs.
+                const text = String(chunk);
+                const code = text.match(/npm (?:ERR!|error) code ([A-Z][A-Z0-9_]+)/)?.[1] ??
+                    text.match(/\b(?:ECONNRESET|ECONNREFUSED|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|ENOTFOUND|EPIPE|ETIMEDOUT)\b/)?.[0];
+                if (code) {
+                    failureCode = code;
+                }
+            };
+            child.stdout?.on("data", progress);
+            child.stderr?.on("data", progress);
+            const signal = (value) => {
+                try {
+                    if (process.platform !== "win32" && child.pid) {
+                        process.kill(-child.pid, value);
+                    }
+                    else {
+                        child.kill(value);
+                    }
+                }
+                catch {
+                    /* child already exited */
+                }
+            };
+            const interval = setInterval(() => {
+                const now = Date.now();
+                options.onProgress?.({
+                    elapsedMs: now - started,
+                    outputBytes: bytes,
+                });
+                if (!failure &&
+                    (now - started >= (options.maxDurationMs ?? 15 * 60_000) ||
+                        now - lastProgress >= (options.idleTimeoutMs ?? 120_000))) {
+                    failure = Object.assign(new Error(`Staged install timed out after ${now - started}ms (${bytes} output bytes, idle ${now - lastProgress}ms)`), { code: "ETIMEDOUT" });
+                    signal("SIGTERM");
+                    killTimer = setTimeout(() => signal("SIGKILL"), options.killGraceMs ?? 5_000);
+                }
+            }, Math.min(5_000, Math.max(10, (options.idleTimeoutMs ?? 120_000) / 4)));
+            const cleanup = () => {
+                clearInterval(interval);
+                clearTimeout(killTimer);
+            };
+            child.once("error", (error) => {
+                cleanup();
+                rejectInstall(error);
+            });
+            child.once("close", (code, signalName) => {
+                cleanup();
+                if (failure) {
+                    rejectInstall(failure);
+                }
+                else if (code !== 0) {
+                    rejectInstall(Object.assign(new Error(`Staged install exited code=${code} signal=${signalName ?? "none"} errorCode=${failureCode ?? "unknown"}`), {
+                        code: failureCode ??
+                            (code === null ? "ECONNRESET" : "INSTALL_FAILED"),
+                    }));
+                }
+                else {
+                    resolveInstall();
+                }
+            });
+        });
+        validate(staging);
+        await rename(staging, destination);
+        return validate(destination);
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+/** Only operator runtime settings survive reinstall, never worker IPC identity. */
+export function isProxyServiceEnvironmentKey(name) {
+    return ((name.startsWith("OTEL_") ||
+        name.startsWith("NEUROLINK_PROXY_") ||
+        [
+            "NEUROLINK_PACKAGE_MANAGER",
+            "NEUROLINK_PACKAGE_MANAGER_PATH",
+            "NEUROLINK_PNPM_PATH",
+            "PNPM_HOME",
+        ].includes(name)) &&
+        ![
+            "NEUROLINK_PROXY_SOCKET_WORKER",
+            "NEUROLINK_PROXY_WORKER_GENERATION",
+            "NEUROLINK_PROXY_WORKER_EXPECTED_VERSION",
+            "NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN",
+            "NEUROLINK_PROXY_ROLLING_SUPERVISOR",
+            "NEUROLINK_PROXY_TRAMPOLINE_EXEC_ONLY",
+            "NEUROLINK_PROXY_TEST_ISOLATED",
+        ].includes(name));
+}
+/** Parse plutil JSON without exposing credentials or invoking the saved launcher. */
+export function parseProxyServiceInstallSettings(value) {
+    const settings = { environment: {} };
+    if (!value || typeof value !== "object") {
+        return settings;
+    }
+    const plist = value;
+    const args = Array.isArray(plist.ProgramArguments)
+        ? plist.ProgramArguments
+        : [];
+    const option = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 && typeof args[index + 1] === "string"
+            ? args[index + 1]
+            : undefined;
+    };
+    settings.envFile = option("--env-file");
+    settings.configFile = option("--config");
+    settings.host = option("--host");
+    const port = Number(option("--port"));
+    if (Number.isInteger(port) && port > 0 && port <= 65535) {
+        settings.port = port;
+    }
+    if (plist.EnvironmentVariables &&
+        typeof plist.EnvironmentVariables === "object") {
+        for (const [name, entry] of Object.entries(plist.EnvironmentVariables)) {
+            if (isProxyServiceEnvironmentKey(name) && typeof entry === "string") {
+                settings.environment[name] = entry;
+            }
+        }
+    }
+    return settings;
+}
+/** Distinguish an absent launchd job from permission failures without logging plist/env data. */
+export function probeProxyLaunchdPresence(options) {
+    try {
+        (options.execFileSync ?? nodeExecFileSync)("launchctl", ["print", `gui/${options.uid}/${options.label}`], { encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "pipe"] });
+        // A loaded but currently idle KeepAlive job can start immediately. It must
+        // be explicitly unloaded before regenerating its launcher and environment.
+        return "loaded";
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "status" in error &&
+            error.status === 113 &&
+            "stderr" in error &&
+            /could not find service/i.test(String(error.stderr))) {
+            return "not_loaded";
+        }
+        return "unknown";
+    }
+}
+/** Read-only guard: callers must run this before every reinstall mutation. */
+export function assertProxyServiceInstallIdle(options) {
+    if (options.launchdPresence !== "not_loaded" ||
+        options.pids.some((pid) => Number.isSafeInteger(pid) &&
+            pid > 0 &&
+            options.getProcessStatus(pid) !== "not_running")) {
+        throw new Error("Proxy service is running or could still run. Reinstall was refused before changing files or processes. Use 'neurolink proxy restart' for a safe rolling replacement, or explicitly stop and unload the service before an intended reinstall.");
+    }
+}

package/dist/proxy/otelLogSink.d.ts

@@ -3,9 +3,9 @@ import type { ProxyBodyChunkEmitter, ProxyBodyDeliveryResult } from "../types/in
 /** Explicit opt-in; configuration never silently falls back to file logging. */
 export declare function isProxyOtelOnly(): boolean;
 /**
- * Own a whole capture within byte/count bounds, then pace its chunks by actual
- * export callbacks. SDK forceFlush alone does not await an automatic export
- * already in flight. Serial publication prevents bursts from dropping tails.
+ * Publish bounded captures concurrently into a shared batch queue. Transport
+ * callbacks settle each chunk once; a flush is a process fence, not a per-body
+ * network round trip. Metadata has a separate queue and transport.
  */
 export declare function publishProxyOtelBody(captureId: string, body: string, emit: ProxyBodyChunkEmitter): Promise<ProxyBodyDeliveryResult>;
 /** Initialize a log-only provider in every proxy process, including the supervisor. */