runlocal 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,92 @@
+# runlocal
+
+Expose your local development server to the internet. Get a public HTTPS URL that tunnels requests to `localhost` via [runlocal.eu](https://runlocal.eu).
+
+No account needed. No configuration. Just run it.
+
+## Install
+
+```sh
+npm install -g runlocal
+```
+
+## Usage
+
+```sh
+# Tunnel to localhost:3000 (default)
+runlocal
+
+# Tunnel to a specific port
+runlocal 4000
+
+# Use a custom tunnel server
+runlocal 3000 --host wss://your-server.com
+```
+
+You'll get a public URL like `https://abc123.runlocal.eu` that forwards HTTP requests to your local server.
+
+### Options
+
+| Option | Description |
+|---|---|
+| `<port>` | Local port to forward to (default: `3000`) |
+| `--host <url>` | Tunnel server URL (default: `wss://runlocal.eu`) |
+| `--help`, `-h` | Show help |
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `RUNLOCAL_HOST` | Same as `--host`. The flag takes precedence. |
+
+## How it works
+
+`runlocal` opens a WebSocket connection to the tunnel server. When someone visits your public URL, the server forwards the HTTP request through the WebSocket. `runlocal` proxies it to your local server and sends the response back.
+
+```
+Browser → runlocal.eu → WebSocket → runlocal CLI → localhost:3000
+```
+
+## Contributing
+
+### Setup
+
+```sh
+git clone git@github.com:runlater-eu/runlocal.git
+cd runlocal
+npm install
+```
+
+### Running tests
+
+```sh
+npm test
+```
+
+Tests use Node's built-in test runner (`node:test`) with no additional dependencies. The test suite covers:
+
+- **Argument parsing** — defaults, custom port, `--host` flag, env var precedence
+- **Header filtering** — strips `host` and `accept-encoding`, preserves others
+- **HTTP proxying** — GET/POST, query strings, response headers, error handling
+- **WebSocket lifecycle** — join, heartbeat, tunnel creation, reconnection
+- **Integration** — full round-trip with real WebSocket and HTTP servers
+
+### Project structure
+
+```
+index.js        CLI entry point
+lib.js          Core logic (parseArgs, filterHeaders, handleRequest, createConnection)
+test/           Test files
+```
+
+The core logic in `lib.js` uses dependency injection for the WebSocket constructor and logger, making it straightforward to test without mocking globals.
+
+### Submitting changes
+
+1. Create a branch for your change
+2. Make sure `npm test` passes
+3. Open a pull request
+
+## License
+
+MIT

package/index.js

@@ -1,187 +1,12 @@
 #!/usr/bin/env node
 
 const WebSocket = require("ws");
-const http = require("http");
+const { parseArgs, createConnection } = require("./lib");
 
-const PORT = parseInt(process.argv[2] || "3000", 10);
-const HOST = process.env.RUNLOCAL_HOST || "wss://runlocal.eu";
-const WS_URL = `${HOST}/tunnel/websocket?vsn=2.0.0`;
-
-const GREEN = "\x1b[32m";
-const CYAN = "\x1b[36m";
-const DIM = "\x1b[2m";
 const BOLD = "\x1b[1m";
 const RESET = "\x1b[0m";
-const RED = "\x1b[31m";
-const YELLOW = "\x1b[33m";
-
-let refCounter = 0;
-const nextRef = () => String(++refCounter);
-
-function connect() {
-  const ws = new WebSocket(WS_URL);
-  let heartbeatTimer = null;
-  let joinRef = null;
-
-  ws.on("open", () => {
-    console.log(`${DIM}Connecting to runlocal.eu...${RESET}`);
-    joinRef = nextRef();
-    // Phoenix Channel join message: [join_ref, ref, topic, event, payload]
-    ws.send(JSON.stringify([joinRef, joinRef, "tunnel:connect", "phx_join", {}]));
-
-    // Heartbeat every 30s
-    heartbeatTimer = setInterval(() => {
-      ws.send(
-        JSON.stringify([null, nextRef(), "phoenix", "heartbeat", {}])
-      );
-    }, 30000);
-  });
-
-  ws.on("message", (data) => {
-    const msg = JSON.parse(data.toString());
-    // Phoenix v2 serializer: [join_ref, ref, topic, event, payload]
-    const [, , topic, event, payload] = msg;
-
-    if (event === "phx_reply" && topic === "tunnel:connect") {
-      if (payload.status === "ok") {
-        // Join succeeded, wait for tunnel_created push
-      } else {
-        console.error(`${RED}Failed to join: ${JSON.stringify(payload)}${RESET}`);
-      }
-      return;
-    }
-
-    if (event === "tunnel_created") {
-      console.log("");
-      console.log(`  ${GREEN}${BOLD}Tunnel created!${RESET}`);
-      console.log(`  ${CYAN}${BOLD}${payload.url}${RESET}`);
-      console.log("");
-      console.log(`  ${DIM}Forwarding to localhost:${PORT}${RESET}`);
-      console.log(`  ${DIM}Press Ctrl+C to stop${RESET}`);
-      console.log("");
-      return;
-    }
-
-    if (event === "http_request") {
-      handleRequest(ws, joinRef, topic, payload);
-      return;
-    }
-
-    if (event === "phx_close") {
-      console.log(`${YELLOW}Tunnel closed by server${RESET}`);
-      process.exit(0);
-    }
-  });
-
-  ws.on("close", () => {
-    clearInterval(heartbeatTimer);
-    console.log(`${YELLOW}Disconnected. Reconnecting in 3s...${RESET}`);
-    setTimeout(connect, 3000);
-  });
-
-  ws.on("error", (err) => {
-    if (err.code === "ECONNREFUSED") {
-      console.error(
-        `${RED}Could not connect to runlocal.eu${RESET}`
-      );
-    } else {
-      console.error(`${RED}WebSocket error: ${err.message}${RESET}`);
-    }
-  });
-}
-
-function handleRequest(ws, joinRef, topic, payload) {
-  const { request_id, method, path, query_string, headers, body } = payload;
-  const fullPath = query_string ? `${path}?${query_string}` : path;
-
-  const timestamp = new Date().toLocaleTimeString();
-  console.log(
-    `${DIM}${timestamp}${RESET}  ${BOLD}${method}${RESET} ${fullPath}`
-  );
-
-  const reqHeaders = {};
-  if (headers) {
-    for (const [k, v] of headers) {
-      // Skip host header (proxying to localhost) and accept-encoding
-      // (compressed responses corrupt during string conversion)
-      if (k.toLowerCase() !== "host" && k.toLowerCase() !== "accept-encoding") {
-        reqHeaders[k] = v;
-      }
-    }
-  }
-
-  const options = {
-    hostname: "127.0.0.1",
-    port: PORT,
-    path: fullPath,
-    method: method,
-    headers: reqHeaders,
-  };
-
-  const proxyReq = http.request(options, (proxyRes) => {
-    const chunks = [];
-    proxyRes.on("data", (chunk) => chunks.push(chunk));
-    proxyRes.on("end", () => {
-      const respBody = Buffer.concat(chunks).toString();
-      const respHeaders = [];
-      for (const [k, v] of Object.entries(proxyRes.headers)) {
-        if (Array.isArray(v)) {
-          for (const val of v) {
-            respHeaders.push([k, val]);
-          }
-        } else {
-          respHeaders.push([k, v]);
-        }
-      }
-
-      const statusColor =
-        proxyRes.statusCode < 400 ? GREEN : RED;
-      console.log(
-        `${DIM}${timestamp}${RESET}  ${statusColor}${proxyRes.statusCode}${RESET} ${fullPath}`
-      );
-
-      ws.send(
-        JSON.stringify([
-          joinRef,
-          nextRef(),
-          topic,
-          "http_response",
-          {
-            request_id,
-            status: proxyRes.statusCode,
-            headers: respHeaders,
-            body: respBody,
-          },
-        ])
-      );
-    });
-  });
-
-  proxyReq.on("error", (err) => {
-    console.log(
-      `${DIM}${timestamp}${RESET}  ${RED}ERR${RESET} ${fullPath} — ${err.message}`
-    );
-    ws.send(
-      JSON.stringify([
-        joinRef,
-        nextRef(),
-        topic,
-        "http_response",
-        {
-          request_id,
-          status: 502,
-          headers: [["content-type", "text/plain"]],
-          body: `Could not connect to localhost:${PORT} — ${err.message}`,
-        },
-      ])
-    );
-  });
 
-  if (body && body.length > 0) {
-    proxyReq.write(body);
-  }
-  proxyReq.end();
-}
+const { port, host, apiKey, subdomain } = parseArgs(process.argv.slice(2));
 
-console.log(`${BOLD}runlocal${RESET} — expose localhost:${PORT} to the internet`);
-connect();
+console.log(`${BOLD}runlocal${RESET} — expose localhost:${port} to the internet`);
+createConnection({ host, port, apiKey, subdomain, WebSocket });

package/lib.js

@@ -0,0 +1,276 @@
+const http = require("http");
+
+const GREEN = "\x1b[32m";
+const CYAN = "\x1b[36m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+
+const TIPS = [
+  "Want a stable URL that never changes? Sign up at runlater.eu",
+  "Need request inspection & replay? Use with runlater.eu",
+  "Forward webhooks to multiple URLs at once with runlater.eu",
+];
+
+function parseArgs(argv) {
+  let port = 3000;
+  let host = process.env.RUNLOCAL_HOST || "wss://runlocal.eu";
+  let apiKey = process.env.RUNLATER_API_KEY || null;
+  let subdomain = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--host" && argv[i + 1]) {
+      host = argv[++i];
+    } else if (argv[i] === "--api-key" && argv[i + 1]) {
+      apiKey = argv[++i];
+    } else if (argv[i] === "--subdomain" && argv[i + 1]) {
+      subdomain = argv[++i];
+    } else if (argv[i] === "--help" || argv[i] === "-h") {
+      console.log("Usage: runlocal <port> [options]");
+      console.log("");
+      console.log("Options:");
+      console.log("  --host <url>        Server URL (default: wss://runlocal.eu)");
+      console.log("  --api-key <key>     Runlater API key for stable subdomain");
+      console.log("  --subdomain <name>  Custom subdomain (Pro plan, requires --api-key)");
+      console.log("  --help, -h          Show this help");
+      console.log("");
+      console.log("Environment:");
+      console.log("  RUNLOCAL_HOST       Same as --host");
+      console.log("  RUNLATER_API_KEY    Same as --api-key");
+      process.exit(0);
+    } else if (!argv[i].startsWith("-")) {
+      port = parseInt(argv[i], 10);
+    }
+  }
+
+  return { port, host, apiKey, subdomain };
+}
+
+function filterHeaders(headers) {
+  const filtered = {};
+  if (headers) {
+    for (const [k, v] of headers) {
+      if (k.toLowerCase() !== "host" && k.toLowerCase() !== "accept-encoding") {
+        filtered[k] = v;
+      }
+    }
+  }
+  return filtered;
+}
+
+function buildWsUrl(host, apiKey, subdomain) {
+  const params = new URLSearchParams({ vsn: "2.0.0" });
+  if (apiKey) params.set("api_key", apiKey);
+  if (subdomain) params.set("subdomain", subdomain);
+  return `${host}/tunnel/websocket?${params.toString()}`;
+}
+
+function handleRequest(ws, joinRef, topic, payload, port, nextRef, log) {
+  const { request_id, method, path, query_string, headers, body } = payload;
+  const fullPath = query_string ? `${path}?${query_string}` : path;
+
+  const timestamp = new Date().toLocaleTimeString();
+  log(
+    `${DIM}${timestamp}${RESET}  ${BOLD}${method}${RESET} ${fullPath}`
+  );
+
+  const reqHeaders = filterHeaders(headers);
+
+  const options = {
+    hostname: "127.0.0.1",
+    port: port,
+    path: fullPath,
+    method: method,
+    headers: reqHeaders,
+  };
+
+  const proxyReq = http.request(options, (proxyRes) => {
+    const chunks = [];
+    proxyRes.on("data", (chunk) => chunks.push(chunk));
+    proxyRes.on("end", () => {
+      const respBody = Buffer.concat(chunks).toString();
+      const respHeaders = [];
+      for (const [k, v] of Object.entries(proxyRes.headers)) {
+        if (Array.isArray(v)) {
+          for (const val of v) {
+            respHeaders.push([k, val]);
+          }
+        } else {
+          respHeaders.push([k, v]);
+        }
+      }
+
+      const statusColor =
+        proxyRes.statusCode < 400 ? GREEN : RED;
+      log(
+        `${DIM}${timestamp}${RESET}  ${statusColor}${proxyRes.statusCode}${RESET} ${fullPath}`
+      );
+
+      ws.send(
+        JSON.stringify([
+          joinRef,
+          nextRef(),
+          topic,
+          "http_response",
+          {
+            request_id,
+            status: proxyRes.statusCode,
+            headers: respHeaders,
+            body: respBody,
+          },
+        ])
+      );
+    });
+  });
+
+  proxyReq.on("error", (err) => {
+    log(
+      `${DIM}${timestamp}${RESET}  ${RED}ERR${RESET} ${fullPath} — ${err.message}`
+    );
+    ws.send(
+      JSON.stringify([
+        joinRef,
+        nextRef(),
+        topic,
+        "http_response",
+        {
+          request_id,
+          status: 502,
+          headers: [["content-type", "text/plain"]],
+          body: `Could not connect to localhost:${port} — ${err.message}`,
+        },
+      ])
+    );
+  });
+
+  if (body && body.length > 0) {
+    proxyReq.write(body);
+  }
+  proxyReq.end();
+}
+
+function createConnection(options) {
+  const {
+    host,
+    port,
+    apiKey,
+    subdomain,
+    WebSocket,
+    onTunnelCreated,
+    onClose,
+    log = console.log,
+    logError = console.error,
+  } = options;
+  const wsUrl = buildWsUrl(host, apiKey, subdomain);
+
+  let refCounter = 0;
+  const nextRef = () => String(++refCounter);
+
+  const ws = new WebSocket(wsUrl);
+  let heartbeatTimer = null;
+  let joinRef = null;
+
+  ws.on("open", () => {
+    const displayHost = host.replace(/^wss?:\/\//, "");
+    log(`${DIM}Connecting to ${displayHost}...${RESET}`);
+    joinRef = nextRef();
+    ws.send(JSON.stringify([joinRef, joinRef, "tunnel:connect", "phx_join", {}]));
+
+    heartbeatTimer = setInterval(() => {
+      ws.send(
+        JSON.stringify([null, nextRef(), "phoenix", "heartbeat", {}])
+      );
+    }, 30000);
+    heartbeatTimer.unref();
+  });
+
+  ws.on("message", (data) => {
+    const msg = JSON.parse(data.toString());
+    const [, , topic, event, payload] = msg;
+
+    if (event === "phx_reply" && topic === "tunnel:connect") {
+      if (payload.status === "ok") {
+        // Join succeeded, wait for tunnel_created push
+      } else {
+        const reason = payload.response && payload.response.reason;
+        if (reason === "invalid_api_key") {
+          logError(`${RED}Invalid API key. Check your --api-key or RUNLATER_API_KEY${RESET}`);
+        } else if (reason === "verification_failed") {
+          logError(`${RED}Subdomain verification failed${RESET}`);
+        } else if (reason === "verification_unavailable") {
+          logError(`${RED}Could not reach runlater.eu to verify API key${RESET}`);
+        } else {
+          logError(`${RED}Failed to join: ${JSON.stringify(payload)}${RESET}`);
+        }
+      }
+      return;
+    }
+
+    if (event === "tunnel_created") {
+      log("");
+      log(`  ${GREEN}${BOLD}Tunnel created!${RESET}`);
+      log(`  ${CYAN}${BOLD}${payload.url}${RESET}`);
+
+      if (payload.fallback) {
+        log(`  ${YELLOW}${payload.requested_subdomain} is already in use. Using random subdomain.${RESET}`);
+      }
+
+      log("");
+      log(`  ${DIM}Forwarding to localhost:${port}${RESET}`);
+      log(`  ${DIM}Press Ctrl+C to stop${RESET}`);
+
+      // Show tip for users without an API key
+      if (!apiKey) {
+        log("");
+        log(`  ${DIM}Tip: ${TIPS[Math.floor(Math.random() * TIPS.length)]}${RESET}`);
+      }
+
+      log("");
+      if (onTunnelCreated) onTunnelCreated(payload);
+      return;
+    }
+
+    if (event === "http_request") {
+      handleRequest(ws, joinRef, topic, payload, port, nextRef, log);
+      return;
+    }
+
+    if (event === "phx_close") {
+      log(`${YELLOW}Tunnel closed by server${RESET}`);
+      if (onClose) {
+        onClose();
+      } else {
+        process.exit(0);
+      }
+    }
+  });
+
+  ws.on("close", () => {
+    clearInterval(heartbeatTimer);
+    log(`${YELLOW}Disconnected. Reconnecting in 3s...${RESET}`);
+    const reconnectTimer = setTimeout(() => createConnection(options), 3000);
+    reconnectTimer.unref();
+  });
+
+  ws.on("error", (err) => {
+    if (err.code === "ECONNREFUSED") {
+      const displayHost = host.replace(/^wss?:\/\//, "");
+      logError(
+        `${RED}Could not connect to ${displayHost}${RESET}`
+      );
+    } else {
+      logError(`${RED}WebSocket error: ${err.message}${RESET}`);
+    }
+  });
+
+  return { ws, getJoinRef: () => joinRef, nextRef };
+}
+
+module.exports = {
+  parseArgs,
+  filterHeaders,
+  buildWsUrl,
+  handleRequest,
+  createConnection,
+};

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "runlocal",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Expose localhost to the internet via runlocal.eu",
   "bin": {
     "runlocal": "./index.js"
   },
-  "files": ["index.js"],
+  "files": ["index.js", "lib.js"],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "keywords": ["tunnel", "localhost", "ngrok", "dev", "https"],
   "license": "MIT",
   "dependencies": {