@ripplo/instrument 0.7.0

package/LICENSE.md

@@ -0,0 +1 @@
+© Ripplo LLC. All rights reserved. Use is subject to Ripplo's [Terms of Service](https://ripplo.ai/terms).

package/README.md

@@ -0,0 +1,30 @@
+# @ripplo/instrument
+
+Server-side OpenTelemetry preload for [Ripplo](https://ripplo.ai). Load it in your app server during development and every test run's `behavior.jsonl` includes your backend spans — HTTP handlers, outbound fetches, queue work — correlated to the browser actions that triggered them.
+
+## Usage
+
+Preload it when starting your dev server:
+
+```sh
+node --import @ripplo/instrument server.js
+tsx watch --import @ripplo/instrument src/index.ts
+NODE_OPTIONS="--import @ripplo/instrument" next dev
+```
+
+Frameworks with a register hook (Next.js `instrumentation.ts`) can call it directly:
+
+```ts
+import { register } from "@ripplo/instrument/register";
+register();
+```
+
+## How it works
+
+The preload starts a NodeSDK with auto-instrumentation and exports spans over OTLP to the Ripplo daemon's local receiver. The receiver's port is discovered through `.ripplo/.local/otlp-port`, written by `ripplo daemon` for the lifetime of your dev session. When the daemon isn't running, spans are dropped and your server runs as if the preload weren't there — safe to leave in your dev script permanently.
+
+Installed by `npx ripplo init`. See the [`ripplo` CLI](https://www.npmjs.com/package/ripplo) for setup.
+
+## License
+
+© Ripplo LLC. All rights reserved. Use is subject to Ripplo's [Terms of Service](https://ripplo.ai/terms).

package/dist/index.js

@@ -0,0 +1,145 @@
+// src/register.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import {
+  CompositePropagator,
+  ExportResultCode,
+  W3CBaggagePropagator,
+  W3CTraceContextPropagator
+} from "@opentelemetry/core";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import { propagation } from "@opentelemetry/api";
+import { z } from "zod";
+var REQUIRE_PARENT = { requireParentSpan: true };
+var BAGGAGE_ATTRIBUTE_KEYS = ["ripplo.run"];
+var ENDPOINT_CACHE_TTL_MS = 1e3;
+var started = false;
+function register() {
+  if (started) {
+    return;
+  }
+  started = true;
+  const sdk = new NodeSDK({
+    instrumentations: [
+      getNodeAutoInstrumentations({
+        "@opentelemetry/instrumentation-dns": { enabled: false },
+        "@opentelemetry/instrumentation-fs": { enabled: false },
+        "@opentelemetry/instrumentation-graphql": { enabled: false },
+        "@opentelemetry/instrumentation-ioredis": REQUIRE_PARENT,
+        "@opentelemetry/instrumentation-mongodb": REQUIRE_PARENT,
+        "@opentelemetry/instrumentation-net": { enabled: false },
+        "@opentelemetry/instrumentation-pg": { enabled: false },
+        "@opentelemetry/instrumentation-redis": REQUIRE_PARENT
+      })
+    ],
+    spanLimits: { attributeValueLengthLimit: 300 },
+    spanProcessors: [
+      new BaggageAttributeSpanProcessor(new BatchSpanProcessor(new LazyOtlpExporter()))
+    ],
+    textMapPropagator: new CompositePropagator({
+      propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()]
+    })
+  });
+  sdk.start();
+}
+var portSchema = z.coerce.number().int().positive();
+var LazyOtlpExporter = class {
+  cached;
+  delegate;
+  portFile = resolvePortFile();
+  export(spans, resultCallback) {
+    const url = this.resolveUrl();
+    if (url == null) {
+      resultCallback({ code: ExportResultCode.SUCCESS });
+      return;
+    }
+    this.exporterFor(url).export(spans, resultCallback);
+  }
+  forceFlush() {
+    return this.delegate?.exporter.forceFlush() ?? Promise.resolve();
+  }
+  shutdown() {
+    return this.delegate?.exporter.shutdown() ?? Promise.resolve();
+  }
+  resolveUrl() {
+    const override = process.env["RIPPLO_OTLP_ENDPOINT"];
+    if (override != null) {
+      return override;
+    }
+    const now = Date.now();
+    if (this.cached != null && now - this.cached.checkedAt < ENDPOINT_CACHE_TTL_MS) {
+      return this.cached.url;
+    }
+    this.cached = { checkedAt: now, url: readEndpoint(this.portFile) };
+    return this.cached.url;
+  }
+  exporterFor(url) {
+    if (this.delegate?.url !== url) {
+      void this.delegate?.exporter.shutdown();
+      this.delegate = { exporter: new OTLPTraceExporter({ url }), url };
+    }
+    return this.delegate.exporter;
+  }
+};
+function readEndpoint(portFile) {
+  if (portFile == null) {
+    return void 0;
+  }
+  const raw = readPortFile(portFile);
+  if (raw == null) {
+    return void 0;
+  }
+  const parsed = portSchema.safeParse(raw.trim());
+  return parsed.success ? `http://localhost:${String(parsed.data)}/v1/traces` : void 0;
+}
+function readPortFile(portFile) {
+  try {
+    return readFileSync(portFile, { encoding: "utf8" });
+  } catch {
+    return void 0;
+  }
+}
+function resolvePortFile() {
+  const root = findRipploRoot(process.cwd());
+  return root == null ? void 0 : path.join(root, ".ripplo", ".local", "otlp-port");
+}
+function findRipploRoot(dir) {
+  if (existsSync(path.join(dir, ".ripplo", "project.json"))) {
+    return dir;
+  }
+  const parent = path.dirname(dir);
+  return parent === dir ? void 0 : findRipploRoot(parent);
+}
+var BaggageAttributeSpanProcessor = class {
+  inner;
+  constructor(inner) {
+    this.inner = inner;
+  }
+  onStart(span, parentContext) {
+    const baggage = propagation.getBaggage(parentContext);
+    if (baggage != null) {
+      BAGGAGE_ATTRIBUTE_KEYS.forEach((key) => {
+        const entry = baggage.getEntry(key);
+        if (entry != null) {
+          span.setAttribute(key, entry.value);
+        }
+      });
+    }
+    this.inner.onStart(span, parentContext);
+  }
+  onEnd(span) {
+    this.inner.onEnd(span);
+  }
+  forceFlush() {
+    return this.inner.forceFlush();
+  }
+  shutdown() {
+    return this.inner.shutdown();
+  }
+};
+
+// src/index.ts
+register();

