autotel-terminal 21.0.0 → 22.0.0

package/README.md

@@ -68,6 +68,32 @@ Port 4319 is used by default to avoid clashing with the standard OTLP port (4318
 | `POST /v1/metrics` | Metrics | Accepts OTLP JSON metrics (acknowledged and counted) |
 | `GET /healthz` | — | Health check |
 
+When bound to a loopback host, the receiver listens on **both** `127.0.0.1`
+and `::1`, so a `localhost` client connects regardless of how the OS resolves
+`localhost` (macOS prefers IPv6 `::1`). The startup line prints every bound
+address; an unbindable family becomes a warning, not a silent failure.
+
+### Behind a dev-server proxy
+
+If a dev server proxies `/v1/traces` to the terminal receiver, two bugs make
+spans silently vanish:
+
+```ts
+// Express / http-proxy-middleware
+app.use(
+  '/v1/traces',
+  createProxyMiddleware({
+    pathRewrite: () => '/v1/traces',      // Express strips the mount prefix → would forward "/"
+    target: 'http://127.0.0.1:4319',      // 127.0.0.1, not localhost (macOS resolves localhost → ::1)
+    changeOrigin: true,
+  }),
+);
+```
+
+The browser shows the request succeeding while the receiver stays empty — so
+verify on the receiver (the TUI should show the spans), not just that the
+request left the browser.
+
 ## Quick Start
 
 ### Recommended Usage

package/dist/cli.cjs

@@ -2761,6 +2761,54 @@ function renderTerminal(options = {}, stream) {
     console.error("[autotel-terminal] Failed to render dashboard:", error);
   }
 }
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+function formatAddress(host, port) {
+  return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
+}
+function listenLoopbackDualStack(args) {
+  const { primary, port, host, attachSecondary } = args;
+  let sibling;
+  const ready = new Promise(
+    (resolve) => {
+      const addresses = [];
+      const warnings = [];
+      const primaryHost = host === "localhost" ? "127.0.0.1" : host;
+      primary.listen(port, primaryHost, () => {
+        const addr = primary.address();
+        const resolvedPort = addr && typeof addr === "object" ? addr.port : port;
+        addresses.push(formatAddress(primaryHost, resolvedPort));
+        if (!LOOPBACK.has(host)) {
+          resolve({ addresses, warnings });
+          return;
+        }
+        const siblingHost = primaryHost === "::1" ? "127.0.0.1" : "::1";
+        const s = http.createServer();
+        attachSecondary(s);
+        const onError = (e) => {
+          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.`
+          );
+          resolve({ addresses, warnings });
+        };
+        s.once("error", onError);
+        s.listen(resolvedPort, siblingHost, () => {
+          s.off("error", onError);
+          sibling = s;
+          addresses.push(formatAddress(siblingHost, resolvedPort));
+          resolve({ addresses, warnings });
+        });
+      });
+    }
+  );
+  return {
+    ready,
+    closeSibling: () => new Promise((res) => {
+      if (!sibling) return res();
+      sibling.close(() => res());
+    })
+  };
+}
 
 // src/cli-stream.ts
 var CliTerminalSpanStream = class {
@@ -3132,7 +3180,7 @@ async function main() {
     },
     spanStream
   );
-  const server = http.createServer(async (req, res) => {
+  const requestHandler = async (req, res) => {
     if (req.method === "GET" && req.url === "/healthz") {
       sendJson(res, 200, { ok: true });
       return;
@@ -3170,23 +3218,34 @@ async function main() {
         message: error instanceof Error ? error.message : String(error)
       });
     }
+  };
+  const server = http.createServer(requestHandler);
+  const listeners = listenLoopbackDualStack({
+    primary: server,
+    port: options.port,
+    host: options.host,
+    attachSecondary: (s) => s.on("request", requestHandler)
   });
-  server.listen(options.port, options.host, () => {
-    process.stdout.write(
-      `[autotel-terminal] listening on http://${options.host}:${options.port}
+  const { addresses, warnings } = await listeners.ready;
+  process.stdout.write(
+    `[autotel-terminal] listening on ${addresses.join(" + ")}
 `
-    );
-    process.stdout.write(
-      "[autotel-terminal] endpoints: /v1/traces, /v1/logs, /v1/metrics\n"
-    );
-    process.stdout.write(
-      "[autotel-terminal] set OTEL_EXPORTER_OTLP_PROTOCOL=http/json and OTEL_EXPORTER_OTLP_ENDPOINT to this host/port\n"
-    );
-  });
+  );
+  process.stdout.write(
+    "[autotel-terminal] endpoints: /v1/traces, /v1/logs, /v1/metrics\n"
+  );
+  process.stdout.write(
+    "[autotel-terminal] set OTEL_EXPORTER_OTLP_PROTOCOL=http/json and OTEL_EXPORTER_OTLP_ENDPOINT to this host/port\n"
+  );
+  for (const w of warnings) {
+    process.stdout.write(`[autotel-terminal] \u26A0 ${w}
+`);
+  }
   const shutdown = () => {
-    server.close(() => {
-      process.exit(0);
-    });
+    Promise.all([
+      new Promise((r) => server.close(() => r())),
+      listeners.closeSibling()
+    ]).then(() => process.exit(0));
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);