@cvasingh/httpsurl 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# @httpsurl/client
+
+CLI tool to expose local HTTP servers to the internet via httpsurl.in tunnels.
+
+## Installation
+
+```bash
+# From the monorepo root
+npm install
+
+# Or install globally (after publishing)
+npm install -g @httpsurl/client
+```
+
+## Usage
+
+### Login
+
+```bash
+# Opens browser for Clerk authentication
+httpsurl login
+
+# Or provide token directly
+httpsurl login --token <clerk-session-token>
+```
+
+Token is stored in `~/.httpsurl/credentials.json` (chmod 600).
+
+### Create a Tunnel
+
+```bash
+# Expose local port 3000
+httpsurl http 3000
+
+# Custom server URL
+httpsurl http 8080 --server wss://httpsurl.in/connect
+
+# Local development
+httpsurl http 8080 --server ws://localhost:3000/connect
+```
+
+Output:
+
+```
+ℹ Connecting to wss://httpsurl.in/connect...
+ℹ Connected, registering tunnel...
+✔ Tunnel registered!
+
+  httpsurl.in
+  ─────────────────────────────
+  ▸ Forwarding: http://abc123def.httpsurl.in
+  ─────────────────────────────
+
+→ GET     /            200 12ms
+→ POST    /api/data    201 45ms
+→ GET     /style.css   200  3ms
+```
+
+## Modules
+
+### `cli.js` — Commander CLI
+Two commands:
+- `httpsurl login` — Opens browser to Clerk sign-in, receives token via localhost callback server
+- `httpsurl http <port>` — Creates tunnel with `--server` option (default: `wss://httpsurl.in/connect`)
+
+### `tunnel-client.js` — WebSocket Client
+- Connects to server, sends `register` message with Clerk token
+- Receives `registered` with tunnel URL
+- Handles `request` messages by proxying to local server via `local-proxy.js`
+- Sends `response` or `response_error` back
+- Auto-reconnects with exponential backoff on disconnect
+- Preserves tunnel ID across reconnections
+
+### `local-proxy.js` — HTTP Proxy
+- Makes HTTP requests to `127.0.0.1:<port>`
+- Strips `host` and `x-tunnel-host` headers
+- Base64 encodes/decodes request and response bodies
+- 30s timeout per request
+
+### `reconnect.js` — Exponential Backoff
+- Initial delay: 1s
+- Doubles each attempt: 1s → 2s → 4s → 8s → 16s → 30s (max)
+- Resets on successful reconnection
+- Cancellable
+
+### `logger.js` — Terminal Output
+Colored output using chalk:
+- `info` — blue
+- `success` — green
+- `warn` — yellow
+- `error` — red
+- `request` — method-colored badges with status code and latency
+- `banner` — formatted tunnel URL display
+
+### `protocol.js` — Message Constants
+Shared message type constants (duplicated from server for simplicity):
+- `MSG_REGISTER`, `MSG_RESPONSE`, `MSG_RESPONSE_ERROR`
+- `MSG_REGISTERED`, `MSG_REQUEST`, `MSG_ERROR`
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| ws | WebSocket client |
+| commander | CLI argument parsing |
+| chalk (v4, CJS) | Terminal colors |
+| nanoid (v3, CJS) | Request ID generation |
+| open (v8) | Open browser for login |

