portless 0.2.2 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@ Replace port numbers with stable, named .localhost URLs. For humans and agents.
 
 ```diff
 - "dev": "next dev"              # http://localhost:3000
-+ "dev": "portless myapp next dev"  # http://myapp.localhost
++ "dev": "portless myapp next dev"  # http://myapp.localhost:1355
 ```
 
 ## Quick Start
@@ -13,29 +13,29 @@ Replace port numbers with stable, named .localhost URLs. For humans and agents.
 # Install
 npm install -g portless
 
-# Start the proxy (once, requires sudo for port 80)
-sudo portless proxy
+# Start the proxy (once, no sudo needed)
+portless proxy start
 
-# Run your app
+# Run your app (auto-starts the proxy if needed)
 portless myapp next dev
-# → http://myapp.localhost
+# -> http://myapp.localhost:1355
 ```
 
-> When run directly in your terminal, portless can auto-start the proxy for you (prompts for sudo once). Via package scripts, start the proxy manually first.
+> The proxy auto-starts when you run an app. You can also start it explicitly with `portless proxy start`.
 
 ## Why
 
 Local dev with port numbers is fragile:
 
-- **Port conflicts** — two projects default to the same port and you get `EADDRINUSE`
-- **Memorizing ports** — was the API on 3001 or 8080?
-- **Refreshing shows the wrong app** — stop one server, start another on the same port, and your open tab now shows something completely different
-- **Monorepo multiplier** — every problem above scales with each service in the repo
-- **Agents test the wrong port** — AI coding agents guess or hardcode the wrong port, especially in monorepos
-- **Cookie and storage clashes** — cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
-- **Hardcoded ports in config** — CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
-- **Sharing URLs with teammates** — "what port is that on?" becomes a Slack question
-- **Browser history is useless** — your history for `localhost:3000` is a jumble of unrelated projects
+- **Port conflicts** -- two projects default to the same port and you get `EADDRINUSE`
+- **Memorizing ports** -- was the API on 3001 or 8080?
+- **Refreshing shows the wrong app** -- stop one server, start another on the same port, and your open tab now shows something completely different
+- **Monorepo multiplier** -- every problem above scales with each service in the repo
+- **Agents test the wrong port** -- AI coding agents guess or hardcode the wrong port, especially in monorepos
+- **Cookie and storage clashes** -- cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
+- **Hardcoded ports in config** -- CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
+- **Sharing URLs with teammates** -- "what port is that on?" becomes a Slack question
+- **Browser history is useless** -- your history for `localhost:3000` is a jumble of unrelated projects
 
 Portless fixes all of this by giving each dev server a stable, named `.localhost` URL that both humans and agents can rely on.
 
@@ -44,14 +44,14 @@ Portless fixes all of this by giving each dev server a stable, named `.localhost
 ```bash
 # Basic
 portless myapp next dev
-# → http://myapp.localhost
+# -> http://myapp.localhost:1355
 
 # Subdomains
 portless api.myapp pnpm start
-# → http://api.myapp.localhost
+# -> http://api.myapp.localhost:1355
 
 portless docs.myapp next dev
-# → http://docs.myapp.localhost
+# -> http://docs.myapp.localhost:1355
 ```
 
 ### In package.json
@@ -64,52 +64,96 @@ portless docs.myapp next dev
 }
 ```
 
-Start the proxy once (`sudo portless proxy`), then just `pnpm dev`.
+The proxy auto-starts when you run an app. Or start it explicitly: `portless proxy start`.
 
 ## How It Works
 
 ```mermaid
 flowchart TD
-    Browser["Browser\nmyapp.localhost"]
-    Proxy["portless proxy\n(port 80)"]
+    Browser["Browser\nmyapp.localhost:1355"]
+    Proxy["portless proxy\n(port 1355)"]
     App1[":4123\nmyapp"]
     App2[":4567\napi"]
 
-    Browser -->|port 80| Proxy
+    Browser -->|port 1355| Proxy
     Proxy --> App1
     Proxy --> App2
 ```
 
-1. **Start the proxy** -- runs on port 80 by default in the background (requires sudo once)
+1. **Start the proxy** -- auto-starts when you run an app, or start explicitly with `portless proxy start`
 2. **Run apps** -- `portless <name> <command>` assigns a free port and registers with the proxy
-3. **Access via URL** -- `http://<name>.localhost` routes through the proxy to your app
+3. **Access via URL** -- `http://<name>.localhost:1355` routes through the proxy to your app
 
 Apps are assigned a random port (4000-4999) via the `PORT` environment variable. Most frameworks (Next.js, Vite, etc.) respect this automatically.
 
