@juspay/neurolink 12.17.1 → 12.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.17.1",
+  "version": "12.17.2",
   "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": {
@@ -153,6 +153,7 @@
     "test:dynamic": "pnpm exec tsx test/continuous-test-suite-dynamic.ts",
     "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-reliability": "node scripts/run-proxy-reliability.mjs",
     "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",
@@ -391,6 +392,7 @@
     "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/otlp-transformer": "^0.214.0",
     "@opentelemetry/resources": "^2.6.0",
     "@opentelemetry/sdk-logs": "^0.214.0",
     "@opentelemetry/sdk-metrics": "^2.6.1",

package/scripts/observability/NATIVE-DURABLE.md

@@ -0,0 +1,63 @@
+# Native collector queues and body separation
+
+`otel-collector.proxy-native-durable.yaml` is an opt-in profile for
+`otelcol-contrib >= 0.160.0`. It does not install, replace, or restart a service.
+Application logs remain OTLP-only. Collector retry storage writes a bounded
+queue to disk so records accepted into that queue survive a collector restart.
+
+Configure these variables in the collector service environment:
+
+- `NEUROLINK_OPENOBSERVE_OTLP_ENDPOINT`: backend API endpoint, for example
+  `http://127.0.0.1:5080/api/default` (use TLS outside loopback).
+- `NEUROLINK_OPENOBSERVE_BASIC_AUTH`: backend authorization, supplied privately.
+- `NEUROLINK_OTEL_QUEUE_DIRECTORY` and `NEUROLINK_OTEL_COMPACTION_DIRECTORY`:
+  private directories on a volume with an operator-managed disk quota.
+- `NEUROLINK_PROXY_STREAM_HEADER=neurolink_proxy` and
+  `NEUROLINK_PROXY_BODY_STREAM_HEADER=neurolink_proxy_bodies`.
+
+Configure the proxy service with `NEUROLINK_PROXY_LOG_SINK=otel`,
+`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://127.0.0.1:14318/v1/logs` and
+`NEUROLINK_PROXY_OTLP_BODIES_ENDPOINT=http://127.0.0.1:14319/v1/logs`.
+Configure the doctor's environment with the same two stream variables, or point
+`NEUROLINK_OTEL_COLLECTOR_CONFIG` at this collector's resolved configuration.
+Without a separate body endpoint/stream, existing single-stream deployments
+continue to work.
+
+The profile isolates metadata and bulk body queues and backend streams. There is
+no volatile batch processor before the persistent exporter queue: receiver
+success follows persistent enqueue rather than a timer-buffered batch. Proxy
+chunk batching still reduces transport calls. Queues use a 32 MiB metadata byte
+limit per signal and a 256 MiB body byte limit, plus in-flight requests and
+storage/index overhead. Compaction reclaims consumed pages. These are payload
+bounds, not a hard filesystem size cap; apply a volume quota and monitor free
+space. Backend retention should be configured separately for each stream.
+
+Disk-full errors, queue saturation, invalid records, process crashes before
+persistent enqueue, and permanent backend rejection can still lose records.
+Retry queues retry transient errors indefinitely until delivered or storage
+limits are reached. A transport acknowledgment is not proof of backend
+persistence or exactly-once delivery; use stable event IDs to deduplicate
+retries. Retrying after ambiguous network acknowledgment can create duplicates.
+
+Validate a profile before an authorized activation:
+
+```sh
+otelcol-contrib validate --config scripts/observability/otel-collector.proxy-native-durable.yaml
+```
+
+The isolated recovery test starts its own collector on random loopback ports,
+uses a temporary queue directory and a fake backend, forces an outage, kills
+only that test-owned collector process, restarts it with the same directory,
+and verifies replay. It never operates an installed service:
+
+```sh
+NEUROLINK_TEST_OTELCOL_BIN=/absolute/path/to/otelcol-contrib \
+  pnpm exec tsx test/continuous-test-suite-proxy-capture-pipeline.ts
+```
+
+The doctor's admission reconciliation searches a bounded lookback (24 hours by
+default), applies per-request deadlines where logged, and gives late ingestion
+120 seconds before flagging missing endings. Use `--admission-lookback-minutes`
+and `--max-rows` to select an explicit wider proof; exceeding row/query budgets
+is incomplete evidence, never a green result. Request success remains separate
+from capture admission, worker processing, publication and exporter transport.

package/scripts/observability/otel-collector.proxy-native-durable.yaml

