autotel-devtools 6.0.0 → 6.0.1

package/README.md

@@ -152,12 +152,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

@@ -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)`);
@@ -1034,43 +1037,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 +1126,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 +1153,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 +1181,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 +1199,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 +1214,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 +1245,8 @@ 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;
+  const uiBase = `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${boundPort}`;
   const title = options.title || "autotel-devtools";
   process.stdout.write(`
   ${title}