+## HTTP/2 + HTTPS
+
+Enable HTTP/2 for faster dev server page loads. Browsers limit HTTP/1.1 to 6 connections per host, which bottlenecks dev servers that serve many unbundled files (Vite, Nuxt, etc.). HTTP/2 multiplexes all requests over a single connection.
+
+```bash
+# Start with HTTPS/2 -- generates certs and trusts them automatically
+portless proxy start --https
+
+# First run prompts for sudo once to add the CA to your system trust store.
+# After that, no prompts. No browser warnings.
+
+# Make it permanent (add to .bashrc / .zshrc)
+export PORTLESS_HTTPS=1
+portless proxy start    # HTTPS by default now
+
+# Use your own certs (e.g., from mkcert)
+portless proxy start --cert ./cert.pem --key ./key.pem
+
+# If you skipped sudo on first run, trust the CA later
+sudo portless trust
+```
+
 ## Commands
 
 ```bash
-portless <name> <cmd> [args...]  # Run app at http://<name>.localhost
+portless <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
 portless list                    # Show active routes
+portless trust                   # Add local CA to system trust store
 
 # Disable portless (run command directly)
 PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
 # Also accepts PORTLESS=skip
 
 # Proxy control
-sudo portless proxy              # Start the proxy (port 80)
-sudo portless proxy --port 8080  # Start the proxy on a custom port
-sudo portless proxy stop         # Stop the proxy
+portless proxy start             # Start the proxy (port 1355, daemon)
+portless proxy start --https     # Start with HTTP/2 + TLS
+portless proxy start -p 80       # Start on port 80 (requires sudo)
+portless proxy start --foreground  # Start in foreground (for debugging)
+portless proxy stop              # Stop the proxy
 
 # Options
---port <number>                  # Port for the proxy (default: 80)
-                                 # Ports >= 1024 do not require sudo
+-p, --port <number>              # Port for the proxy (default: 1355)
+                                 # Ports < 1024 require sudo
+--https                          # Enable HTTP/2 + TLS with auto-generated certs
+--cert <path>                    # Use a custom TLS certificate (implies --https)
+--key <path>                     # Use a custom TLS private key (implies --https)
+--no-tls                         # Disable HTTPS (overrides PORTLESS_HTTPS)
+--foreground                     # Run proxy in foreground instead of daemon
+
+# Environment variables
+PORTLESS_PORT=<number>           # Override the default proxy port
+PORTLESS_HTTPS=1                 # Always enable HTTPS
+PORTLESS_STATE_DIR=<path>        # Override the state directory
 
 # Info
 portless --help                  # Show help
 portless --version               # Show version
 ```
 
+## State Directory
+
+Portless stores its state (routes, PID file, port file) in a directory that depends on the proxy port:
+
+- **Port < 1024** (sudo required): `/tmp/portless` -- shared between root and user processes
+- **Port >= 1024** (no sudo): `~/.portless` -- user-scoped, no root involvement
+
+Override with the `PORTLESS_STATE_DIR` environment variable if needed.
+
 ## Requirements
 
 - Node.js 20+

package/dist/chunk-VRBD6YAY.js