package/bin/httpsurl.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+const { createCli } = require('../src/cli');
+
+const program = createCli();
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cvasingh/httpsurl",
+  "version": "1.0.0",
+  "description": "Expose local servers to the internet via httpsurl.in tunnels",
+  "keywords": [
+    "tunnel",
+    "localhost",
+    "ngrok",
+    "proxy",
+    "cli",
+    "httpsurl"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cvasingh/httpsurl.git",
+    "directory": "packages/client"
+  },
+  "author": "cvasingh",
+  "bin": {
+    "httpsurl": "bin/httpsurl.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.0.0",
+    "nanoid": "^3.3.7",
+    "open": "^8.4.2",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,134 @@
+const { Command } = require('commander');
+const { TunnelClient } = require('./tunnel-client');
+const log = require('./logger');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CREDENTIALS_DIR = path.join(os.homedir(), '.httpsurl');
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'credentials.json');
+
+function loadToken() {
+  try {
+    const data = JSON.parse(fs.readFileSync(CREDENTIALS_FILE, 'utf8'));
+    return data.token;
+  } catch {
+    return null;
+  }
+}
+
+function saveToken(token) {
+  fs.mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify({ token }, null, 2));
+  fs.chmodSync(CREDENTIALS_FILE, 0o600);
+}
+
+function createCli() {
+  const program = new Command();
+
+  program
+    .name('httpsurl')
+    .description('Expose local servers to the internet via httpsurl.in')
+    .version('1.0.0');
+
+  // Login command
+  program
+    .command('login')
+    .description('Authenticate with httpsurl.in')
+    .option('--token <token>', 'Provide token directly')
+    .action(async (options) => {
+      if (options.token) {
+        saveToken(options.token);
+        log.success('Token saved!');
+        return;
+      }
+
+      // Open browser for Clerk auth
+      const http = require('http');
+
+      const server = http.createServer((req, res) => {
+        const url = new URL(req.url, 'http://localhost');
+        const token = url.searchParams.get('token');
+
+        if (token) {
+          saveToken(token);
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end(`
+            <html>
+            <body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0;">
+              <div style="text-align: center;">
+                <h1 style="font-weight: 300;">✓ Authenticated</h1>
+                <p style="color: #666;">You can close this window and return to the terminal.</p>
+              </div>
+            </body>
+            </html>
+          `);
+          server.close();
+          log.success('Authenticated successfully!');
+          process.exit(0);
+        } else {
+          res.writeHead(400);
+          res.end('Missing token');
+        }
+      });
+
+      server.listen(0, async () => {
+        const port = server.address().port;
+        const callbackUrl = `http://localhost:${port}`;
+        const loginUrl = `https://httpsurl.in/sign-in?redirect_url=${encodeURIComponent(callbackUrl)}`;
+
+        log.info(`Opening browser for authentication...`);
+        log.info(`If browser doesn't open, visit: ${loginUrl}`);
+
+        try {
+          const open = require('open');
+          await open(loginUrl);
+        } catch {
+          log.warn('Could not open browser automatically');
+        }
+      });
+    });
+
+  // HTTP tunnel command
+  program
+    .command('http')
+    .description('Create a tunnel to a local HTTP server')
+    .argument('<port>', 'Local port to expose', parseInt)
+    .option('-s, --server <url>', 'Server WebSocket URL', 'wss://httpsurl.in/connect')
+    .action(async (port, options) => {
+      if (!port || port < 1 || port > 65535) {
+        log.error('Invalid port number');
+        process.exit(1);
+      }
+
+      const token = loadToken();
+      if (!token) {
+        log.error('Not authenticated. Run: httpsurl login');
+        process.exit(1);
+      }
+
+      const client = new TunnelClient({
+        serverUrl: options.server,
+        localPort: port,
+        token,
+      });
+
+      // Graceful shutdown
+      process.on('SIGINT', () => {
+        log.info('\nShutting down...');
+        client.close();
+        process.exit(0);
+      });
+
+      try {
+        await client.connect();
+      } catch (err) {
+        log.error(`Failed to connect: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  return program;
+}
+
+module.exports = { createCli };

package/src/local-proxy.js

@@ -0,0 +1,52 @@
+const http = require('http');
+
+function makeLocalRequest(port, requestData) {
+  return new Promise((resolve, reject) => {
+    const { method, path, headers, body } = requestData;
+
+    // Remove headers that shouldn't be forwarded to local server
+    const localHeaders = { ...headers };
+    delete localHeaders.host;
+    delete localHeaders['x-tunnel-host'];
+
+    const options = {
+      hostname: '127.0.0.1',
+      port,
+      path,
+      method,
+      headers: localHeaders,
+    };
+
+    const req = http.request(options, (res) => {
+      const chunks = [];
+
+      res.on('data', (chunk) => chunks.push(chunk));
+
+      res.on('end', () => {
+        const responseBody = Buffer.concat(chunks);
+        resolve({
+          statusCode: res.statusCode,
+          headers: res.headers,
+          body: responseBody.length > 0 ? responseBody.toString('base64') : null,
+        });
+      });
+    });
+
+    req.on('error', (err) => {
+      reject(new Error(`Local server error: ${err.message}`));
+    });
+
+    // Set timeout
+    req.setTimeout(30000, () => {
+      req.destroy(new Error('Local server timeout'));
+    });
+
+    if (body) {
+      req.write(Buffer.from(body, 'base64'));
+    }
+
+    req.end();
+  });
+}
+
+module.exports = { makeLocalRequest };

package/src/logger.js

@@ -0,0 +1,45 @@
+const chalk = require('chalk');
+
+const log = {
+  info(msg, ...args) {
+    console.log(chalk.blue('ℹ'), msg, ...args);
+  },
+  success(msg, ...args) {
+    console.log(chalk.green('✔'), msg, ...args);
+  },
+  warn(msg, ...args) {
+    console.log(chalk.yellow('⚠'), msg, ...args);
+  },
+  error(msg, ...args) {
+    console.error(chalk.red('✖'), msg, ...args);
+  },
+  request(method, path, statusCode, latency) {
+    const methodColor = {
+      GET: chalk.cyan,
+      POST: chalk.green,
+      PUT: chalk.yellow,
+      DELETE: chalk.red,
+      PATCH: chalk.magenta,
+    };
+    const colorFn = methodColor[method] || chalk.white;
+    const statusColor = statusCode < 400 ? chalk.green : statusCode < 500 ? chalk.yellow : chalk.red;
+
+    console.log(
+      chalk.gray('→'),
+      colorFn(method.padEnd(7)),
+      chalk.white(path),
+      statusColor(statusCode),
+      chalk.gray(`${latency}ms`)
+    );
+  },
+  banner(url) {
+    console.log('');
+    console.log(chalk.bold('  httpsurl.in'));
+    console.log(chalk.gray('  ─────────────────────────────'));
+    console.log(`  ${chalk.green('▸')} Forwarding: ${chalk.cyan.underline(url)}`);
+    console.log(chalk.gray('  ─────────────────────────────'));
+    console.log('');
+  },
+};
+
+module.exports = log;

package/src/protocol.js

@@ -0,0 +1,11 @@
+module.exports = {
+  // Client → Server
+  MSG_REGISTER: 'register',
+  MSG_RESPONSE: 'response',
+  MSG_RESPONSE_ERROR: 'response_error',
+
+  // Server → Client
+  MSG_REGISTERED: 'registered',
+  MSG_REQUEST: 'request',
+  MSG_ERROR: 'error',
+};

package/src/reconnect.js

@@ -0,0 +1,33 @@
+class ReconnectStrategy {
+  constructor(options = {}) {
+    this.initialDelay = options.initialDelay || 1000;
+    this.maxDelay = options.maxDelay || 30000;
+    this.currentDelay = this.initialDelay;
+    this._timer = null;
+  }
+
+  schedule(fn) {
+    const delay = this.currentDelay;
+    this._timer = setTimeout(fn, delay);
+    // Exponential backoff
+    this.currentDelay = Math.min(this.currentDelay * 2, this.maxDelay);
+    return delay;
+  }
+
+  reset() {
+    this.currentDelay = this.initialDelay;
+  }
+
+  cancel() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+
+  destroy() {
+    this.cancel();
+  }
+}
+
+module.exports = { ReconnectStrategy };

package/src/tunnel-client.js

@@ -0,0 +1,151 @@
+const WebSocket = require('ws');
+const { MSG_REGISTER, MSG_REGISTERED, MSG_REQUEST, MSG_RESPONSE, MSG_RESPONSE_ERROR, MSG_ERROR } = require('./protocol');
+const { makeLocalRequest } = require('./local-proxy');
+const { ReconnectStrategy } = require('./reconnect');
+const log = require('./logger');
+
+class TunnelClient {
+  constructor(options) {
+    this.serverUrl = options.serverUrl;
+    this.localPort = options.localPort;
+    this.token = options.token;
+    this.tunnelId = null;
+    this.tunnelUrl = null;
+    this.ws = null;
+    this._reconnect = new ReconnectStrategy();
+    this._closing = false;
+    this._requestCount = 0;
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      this._closing = false;
+      const url = this.serverUrl;
+
+      log.info(`Connecting to ${url}...`);
+
+      this.ws = new WebSocket(url);
+
+      this.ws.on('open', () => {
+        log.info('Connected, registering tunnel...');
+
+        // Send register message
+        this.ws.send(JSON.stringify({
+          type: MSG_REGISTER,
+          token: this.token,
+          port: this.localPort,
+          tunnelId: this.tunnelId, // null on first connect, set on reconnect
+        }));
+      });
+
+      this.ws.on('message', (data) => {
+        let msg;
+        try {
+          msg = JSON.parse(data.toString());
+        } catch {
+          log.error('Invalid message from server');
+          return;
+        }
+
+        this._handleMessage(msg, resolve);
+      });
+
+      this.ws.on('close', (code, reason) => {
+        if (this._closing) return;
+
+        log.warn(`Disconnected (code: ${code}). Reconnecting...`);
+        const delay = this._reconnect.schedule(() => this.connect());
+        log.info(`Reconnecting in ${delay}ms...`);
+      });
+
+      this.ws.on('error', (err) => {
+        if (this._closing) return;
+
+        // Only reject on first connection attempt
+        if (!this.tunnelId) {
+          reject(err);
+        }
+        log.error(`WebSocket error: ${err.message}`);
+      });
+    });
+  }
+
+  _handleMessage(msg, resolveConnect) {
+    switch (msg.type) {
+      case MSG_REGISTERED: {
+        this.tunnelId = msg.tunnelId;
+        this.tunnelUrl = msg.url;
+        this._reconnect.reset();
+
+        log.success(`Tunnel registered!`);
+        log.banner(`http://${msg.url}`);
+
+        if (resolveConnect) resolveConnect(this);
+        break;
+      }
+
+      case MSG_REQUEST: {
+        this._handleRequest(msg);
+        break;
+      }
+
+      case MSG_ERROR: {
+        log.error(`Server error: ${msg.error}`);
+        break;
+      }
+    }
+  }
+
+  async _handleRequest(msg) {
+    const { requestId, method, path, headers, body } = msg;
+    const start = Date.now();
+    this._requestCount++;
+
+    try {
+      const response = await makeLocalRequest(this.localPort, {
+        method,
+        path,
+        headers,
+        body,
+      });
+
+      this.ws.send(JSON.stringify({
+        type: MSG_RESPONSE,
+        requestId,
+        statusCode: response.statusCode,
+        headers: response.headers,
+        body: response.body,
+      }));
+
+      const latency = Date.now() - start;
+      log.request(method, path, response.statusCode, latency);
+    } catch (err) {
+      this.ws.send(JSON.stringify({
+        type: MSG_RESPONSE_ERROR,
+        requestId,
+        error: err.message,
+      }));
+
+      log.error(`${method} ${path} → Error: ${err.message}`);
+    }
+  }
+
+  close() {
+    this._closing = true;
+    this._reconnect.destroy();
+    if (this.ws) {
+      this.ws.close(1000, 'Client closing');
+    }
+  }
+
+  get stats() {
+    return {
+      tunnelId: this.tunnelId,
+      url: this.tunnelUrl,
+      requestCount: this._requestCount,
+      connected: this.ws?.readyState === WebSocket.OPEN,
+    };
+  }
+}
+
+module.exports = { TunnelClient };