package/dist/register.d.ts

@@ -0,0 +1,3 @@
+declare function register(): void;
+
+export { register };

package/dist/register.js

@@ -0,0 +1,145 @@
+// src/register.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import {
+  CompositePropagator,
+  ExportResultCode,
+  W3CBaggagePropagator,
+  W3CTraceContextPropagator
+} from "@opentelemetry/core";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import { propagation } from "@opentelemetry/api";
+import { z } from "zod";
+var REQUIRE_PARENT = { requireParentSpan: true };
+var BAGGAGE_ATTRIBUTE_KEYS = ["ripplo.run"];
+var ENDPOINT_CACHE_TTL_MS = 1e3;
+var started = false;
+function register() {
+  if (started) {
+    return;
+  }
+  started = true;
+  const sdk = new NodeSDK({
+    instrumentations: [
+      getNodeAutoInstrumentations({
+        "@opentelemetry/instrumentation-dns": { enabled: false },
+        "@opentelemetry/instrumentation-fs": { enabled: false },
+        "@opentelemetry/instrumentation-graphql": { enabled: false },
+        "@opentelemetry/instrumentation-ioredis": REQUIRE_PARENT,
+        "@opentelemetry/instrumentation-mongodb": REQUIRE_PARENT,
+        "@opentelemetry/instrumentation-net": { enabled: false },
+        "@opentelemetry/instrumentation-pg": { enabled: false },
+        "@opentelemetry/instrumentation-redis": REQUIRE_PARENT
+      })
+    ],
+    spanLimits: { attributeValueLengthLimit: 300 },
+    spanProcessors: [
+      new BaggageAttributeSpanProcessor(new BatchSpanProcessor(new LazyOtlpExporter()))
+    ],
+    textMapPropagator: new CompositePropagator({
+      propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()]
+    })
+  });
+  sdk.start();
+}
+var portSchema = z.coerce.number().int().positive();
+var LazyOtlpExporter = class {
+  cached;
+  delegate;
+  portFile = resolvePortFile();
+  export(spans, resultCallback) {
+    const url = this.resolveUrl();
+    if (url == null) {
+      resultCallback({ code: ExportResultCode.SUCCESS });
+      return;
+    }
+    this.exporterFor(url).export(spans, resultCallback);
+  }
+  forceFlush() {
+    return this.delegate?.exporter.forceFlush() ?? Promise.resolve();
+  }
+  shutdown() {
+    return this.delegate?.exporter.shutdown() ?? Promise.resolve();
+  }
+  resolveUrl() {
+    const override = process.env["RIPPLO_OTLP_ENDPOINT"];
+    if (override != null) {
+      return override;
+    }
+    const now = Date.now();
+    if (this.cached != null && now - this.cached.checkedAt < ENDPOINT_CACHE_TTL_MS) {
+      return this.cached.url;
+    }
+    this.cached = { checkedAt: now, url: readEndpoint(this.portFile) };
+    return this.cached.url;
+  }
+  exporterFor(url) {
+    if (this.delegate?.url !== url) {
+      void this.delegate?.exporter.shutdown();
+      this.delegate = { exporter: new OTLPTraceExporter({ url }), url };
+    }
+    return this.delegate.exporter;
+  }
+};
+function readEndpoint(portFile) {
+  if (portFile == null) {
+    return void 0;
+  }
+  const raw = readPortFile(portFile);
+  if (raw == null) {
+    return void 0;
+  }
+  const parsed = portSchema.safeParse(raw.trim());
+  return parsed.success ? `http://localhost:${String(parsed.data)}/v1/traces` : void 0;
+}
+function readPortFile(portFile) {
+  try {
+    return readFileSync(portFile, { encoding: "utf8" });
+  } catch {
+    return void 0;
+  }
+}
+function resolvePortFile() {
+  const root = findRipploRoot(process.cwd());
+  return root == null ? void 0 : path.join(root, ".ripplo", ".local", "otlp-port");
+}
+function findRipploRoot(dir) {
+  if (existsSync(path.join(dir, ".ripplo", "project.json"))) {
+    return dir;
+  }
+  const parent = path.dirname(dir);
+  return parent === dir ? void 0 : findRipploRoot(parent);
+}
+var BaggageAttributeSpanProcessor = class {
+  inner;
+  constructor(inner) {
+    this.inner = inner;
+  }
+  onStart(span, parentContext) {
+    const baggage = propagation.getBaggage(parentContext);
+    if (baggage != null) {
+      BAGGAGE_ATTRIBUTE_KEYS.forEach((key) => {
+        const entry = baggage.getEntry(key);
+        if (entry != null) {
+          span.setAttribute(key, entry.value);
+        }
+      });
+    }
+    this.inner.onStart(span, parentContext);
+  }
+  onEnd(span) {
+    this.inner.onEnd(span);
+  }
+  forceFlush() {
+    return this.inner.forceFlush();
+  }
+  shutdown() {
+    return this.inner.shutdown();
+  }
+};
+export {
+  register
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ripplo/instrument",
+  "version": "0.7.0",
+  "description": "Server-side OpenTelemetry preload for Ripplo — streams backend spans into test runs",
+  "homepage": "https://ripplo.ai",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js",
+      "default": "./dist/register.js"
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.56.1",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.200.0",
+    "@opentelemetry/sdk-node": "^0.200.0",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsup": "^8.5.1",
+    "@ripplo/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "main": "./dist/index.js"
+}