@@ -0,0 +1,412 @@
+// src/utils.ts
+function isErrnoException(err) {
+  return err instanceof Error && "code" in err && typeof err.code === "string";
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function formatUrl(hostname, proxyPort, tls = false) {
+  const proto = tls ? "https" : "http";
+  const defaultPort = tls ? 443 : 80;
+  return proxyPort === defaultPort ? `${proto}://${hostname}` : `${proto}://${hostname}:${proxyPort}`;
+}
+function parseHostname(input) {
+  let hostname = input.trim().replace(/^https?:\/\//, "").split("/")[0].toLowerCase();
+  if (!hostname || hostname === ".localhost") {
+    throw new Error("Hostname cannot be empty");
+  }
+  if (!hostname.endsWith(".localhost")) {
+    hostname = `${hostname}.localhost`;
+  }
+  const name = hostname.replace(/\.localhost$/, "");
+  if (name.includes("..")) {
+    throw new Error(`Invalid hostname "${name}": consecutive dots are not allowed`);
+  }
+  if (!/^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/.test(name)) {
+    throw new Error(
+      `Invalid hostname "${name}": must contain only lowercase letters, digits, hyphens, and dots`
+    );
+  }
+  return hostname;
+}
+
+// src/proxy.ts
+import * as http from "http";
+import * as http2 from "http2";
+import * as net from "net";
+var PORTLESS_HEADER = "X-Portless";
+var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-connection",
+  "transfer-encoding",
+  "upgrade"
+]);
+function getRequestHost(req) {
+  const authority = req.headers[":authority"];
+  if (typeof authority === "string" && authority) return authority;
+  return req.headers.host || "";
+}
+function buildForwardedHeaders(req, tls) {
+  const headers = {};
+  const remoteAddress = req.socket.remoteAddress || "127.0.0.1";
+  const proto = tls ? "https" : "http";
+  const defaultPort = tls ? "443" : "80";
+  const hostHeader = getRequestHost(req);
+  headers["x-forwarded-for"] = req.headers["x-forwarded-for"] ? `${req.headers["x-forwarded-for"]}, ${remoteAddress}` : remoteAddress;
+  headers["x-forwarded-proto"] = req.headers["x-forwarded-proto"] || proto;
+  headers["x-forwarded-host"] = req.headers["x-forwarded-host"] || hostHeader;
+  headers["x-forwarded-port"] = req.headers["x-forwarded-port"] || hostHeader.split(":")[1] || defaultPort;
+  return headers;
+}
+function createProxyServer(options) {
+  const { getRoutes, proxyPort, onError = (msg) => console.error(msg), tls } = options;
+  const isTls = !!tls;
+  const handleRequest = (req, res) => {
+    res.setHeader(PORTLESS_HEADER, "1");
+    const routes = getRoutes();
+    const host = getRequestHost(req).split(":")[0];
+    if (!host) {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      res.end("Missing Host header");
+      return;
+    }
+    const route = routes.find((r) => r.hostname === host);
+    if (!route) {
+      const safeHost = escapeHtml(host);
+      res.writeHead(404, { "Content-Type": "text/html" });
+      res.end(`
+        <html>
+          <head><title>portless - Not Found</title></head>
+          <body style="font-family: system-ui; padding: 40px; max-width: 600px; margin: 0 auto;">
+            <h1>Not Found</h1>
+            <p>No app registered for <strong>${safeHost}</strong></p>
+            ${routes.length > 0 ? `
+              <h2>Active apps:</h2>
+              <ul>
+                ${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort, isTls))}">${escapeHtml(r.hostname)}</a> - localhost:${escapeHtml(String(r.port))}</li>`).join("")}
+              </ul>
+            ` : "<p><em>No apps running.</em></p>"}
+            <p>Start an app with: <code>portless ${safeHost.replace(".localhost", "")} your-command</code></p>
+          </body>
+        </html>
+      `);
+      return;
+    }
+    const forwardedHeaders = buildForwardedHeaders(req, isTls);
+    const proxyReqHeaders = { ...req.headers };
+    for (const [key, value] of Object.entries(forwardedHeaders)) {
+      proxyReqHeaders[key] = value;
+    }
+    for (const key of Object.keys(proxyReqHeaders)) {
+      if (key.startsWith(":")) {
+        delete proxyReqHeaders[key];
+      }
+    }
+    const proxyReq = http.request(
+      {
+        hostname: "127.0.0.1",
+        port: route.port,
+        path: req.url,
+        method: req.method,
+        headers: proxyReqHeaders
+      },
+      (proxyRes) => {
+        const responseHeaders = { ...proxyRes.headers };
+        if (isTls) {
+          for (const h of HOP_BY_HOP_HEADERS) {
+            delete responseHeaders[h];
+          }
+        }
+        res.writeHead(proxyRes.statusCode || 502, responseHeaders);
+        proxyRes.pipe(res);
+      }
+    );
+    proxyReq.on("error", (err) => {
+      onError(`Proxy error for ${getRequestHost(req)}: ${err.message}`);
+      if (!res.headersSent) {
+        const errWithCode = err;
+        const message = errWithCode.code === "ECONNREFUSED" ? "Bad Gateway: the target app is not responding. It may have crashed." : "Bad Gateway: the target app may not be running.";
+        res.writeHead(502, { "Content-Type": "text/plain" });
+        res.end(message);
+      }
+    });
+    res.on("close", () => {
+      if (!proxyReq.destroyed) {
+        proxyReq.destroy();
+      }
+    });
+    req.on("error", () => {
+      if (!proxyReq.destroyed) {
+        proxyReq.destroy();
+      }
+    });
+    req.pipe(proxyReq);
+  };
+  const handleUpgrade = (req, socket, head) => {
+    const routes = getRoutes();
+    const host = getRequestHost(req).split(":")[0];
+    const route = routes.find((r) => r.hostname === host);
+    if (!route) {
+      socket.destroy();
+      return;
+    }
+    const forwardedHeaders = buildForwardedHeaders(req, isTls);
+    const proxyReqHeaders = { ...req.headers };
+    for (const [key, value] of Object.entries(forwardedHeaders)) {
+      proxyReqHeaders[key] = value;
+    }
+    for (const key of Object.keys(proxyReqHeaders)) {
+      if (key.startsWith(":")) {
+        delete proxyReqHeaders[key];
+      }
+    }
+    const proxyReq = http.request({
+      hostname: "127.0.0.1",
+      port: route.port,
+      path: req.url,
+      method: req.method,
+      headers: proxyReqHeaders
+    });
+    proxyReq.on("upgrade", (proxyRes, proxySocket, proxyHead) => {
+      let response = `HTTP/1.1 101 Switching Protocols\r
+`;
+      for (let i = 0; i < proxyRes.rawHeaders.length; i += 2) {
+        response += `${proxyRes.rawHeaders[i]}: ${proxyRes.rawHeaders[i + 1]}\r
+`;
+      }
+      response += "\r\n";
+      socket.write(response);
+      if (proxyHead.length > 0) {
+        socket.write(proxyHead);
+      }
+      proxySocket.pipe(socket);
+      socket.pipe(proxySocket);
+      proxySocket.on("error", () => socket.destroy());
+      socket.on("error", () => proxySocket.destroy());
+    });
+    proxyReq.on("error", (err) => {
+      onError(`WebSocket proxy error for ${getRequestHost(req)}: ${err.message}`);
+      socket.destroy();
+    });
+    proxyReq.on("response", (res) => {
+      if (!socket.destroyed) {
+        let response = `HTTP/1.1 ${res.statusCode} ${res.statusMessage}\r
+`;
+        for (let i = 0; i < res.rawHeaders.length; i += 2) {
+          response += `${res.rawHeaders[i]}: ${res.rawHeaders[i + 1]}\r
+`;
+        }
+        response += "\r\n";
+        socket.write(response);
+        res.pipe(socket);
+      }
+    });
+    if (head.length > 0) {
+      proxyReq.write(head);
+    }
+    proxyReq.end();
+  };
+  if (tls) {
+    const h2Server = http2.createSecureServer({
+      cert: tls.cert,
+      key: tls.key,
+      allowHTTP1: true,
+      ...tls.SNICallback ? { SNICallback: tls.SNICallback } : {}
+    });
+    h2Server.on("request", (req, res) => {
+      handleRequest(req, res);
+    });
+    h2Server.on("upgrade", (req, socket, head) => {
+      handleUpgrade(req, socket, head);
+    });
+    const plainServer = http.createServer(handleRequest);
+    plainServer.on("upgrade", handleUpgrade);
+    const wrapper = net.createServer((socket) => {
+      socket.once("readable", () => {
+        const buf = socket.read(1);
+        if (!buf) {
+          socket.destroy();
+          return;
+        }
+        socket.unshift(buf);
+        if (buf[0] === 22) {
+          h2Server.emit("connection", socket);
+        } else {
+          plainServer.emit("connection", socket);
+        }
+      });
+    });
+    const origClose = wrapper.close.bind(wrapper);
+    wrapper.close = function(cb) {
+      h2Server.close();
+      plainServer.close();
+      return origClose(cb);
+    };
+    return wrapper;
+  }
+  const httpServer = http.createServer(handleRequest);
+  httpServer.on("upgrade", handleUpgrade);
+  return httpServer;
+}
+
+// src/routes.ts
+import * as fs from "fs";
+import * as path from "path";
+var STALE_LOCK_THRESHOLD_MS = 1e4;
+var LOCK_MAX_RETRIES = 20;
+var LOCK_RETRY_DELAY_MS = 50;
+var FILE_MODE = 420;
+var DIR_MODE = 493;
+function isValidRoute(value) {
+  return typeof value === "object" && value !== null && typeof value.hostname === "string" && typeof value.port === "number" && typeof value.pid === "number";
+}
+var RouteStore = class _RouteStore {
+  /** The state directory path. */
+  dir;
+  routesPath;
+  lockPath;
+  pidPath;
+  portFilePath;
+  onWarning;
+  constructor(dir, options) {
+    this.dir = dir;
+    this.routesPath = path.join(dir, "routes.json");
+    this.lockPath = path.join(dir, "routes.lock");
+    this.pidPath = path.join(dir, "proxy.pid");
+    this.portFilePath = path.join(dir, "proxy.port");
+    this.onWarning = options?.onWarning;
+  }
+  ensureDir() {
+    if (!fs.existsSync(this.dir)) {
+      fs.mkdirSync(this.dir, { recursive: true, mode: DIR_MODE });
+    }
+    try {
+      fs.chmodSync(this.dir, DIR_MODE);
+    } catch {
+    }
+  }
+  getRoutesPath() {
+    return this.routesPath;
+  }
+  // -- Locking ---------------------------------------------------------------
+  static sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+  syncSleep(ms) {
+    Atomics.wait(_RouteStore.sleepBuffer, 0, 0, ms);
+  }
+  acquireLock(maxRetries = LOCK_MAX_RETRIES, retryDelayMs = LOCK_RETRY_DELAY_MS) {
+    for (let i = 0; i < maxRetries; i++) {
+      try {
+        fs.mkdirSync(this.lockPath);
+        return true;
+      } catch (err) {
+        if (isErrnoException(err) && err.code === "EEXIST") {
+          try {
+            const stat = fs.statSync(this.lockPath);
+            if (Date.now() - stat.mtimeMs > STALE_LOCK_THRESHOLD_MS) {
+              fs.rmSync(this.lockPath, { recursive: true });
+              continue;
+            }
+          } catch {
+            continue;
+          }
+          this.syncSleep(retryDelayMs);
+        } else {
+          return false;
+        }
+      }
+    }
+    return false;
+  }
+  releaseLock() {
+    try {
+      fs.rmSync(this.lockPath, { recursive: true });
+    } catch {
+    }
+  }
+  // -- Route I/O -------------------------------------------------------------
+  isProcessAlive(pid) {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Load routes from disk, filtering out stale entries whose owning process
+   * is no longer alive. Stale-route cleanup is only persisted when the caller
+   * already holds the lock (i.e. inside addRoute/removeRoute) to avoid
+   * unprotected concurrent writes.
+   */
+  loadRoutes(persistCleanup = false) {
+    if (!fs.existsSync(this.routesPath)) {
+      return [];
+    }
+    try {
+      const raw = fs.readFileSync(this.routesPath, "utf-8");
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        this.onWarning?.(`Corrupted routes file (invalid JSON): ${this.routesPath}`);
+        return [];
+      }
+      if (!Array.isArray(parsed)) {
+        this.onWarning?.(`Corrupted routes file (expected array): ${this.routesPath}`);
+        return [];
+      }
+      const routes = parsed.filter(isValidRoute);
+      const alive = routes.filter((r) => this.isProcessAlive(r.pid));
+      if (persistCleanup && alive.length !== routes.length) {
+        try {
+          fs.writeFileSync(this.routesPath, JSON.stringify(alive, null, 2), { mode: FILE_MODE });
+        } catch {
+        }
+      }
+      return alive;
+    } catch {
+      return [];
+    }
+  }
+  saveRoutes(routes) {
+    fs.writeFileSync(this.routesPath, JSON.stringify(routes, null, 2), { mode: FILE_MODE });
+  }
+  addRoute(hostname, port, pid) {
+    this.ensureDir();
+    if (!this.acquireLock()) {
+      throw new Error("Failed to acquire route lock");
+    }
+    try {
+      const routes = this.loadRoutes(true).filter((r) => r.hostname !== hostname);
+      routes.push({ hostname, port, pid });
+      this.saveRoutes(routes);
+    } finally {
+      this.releaseLock();
+    }
+  }
+  removeRoute(hostname) {
+    this.ensureDir();
+    if (!this.acquireLock()) {
+      throw new Error("Failed to acquire route lock");
+    }
+    try {
+      const routes = this.loadRoutes(true).filter((r) => r.hostname !== hostname);
+      this.saveRoutes(routes);
+    } finally {
+      this.releaseLock();
+    }
+  }
+};
+
+export {
+  isErrnoException,
+  escapeHtml,
+  formatUrl,
+  parseHostname,
+  PORTLESS_HEADER,
+  createProxyServer,
+  FILE_MODE,
+  DIR_MODE,
+  RouteStore
+};