npm - autotel-devtools - Versions diffs - 6.0.0 → 6.1.0 - Mend

autotel-devtools 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +25 -1
package/dist/cli.cjs +146 -23
package/dist/cli.cjs.map +1 -1
package/dist/cli.js +146 -23
package/dist/cli.js.map +1 -1
package/dist/index.cjs +84 -16
package/dist/index.cjs.map +1 -1
package/dist/index.js +84 -16
package/dist/index.js.map +1 -1
package/dist/server/index.cjs +59 -4
package/dist/server/index.cjs.map +1 -1
package/dist/server/index.d.cts +17 -1
package/dist/server/index.d.ts +17 -1
package/dist/server/index.js +58 -5
package/dist/server/index.js.map +1 -1
package/dist/widget.global.js +1 -1
package/package.json +2 -2
package/skills/autotel-devtools/SKILL.md +4 -2

package/README.md CHANGED Viewed

@@ -111,6 +111,25 @@ const myFunction = trace((ctx) => async () => {
 - **DevtoolsServer** - WebSocket server + in-memory data store
 - **HTTP Routes** - OTLP receivers for traces/logs/metrics (JSON + protobuf)
+#### Detecting the receiver
+Every response carries an `x-autotel-devtools: <version>` header, and `GET /healthz`
+returns `{ ok, service: "autotel-devtools", version, clients }`. Use either to confirm
+you are talking to autotel-devtools rather than another OTLP collector that happens to
+share the port — for example before pointing an exporter at `:4318`:
+```ts
+import { probePortHolder } from 'autotel-devtools/server'
+// 'autotel-devtools' | 'foreign' | 'none'
+const holder = await probePortHolder('127.0.0.1', 4318)
+```
+If you start the receiver and the requested port is held by a *foreign* process (some
+IDEs run their own OTLP collector on `:4318`), the CLI falls forward to the next free
+port and warns that exporters still aimed at the busy port are reaching that other
+process — point them at the bound port, or free the original.
 - **Exporters** - OpenTelemetry span/log exporters
 ### Widget (Svelte 5)
@@ -152,12 +171,17 @@ AUTOTEL_DEVTOOLS_TITLE="My App"  # Dashboard title (optional)
 ### CLI Options
 ```bash
+npx autotel-devtools 4319                      # port as a bare positional
 npx autotel-devtools --port 4319 --host 0.0.0.0
 ```
+Arguments:
+- `[port]` - Port to listen on, shorthand for `--port` (an explicit `--port` always wins)
 Options:
-- `--port, -p` - Port to listen on (default: 4318)
+- `--port, -p` - Port to listen on (default: 4318). If the port is taken, the receiver walks forward to the next free port and prints a warning.
 - `--host, -H` - Host to bind to (default: 127.0.0.1)
 - `--title, -t` - Dashboard title

package/dist/cli.cjs CHANGED Viewed

@@ -373,6 +373,9 @@ var DevtoolsServer = class {
     this.onData = options.onData;
     this.httpServer = options.server ?? http.createServer();
     this.wss = new ws.WebSocketServer({ server: this.httpServer, path: options.path ?? "/ws" });
+    this.wss.on("error", (err) => {
+      if (this.httpServer.listening) throw err;
+    });
     this.wss.on("connection", (ws) => {
       this.clients.add(ws);
       this.log(`Client connected (${this.clients.size} total)`);
@@ -920,7 +923,38 @@ function decodeOtlpMetricsRequest(body) {
   return decodeRequest("opentelemetry.proto.metrics.v1.ExportMetricsServiceRequest", body);
 }
+// src/server/identity.ts
+var DEVTOOLS_IDENTITY = "autotel-devtools";
+async function probePortHolder(host, port, timeoutMs = 500) {
+  const authority = host.includes(":") ? `[${host}]` : host;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://${authority}:${port}/healthz`, {
+      signal: controller.signal
+    });
+    if (res.headers.get("x-autotel-devtools")) return "autotel-devtools";
+    try {
+      const body = await res.json();
+      if (body && body.service === DEVTOOLS_IDENTITY) return "autotel-devtools";
+    } catch {
+    }
+    return "foreign";
+  } catch {
+    return "none";
+  } finally {
+    clearTimeout(timer);
+  }
+}
 // src/server/http.ts
+function sendOtlpError(res, req, e) {
+  sendJson(res, 400, {
+    error: "Invalid OTLP payload",
+    message: e instanceof Error ? e.message : String(e),
+    contentType: req.headers["content-type"] ?? null
+  });
+}
 var PROTOBUF_DECODERS = {
   traces: decodeOtlpTraceRequest,
   logs: decodeOtlpLogsRequest,
@@ -941,6 +975,18 @@ function findPackageRoot() {
   return dir;
 }
 var FULLPAGE_HTML = `<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>autotel-devtools</title><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;width:100%;overflow:hidden}</style></head><body><script src="/widget.js?mode=fullpage"></script></body></html>`;
+var cachedVersion = null;
+function getVersion() {
+  if (cachedVersion !== null) return cachedVersion;
+  let version = "unknown";
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.resolve(findPackageRoot(), "package.json"), "utf8"));
+    if (typeof pkg.version === "string") version = pkg.version;
+  } catch {
+  }
+  cachedVersion = version;
+  return version;
+}
 var cachedWidgetJs = null;
 function getWidgetJs() {
   if (!cachedWidgetJs) {
@@ -967,6 +1013,8 @@ function attachDevtoolsRoutes(httpServer, devtools) {
     res.setHeader("Access-Control-Allow-Origin", "*");
     res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    res.setHeader("x-autotel-devtools", getVersion());
+    res.setHeader("Access-Control-Expose-Headers", "x-autotel-devtools");
     if (req.method === "OPTIONS") {
       res.writeHead(204);
       res.end();
@@ -985,7 +1033,12 @@ function attachDevtoolsRoutes(httpServer, devtools) {
       return;
     }
     if (req.method === "GET" && url === "/healthz") {
-      sendJson(res, 200, { ok: true, clients: devtools.clientCount });
+      sendJson(res, 200, {
+        ok: true,
+        service: DEVTOOLS_IDENTITY,
+        version: getVersion(),
+        clients: devtools.clientCount
+      });
       return;
     }
     if (req.method === "GET" && url === "/v1/traces") {
@@ -1005,7 +1058,7 @@ function attachDevtoolsRoutes(httpServer, devtools) {
         devtools.addTraces(traces);
         sendJson(res, 200, { acceptedTraces: traces.length });
       } catch (e) {
-        sendJson(res, 400, { error: "Invalid OTLP payload", message: e instanceof Error ? e.message : String(e) });
+        sendOtlpError(res, req, e);
       }
       return;
     }
@@ -1016,7 +1069,7 @@ function attachDevtoolsRoutes(httpServer, devtools) {
         devtools.addLogs(logs);
         sendJson(res, 200, { acceptedLogs: logs.length });
       } catch (e) {
-        sendJson(res, 400, { error: "Invalid OTLP payload", message: e instanceof Error ? e.message : String(e) });
+        sendOtlpError(res, req, e);
       }
       return;
     }
@@ -1026,7 +1079,7 @@ function attachDevtoolsRoutes(httpServer, devtools) {
         const count = countOtlpMetrics(payload);
         sendJson(res, 200, { acceptedMetrics: count });
       } catch (e) {
-        sendJson(res, 400, { error: "Invalid OTLP payload", message: e instanceof Error ? e.message : String(e) });
+        sendOtlpError(res, req, e);
       }
       return;
     }
@@ -1034,43 +1087,79 @@ function attachDevtoolsRoutes(httpServer, devtools) {
   });
 }
 var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+var DEFAULT_MAX_PORT_TRIES = 20;
 function formatAddress(host, port) {
   return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
 }
 function listenLoopbackDualStack(args) {
-  const { primary, port, host, attachSecondary } = args;
+  const { primary, port, host, attachSecondary, maxTries } = args;
+  const maxAttempts = Math.max(1, maxTries ?? DEFAULT_MAX_PORT_TRIES);
   let sibling;
   const ready = new Promise(
-    (resolve3) => {
+    (resolve3, reject) => {
       const addresses = [];
       const warnings = [];
       const primaryHost = host === "localhost" ? "127.0.0.1" : host;
-      primary.listen(port, primaryHost, () => {
+      let candidate = port;
+      let attempt = 0;
+      const bindFailed = (atPort, msg) => reject(
+        new Error(`could not bind ${formatAddress(primaryHost, atPort)}: ${msg}`)
+      );
+      const onError = (e) => {
+        if (e.code !== "EADDRINUSE") return bindFailed(candidate, e.message);
+        if (++attempt >= maxAttempts) {
+          reject(
+            new Error(
+              `could not bind ${formatAddress(primaryHost, port)}: ${maxAttempts} consecutive ports in use`
+            )
+          );
+          return;
+        }
+        candidate++;
+        listen();
+      };
+      const onListening = () => {
+        primary.removeListener("error", onError);
+        if (candidate !== port) {
+          warnings.push(`port ${port} was busy; using ${candidate} instead`);
+        }
         const addr = primary.address();
-        const resolvedPort = addr && typeof addr === "object" ? addr.port : port;
+        const resolvedPort = addr && typeof addr === "object" ? addr.port : candidate;
         addresses.push(formatAddress(primaryHost, resolvedPort));
         if (!LOOPBACK.has(host)) {
-          resolve3({ addresses, warnings });
+          resolve3({ addresses, port: resolvedPort, warnings });
           return;
         }
         const siblingHost = primaryHost === "::1" ? "127.0.0.1" : "::1";
         const s = http.createServer();
         attachSecondary(s);
-        const onError = (e) => {
+        const onSiblingError = (se) => {
           s.close();
           warnings.push(
-            `could not also bind ${formatAddress(siblingHost, resolvedPort)} (${e.message}); clients using the ${siblingHost === "::1" ? "IPv6" : "IPv4"} form of "localhost" may not connect.`
+            `could not also bind ${formatAddress(siblingHost, resolvedPort)} (${se.message}); clients using the ${siblingHost === "::1" ? "IPv6" : "IPv4"} form of "localhost" may not connect.`
           );
-          resolve3({ addresses, warnings });
+          resolve3({ addresses, port: resolvedPort, warnings });
         };
-        s.once("error", onError);
+        s.once("error", onSiblingError);
         s.listen(resolvedPort, siblingHost, () => {
-          s.off("error", onError);
+          s.off("error", onSiblingError);
           sibling = s;
           addresses.push(formatAddress(siblingHost, resolvedPort));
-          resolve3({ addresses, warnings });
+          resolve3({ addresses, port: resolvedPort, warnings });
         });
-      });
+      };
+      const listen = () => {
+        try {
+          primary.listen(candidate, primaryHost);
+        } catch (e) {
+          primary.removeListener("error", onError);
+          primary.removeListener("listening", onListening);
+          bindFailed(candidate, e.message);
+        }
+      };
+      primary.on("error", onError);
+      primary.once("listening", onListening);
+      listen();
     }
   );
   return {
@@ -1087,10 +1176,14 @@ function printHelp() {
   process.stdout.write(
     `autotel-devtools - Standalone OTLP receiver with web devtools UI
-Usage: autotel-devtools [options]
+Usage: autotel-devtools [port] [options]
+Arguments:
+  port                 Port to listen on (shorthand for --port; must be a positive integer)
 Options:
-  -p, --port <port>    Port to listen on (default: 4318, env: AUTOTEL_DEVTOOLS_PORT)
+  -p, --port <port>    Port to listen on (default: 4318, env: AUTOTEL_DEVTOOLS_PORT).
+                       If the port is taken, the next free port is used and a warning is shown.
   -H, --host <host>    Host to bind to (default: 127.0.0.1, env: AUTOTEL_DEVTOOLS_HOST)
   -t, --title <title>  Dashboard title (env: AUTOTEL_DEVTOOLS_TITLE)
   Env limits:          AUTOTEL_MAX_TRACE_COUNT, AUTOTEL_MAX_LOG_COUNT, AUTOTEL_MAX_METRIC_COUNT
@@ -1110,7 +1203,8 @@ Endpoints:
 Examples:
   npx autotel-devtools
-  npx autotel-devtools -p 4319
+  npx autotel-devtools 4319
+  npx autotel-devtools -p 4319 -H 0.0.0.0
 Then point your app:
   OTEL_EXPORTER_OTLP_PROTOCOL=http/json OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 node app.js
@@ -1137,10 +1231,12 @@ function printVersion() {
 }
 function parseArgs(argv) {
   const options = {
-    port: Number(process.env.AUTOTEL_DEVTOOLS_PORT || 4318),
+    port: parsePort(process.env.AUTOTEL_DEVTOOLS_PORT || "4318"),
     host: process.env.AUTOTEL_DEVTOOLS_HOST || "127.0.0.1",
     title: process.env.AUTOTEL_DEVTOOLS_TITLE
   };
+  let portWasExplicit = false;
+  let positionalPortConsumed = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     const next = argv[i + 1];
@@ -1153,7 +1249,8 @@ function parseArgs(argv) {
       return null;
     }
     if ((arg === "--port" || arg === "-p") && next) {
-      options.port = Number(next);
+      options.port = parsePort(next);
+      portWasExplicit = true;
       i++;
       continue;
     }
@@ -1167,9 +1264,23 @@ function parseArgs(argv) {
       i++;
       continue;
     }
+    if (/^\d+$/.test(arg) && !positionalPortConsumed) {
+      if (!portWasExplicit) options.port = parsePort(arg);
+      positionalPortConsumed = true;
+      continue;
+    }
   }
   return options;
 }
+function parsePort(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0 || n > 65535) {
+    process.stderr.write(`[autotel-devtools] invalid port: ${value}
+`);
+    process.exit(2);
+  }
+  return n;
+}
 async function main() {
   const options = parseArgs(process.argv.slice(2));
   if (!options) {
@@ -1184,8 +1295,20 @@ async function main() {
     host: options.host,
     attachSecondary: (s) => attachDevtoolsRoutes(s, wsServer)
   });
-  const { addresses, warnings } = await listeners.ready;
-  const uiBase = `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${options.port}`;
+  const { addresses, warnings, port: boundPort } = await listeners.ready;
+  if (boundPort !== options.port) {
+    const holder = await probePortHolder(options.host, options.port);
+    if (holder === "autotel-devtools") {
+      warnings.push(
+        `another autotel-devtools is already running on port ${options.port}; this instance is on ${boundPort}. Use the existing one, or stop it and restart here.`
+      );
+    } else {
+      warnings.push(
+        `port ${options.port} is held by another process that is NOT autotel-devtools. Anything exporting OTLP to :${options.port} is reaching that process, not this devtools. Point your exporter at :${boundPort}, or free :${options.port} and restart.`
+      );
+    }
+  }
+  const uiBase = `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${boundPort}`;
   const title = options.title || "autotel-devtools";
   process.stdout.write(`
   ${title}