@@ -0,0 +1,93 @@
+# Opt-in native collector profile (otelcol-contrib >= 0.160.0).
+# This persists collector retry queues, never application log files. Configure a
+# private directory and a filesystem quota; queue byte bounds exclude DB overhead.
+receivers:
+  otlp/metadata:
+    protocols:
+      http:
+        endpoint: ${env:NEUROLINK_OTEL_METADATA_LISTEN:-127.0.0.1:14318}
+  otlp/bodies:
+    protocols:
+      http:
+        endpoint: ${env:NEUROLINK_OTEL_BODIES_LISTEN:-127.0.0.1:14319}
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 256
+    spike_limit_mib: 64
+exporters:
+  otlphttp/openobserve:
+    endpoint: ${env:NEUROLINK_OPENOBSERVE_OTLP_ENDPOINT}
+    encoding: json
+    headers:
+      Authorization: ${env:NEUROLINK_OPENOBSERVE_BASIC_AUTH}
+      stream-name: ${env:NEUROLINK_PROXY_STREAM_HEADER:-neurolink_proxy}
+    retry_on_failure:
+      enabled: true
+      initial_interval: 1s
+      max_interval: 30s
+      max_elapsed_time: 0s
+    sending_queue:
+      enabled: true
+      num_consumers: 2
+      sizer: bytes
+      queue_size: 33554432
+      storage: file_storage
+  otlphttp/openobserve-bodies:
+    endpoint: ${env:NEUROLINK_OPENOBSERVE_OTLP_ENDPOINT}
+    encoding: json
+    headers:
+      Authorization: ${env:NEUROLINK_OPENOBSERVE_BASIC_AUTH}
+      stream-name: ${env:NEUROLINK_PROXY_BODY_STREAM_HEADER:-neurolink_proxy_bodies}
+    retry_on_failure:
+      enabled: true
+      initial_interval: 1s
+      max_interval: 30s
+      max_elapsed_time: 0s
+    sending_queue:
+      enabled: true
+      num_consumers: 2
+      sizer: bytes
+      queue_size: 268435456
+      storage: file_storage
+extensions:
+  file_storage:
+    directory: ${env:NEUROLINK_OTEL_QUEUE_DIRECTORY}
+    create_directory: true
+    fsync: true
+    compaction:
+      on_start: true
+      on_rebound: true
+      directory: ${env:NEUROLINK_OTEL_COMPACTION_DIRECTORY}
+  health_check:
+    endpoint: ${env:NEUROLINK_OTEL_HEALTH_LISTEN:-127.0.0.1:14333}
+service:
+  extensions: [file_storage, health_check]
+  pipelines:
+    logs/metadata:
+      receivers: [otlp/metadata]
+      processors: [memory_limiter]
+      exporters: [otlphttp/openobserve]
+    logs/bodies:
+      receivers: [otlp/bodies]
+      processors: [memory_limiter]
+      exporters: [otlphttp/openobserve-bodies]
+    traces:
+      receivers: [otlp/metadata]
+      processors: [memory_limiter]
+      exporters: [otlphttp/openobserve]
+    metrics:
+      receivers: [otlp/metadata]
+      processors: [memory_limiter]
+      exporters: [otlphttp/openobserve]
+  telemetry:
+    logs:
+      level: warn
+    metrics:
+      level: detailed
+      readers:
+        - pull:
+            exporter:
+              prometheus:
+                host: "127.0.0.1"
+                port: ${env:NEUROLINK_OTEL_METRICS_PORT:-14388}

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

@@ -37,9 +37,25 @@ export async function resolveProxyTelemetryBackend(env = process.env) {
       }
     }
   }
+  /** Resolve collector environment substitutions without logging their values.
+   * @param {string | undefined} value
+   */
+  const resolveCollectorValue = (value) =>
+    value?.replace(
+      /\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g,
+      (_match, name, fallback) => {
+        const resolved = env[name] ?? fallback;
+        if (resolved === undefined)
+          {throw new Error(
+            `Collector environment variable ${name} is not configured`,
+          );}
+        return resolved;
+      },
+    );
   const exporter = native?.exporters?.["otlphttp/openobserve"];
-  const destination = exporter?.endpoint
-    ? new URL(exporter.endpoint)
+  const configuredEndpoint = resolveCollectorValue(exporter?.endpoint);
+  const destination = configuredEndpoint
+    ? new URL(configuredEndpoint)
     : undefined;
   const nativeOrg = destination?.pathname.match(
     /^\/api\/([a-zA-Z0-9_-]+)\/?$/,
@@ -48,7 +64,9 @@ export async function resolveProxyTelemetryBackend(env = process.env) {
     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));
+      : resolveCollectorValue(
+          exporter?.headers?.Authorization ?? exporter?.headers?.authorization,
+        ));
   return {
     baseUrl:
       env.NEUROLINK_OPENOBSERVE_URL ??
@@ -57,8 +75,15 @@ export async function resolveProxyTelemetryBackend(env = process.env) {
     organization: env.NEUROLINK_OPENOBSERVE_ORG ?? nativeOrg ?? "default",
     stream:
       env.NEUROLINK_PROXY_STREAM_HEADER ??
-      exporter?.headers?.["stream-name"] ??
+      resolveCollectorValue(exporter?.headers?.["stream-name"]) ??
       "neurolink_proxy",
+    bodyStream:
+      env.NEUROLINK_PROXY_BODY_STREAM_HEADER ??
+      resolveCollectorValue(
+        native?.exporters?.["otlphttp/openobserve-bodies"]?.headers?.[
+          "stream-name"
+        ],
+      ),
     authorization,
     collectorMetricsUrl:
       env.NEUROLINK_OTEL_COLLECTOR_METRICS_URL ??
@@ -72,7 +97,9 @@ export async function resolveProxyTelemetryBackend(env = process.env) {
 export function validateProxyTelemetryBackend(backend) {
   if (
     !/^[a-zA-Z0-9_-]+$/.test(backend.organization) ||
-    !/^[a-zA-Z0-9_]+$/.test(backend.stream)
+    !/^[a-zA-Z0-9_]+$/.test(backend.stream) ||
+    (backend.bodyStream !== undefined &&
+      !/^[a-zA-Z0-9_]+$/.test(backend.bodyStream))
   ) {
     throw new Error("Invalid telemetry organization or stream");
   }