@juspay/neurolink 12.14.5 → 12.14.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.14.5",
+  "version": "12.14.7",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -147,6 +147,7 @@
     "test:proxy": "pnpm exec tsx test/continuous-test-suite-proxy.ts",
     "test:proxy-connect-retry": "pnpm exec tsx test/continuous-test-suite-proxy-connect-retry.ts",
     "test:proxy-telemetry": "pnpm exec tsx test/continuous-test-suite-proxy-telemetry.ts",
+    "test:proxy-restart": "pnpm exec tsx test/continuous-test-suite-proxy-restart.ts",
     "test:codex": "pnpm exec tsx test/continuous-test-suite-codex.ts",
     "test:bugfixes": "pnpm exec tsx test/continuous-test-suite-bugfixes.ts",
     "test:json-e2e": "pnpm exec tsx test/continuous-test-suite-json-e2e.ts",

package/scripts/observability/check-proxy-telemetry.mjs

@@ -1,248 +1,36 @@
 #!/usr/bin/env node
-
-import { Buffer } from "node:buffer";
-import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-const DEFAULT_OPENOBSERVE_URL = "http://localhost:5080";
-const DEFAULT_OPENOBSERVE_ORG = "default";
-const DEFAULT_OPENOBSERVE_USER = "root@example.com";
-const DEFAULT_OPENOBSERVE_PASSWORD = "Complexpass#123";
-const DEFAULT_MAX_LAG_SECONDS = 900;
-const STREAMS_TO_CHECK = [
-  {
-    type: "logs",
-    name: process.env.NEUROLINK_PROXY_STREAM_HEADER || "neurolink_proxy",
-    label: "OpenObserve logs",
-  },
-  {
-    type: "traces",
-    name: process.env.NEUROLINK_PROXY_STREAM_HEADER || "neurolink_proxy",
-    label: "OpenObserve traces",
-  },
-  {
-    type: "metrics",
-    name: "proxy_requests_total",
-    label: "OpenObserve proxy metrics",
-  },
-];
-
-function getAuthHeader() {
-  if (process.env.NEUROLINK_OPENOBSERVE_BASIC_AUTH) {
-    return process.env.NEUROLINK_OPENOBSERVE_BASIC_AUTH;
-  }
-
-  const user =
-    process.env.NEUROLINK_OPENOBSERVE_USER || DEFAULT_OPENOBSERVE_USER;
-  const password =
-    process.env.NEUROLINK_OPENOBSERVE_PASSWORD || DEFAULT_OPENOBSERVE_PASSWORD;
-
-  return `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
-}
-
-function formatDate(micros) {
-  return new Date(Math.floor(micros / 1000)).toISOString();
-}
-
-function formatAgeSeconds(seconds) {
-  if (!Number.isFinite(seconds) || seconds < 0) {
-    return "n/a";
-  }
-  if (seconds < 60) {
-    return `${Math.round(seconds)}s`;
-  }
-  const minutes = seconds / 60;
-  if (minutes < 60) {
-    return `${Math.round(minutes)}m`;
-  }
-  const hours = minutes / 60;
-  return `${hours.toFixed(1)}h`;
-}
-
-function summarizeLag(ageSeconds, thresholdSeconds) {
-  if (!Number.isFinite(ageSeconds)) {
-    return "missing";
-  }
-  return ageSeconds <= thresholdSeconds ? "fresh" : "stale";
-}
-
-async function fetchStreams(type) {
-  const url = new URL(
-    `/api/${process.env.NEUROLINK_OPENOBSERVE_ORG || DEFAULT_OPENOBSERVE_ORG}/streams?type=${type}`,
-    process.env.NEUROLINK_OPENOBSERVE_URL || DEFAULT_OPENOBSERVE_URL,
-  );
-
-  const response = await fetch(url, {
-    signal: globalThis.AbortSignal.timeout(15_000),
-    headers: {
-      Authorization: getAuthHeader(),
-    },
-  });
-
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch ${type} streams: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const body = await response.json();
-  return body.list || [];
-}
-
-async function readLatestLocalSummary() {
-  const logsDir = join(homedir(), ".neurolink", "logs");
-  let entries;
-  try {
-    entries = await fs.readdir(logsDir);
-  } catch (err) {
-    if (err.code === "ENOENT") {
-      return null; // No log directory yet — fresh setup
-    }
-    throw err;
-  }
-  const files = entries
-    .filter((name) => /^proxy-\d{4}-\d{2}-\d{2}\.jsonl$/.test(name))
-    .sort()
-    .reverse();
-
-  for (const name of files) {
-    const path = join(logsDir, name);
-    let handle;
-    try {
-      handle = await fs.open(path, "r");
-    } catch (err) {
-      if (err.code === "ENOENT") {
-        continue;
-      }
-      throw err;
-    }
-    try {
-      const stats = await handle.stat();
-      const chunkSize = Math.min(stats.size, 64 * 1024);
-      const buffer = Buffer.alloc(chunkSize);
-      await handle.read(buffer, 0, chunkSize, stats.size - chunkSize);
-      const lines = buffer
-        .toString("utf8")
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean);
-      for (let i = lines.length - 1; i >= 0; i -= 1) {
-        try {
-          return JSON.parse(lines[i]);
-        } catch {
-          // ignore malformed tail line
-        }
-      }
-    } finally {
-      await handle.close();
-    }
-  }
-
-  return null;
-}
-
-async function main() {
-  const thresholdSeconds = Number(
-    process.env.NEUROLINK_PROXY_TELEMETRY_MAX_LAG_SEC ||
-      DEFAULT_MAX_LAG_SECONDS,
-  );
-  const nowMicros = Date.now() * 1000;
-
-  const groupedStreams = Object.fromEntries(
-    await Promise.all(
-      [...new Set(STREAMS_TO_CHECK.map((stream) => stream.type))].map(
-        async (type) => [type, await fetchStreams(type)],
-      ),
-    ),
-  );
-
-  const otelOnly = process.env.NEUROLINK_PROXY_LOG_SINK === "otel";
-  const localSummary = otelOnly ? null : await readLatestLocalSummary();
-  const localSummaryMicros = localSummary?.timestamp
-    ? new Date(localSummary.timestamp).getTime() * 1000
-    : null;
-
-  console.log("NeuroLink Proxy Telemetry Doctor");
-  console.log("================================");
-  console.log(
-    `OpenObserve: ${process.env.NEUROLINK_OPENOBSERVE_URL || DEFAULT_OPENOBSERVE_URL}`,
-  );
-  console.log(`Lag threshold: ${thresholdSeconds}s`);
-  console.log("");
-
-  let hasProblem = false;
-
-  for (const stream of STREAMS_TO_CHECK) {
-    const item = groupedStreams[stream.type]?.find(
-      (entry) => entry.name === stream.name,
-    );
-    const latestMicros = item?.stats?.doc_time_max ?? null;
-    const ageSeconds = latestMicros
-      ? Math.max(0, (nowMicros - latestMicros) / 1_000_000)
-      : Number.NaN;
-    const status = summarizeLag(ageSeconds, thresholdSeconds);
-    if (status !== "fresh") {
-      hasProblem = true;
-    }
-
-    console.log(`${stream.label}: ${status}`);
-    console.log(`  stream: ${stream.name}`);
-    console.log(
-      `  latest: ${latestMicros ? formatDate(latestMicros) : "missing"}`,
-    );
-    console.log(`  age: ${formatAgeSeconds(ageSeconds)}`);
-    console.log(`  docs: ${item?.stats?.doc_num ?? 0}`);
-  }
-
-  console.log("");
-  console.log("Local proxy summary log:");
-  if (otelOnly) {
+import { runProxyTelemetryDoctor } from "./proxy-telemetry-check.mjs";
+runProxyTelemetryDoctor().catch((error) => {
+  // JSON consumers must also get structured evidence when a service is
+  // unavailable. Do not echo parser excerpts from backend/configuration bodies.
+  const reason =
+    error instanceof SyntaxError
+      ? "Telemetry response or configuration is not valid"
+      : error instanceof Error
+        ? error.message
+        : "Telemetry verification failed";
+  if (process.argv.includes("json")) {
     console.log(
-      "  disabled (OTel-only mode); local file freshness is not a delivery check",
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          checkedAt: new Date().toISOString(),
+          status: "incomplete",
+          completeQuery: false,
+          checks: [
+            {
+              name: "verification",
+              status: "unverified",
+              evidence: { reason },
+            },
+          ],
+        },
+        null,
+        2,
+      ),
     );
-  } else if (!localSummary || !localSummaryMicros) {
-    console.log("  missing");
-    hasProblem = true;
   } else {
-    const ageSeconds = Math.max(
-      0,
-      (nowMicros - localSummaryMicros) / 1_000_000,
-    );
-    console.log(`  latest: ${localSummary.timestamp}`);
-    console.log(`  age: ${formatAgeSeconds(ageSeconds)}`);
-    console.log(`  requestId: ${localSummary.requestId}`);
-    console.log(`  status: ${localSummary.responseStatus}`);
-    console.log(`  accountType: ${localSummary.accountType}`);
-  }
-
-  if (localSummaryMicros) {
-    console.log("");
-    console.log("Lag vs local summary:");
-    for (const stream of STREAMS_TO_CHECK) {
-      const item = groupedStreams[stream.type]?.find(
-        (entry) => entry.name === stream.name,
-      );
-      const latestMicros = item?.stats?.doc_time_max ?? null;
-      const deltaSeconds = latestMicros
-        ? Math.abs(localSummaryMicros - latestMicros) / 1_000_000
-        : Number.NaN;
-      const status = summarizeLag(deltaSeconds, thresholdSeconds);
-      if (status !== "fresh") {
-        hasProblem = true;
-      }
-      console.log(
-        `  ${stream.name}: ${status} (${formatAgeSeconds(deltaSeconds)})`,
-      );
-    }
-  }
-
-  if (hasProblem) {
-    process.exitCode = 1;
+    console.error(reason);
   }
-}
-
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
   process.exitCode = 1;
 });

package/scripts/observability/proxy-telemetry-backend.mjs

@@ -0,0 +1,202 @@
+/** Backend query adapter for OTLP telemetry. OTLP itself has no history/query API. */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+/** Discover the existing native collector destination without exposing its credentials. */
+export async function resolveProxyTelemetryBackend(env = process.env) {
+  /** @type {import("../../src/lib/types/index.js").ProxyTelemetryNativeConfig | undefined} */
+  let native;
+  if (!env.NEUROLINK_OPENOBSERVE_URL) {
+    try {
+      native =
+        /** @type {import("../../src/lib/types/index.js").ProxyTelemetryNativeConfig} */ (
+          yaml.load(
+            await readFile(
+              env.NEUROLINK_OTEL_COLLECTOR_CONFIG ??
+                join(
+                  homedir(),
+                  ".neurolink",
+                  "telemetry-native",
+                  "config",
+                  "collector.yaml",
+                ),
+              "utf8",
+            ),
+          )
+        );
+    } catch (error) {
+      if (
+        !(error instanceof Error && "code" in error && error.code === "ENOENT")
+      ) {
+        throw new Error(
+          "Could not read the configured telemetry collector destination",
+          { cause: error },
+        );
+      }
+    }
+  }
+  const exporter = native?.exporters?.["otlphttp/openobserve"];
+  const destination = exporter?.endpoint
+    ? new URL(exporter.endpoint)
+    : undefined;
+  const nativeOrg = destination?.pathname.match(
+    /^\/api\/([a-zA-Z0-9_-]+)\/?$/,
+  )?.[1];
+  const authorization =
+    env.NEUROLINK_OPENOBSERVE_BASIC_AUTH ??
+    (env.NEUROLINK_OPENOBSERVE_USER && env.NEUROLINK_OPENOBSERVE_PASSWORD
+      ? `Basic ${Buffer.from(`${env.NEUROLINK_OPENOBSERVE_USER}:${env.NEUROLINK_OPENOBSERVE_PASSWORD}`).toString("base64")}`
+      : (exporter?.headers?.Authorization ?? exporter?.headers?.authorization));
+  return {
+    baseUrl:
+      env.NEUROLINK_OPENOBSERVE_URL ??
+      destination?.origin ??
+      "http://127.0.0.1:5080",
+    organization: env.NEUROLINK_OPENOBSERVE_ORG ?? nativeOrg ?? "default",
+    stream:
+      env.NEUROLINK_PROXY_STREAM_HEADER ??
+      exporter?.headers?.["stream-name"] ??
+      "neurolink_proxy",
+    authorization,
+    collectorMetricsUrl:
+      env.NEUROLINK_OTEL_COLLECTOR_METRICS_URL ??
+      (native ? "http://127.0.0.1:14388/metrics" : undefined),
+  };
+}
+
+/** Validate before issuing any diagnostics request.
+ * @param {import("../../src/lib/types/index.js").ProxyTelemetryBackend} backend
+ */
+export function validateProxyTelemetryBackend(backend) {
+  if (
+    !/^[a-zA-Z0-9_-]+$/.test(backend.organization) ||
+    !/^[a-zA-Z0-9_]+$/.test(backend.stream)
+  ) {
+    throw new Error("Invalid telemetry organization or stream");
+  }
+  const endpoint = new URL(backend.baseUrl);
+  if (
+    endpoint.username ||
+    endpoint.password ||
+    !["https:", "http:"].includes(endpoint.protocol)
+  ) {
+    throw new Error("Invalid telemetry endpoint");
+  }
+  if (
+    backend.authorization &&
+    endpoint.protocol !== "https:" &&
+    !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname)
+  ) {
+    throw new Error(
+      "Credentialed telemetry queries require HTTPS outside loopback",
+    );
+  }
+  if (backend.collectorMetricsUrl) {
+    const url = new URL(backend.collectorMetricsUrl);
+    if (
+      url.username ||
+      url.password ||
+      !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) ||
+      !["http:", "https:"].includes(url.protocol)
+    ) {
+      throw new Error("Collector diagnostics must use loopback HTTP(S)");
+    }
+  }
+}
+
+/** A bounded, complete search; no backend response body or authorization enters errors.
+ * @param {import("../../src/lib/types/index.js").ProxyTelemetryBackend} backend
+ * @param {import("../../src/lib/types/index.js").ProxyTelemetryQueryOptions} options
+ * @param {typeof fetch} fetchImpl
+ */
+export async function queryProxyTelemetry(
+  backend,
+  { sql, signal = "logs", startTime, endTime, size = 200, offset = 0 },
+  fetchImpl = fetch,
+) {
+  validateProxyTelemetryBackend(backend);
+  if (
+    !/^[a-zA-Z0-9_-]+$/.test(backend.organization) ||
+    !/^[a-zA-Z0-9_]+$/.test(backend.stream) ||
+    !["logs", "traces", "metrics"].includes(signal) ||
+    !Number.isSafeInteger(startTime) ||
+    !Number.isSafeInteger(endTime) ||
+    startTime >= endTime ||
+    !Number.isSafeInteger(size) ||
+    size < 1 ||
+    size > 1000 ||
+    !Number.isSafeInteger(offset) ||
+    offset < 0
+  ) {
+    throw new Error("Invalid bounded telemetry query");
+  }
+  const endpoint = new URL(
+    `/api/${backend.organization}/_search?type=${signal}`,
+    backend.baseUrl,
+  );
+  if (
+    endpoint.username ||
+    endpoint.password ||
+    !["https:", "http:"].includes(endpoint.protocol)
+  ) {
+    throw new Error("Invalid telemetry endpoint");
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(
+    endpoint.hostname,
+  );
+  if (backend.authorization && endpoint.protocol !== "https:" && !loopback) {
+    throw new Error(
+      "Credentialed telemetry queries require HTTPS outside loopback",
+    );
+  }
+  const started = globalThis.performance.now();
+  const response = await fetchImpl(endpoint, {
+    method: "POST",
+    redirect: "error",
+    signal: globalThis.AbortSignal.timeout(15_000),
+    headers: {
+      "Content-Type": "application/json",
+      ...(backend.authorization
+        ? { Authorization: backend.authorization }
+        : {}),
+    },
+    body: JSON.stringify({
+      query: {
+        sql,
+        start_time: startTime,
+        end_time: endTime - 1,
+        size,
+        from: offset,
+      },
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(`Telemetry query failed: HTTP ${response.status}`);
+  }
+  const data = await response.json();
+  if (
+    data.is_partial === true ||
+    (Array.isArray(data.function_error)
+      ? data.function_error.length
+      : data.function_error) ||
+    !Array.isArray(data.hits)
+  ) {
+    throw new Error("Telemetry query returned incomplete data");
+  }
+  return {
+    rows: /** @type {Array<Record<string, unknown>>} */ (data.hits),
+    query: {
+      sql,
+      signal,
+      startTime,
+      endTimeExclusive: endTime,
+      size,
+      offset,
+      rows: data.hits.length,
+      complete: true,
+      durationMs: Math.round(globalThis.performance.now() - started),
+    },
+  };
+}