@dpkrn/nodetunnel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DpkRn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# @dpkrn/nodetunnel
+
+**nodetunnel** is a Node.js library for exposing a local HTTP server through a compatible tunnel server (yamux + JSON wire format). It is published on npm as **`@dpkrn/nodetunnel`**.
+
+```
+Internet ──► Tunnel Server ──► yamux stream ──► nodetunnel ──► localhost:<port>
+```
+
+**Requirements**
+
+- **Node.js 18+** (uses global `fetch` / `Headers`)
+- A running tunnel **server** reachable at `localhost:9000` (for example the [devtunnel](https://github.com/DpkRn/devtunnel) server)
+
+### Install from npm
+
+```bash
+npm install @dpkrn/nodetunnel
+```
+
+When developing **in this repository**, import with a relative path instead, for example:
+
+`import { startTunnel } from "./pkg/tunnel/tunnel.js"`.
+
+---
+
+## Quick start (ESM)
+
+This package is **`"type": "module"`**. Use `import`, not `require`.
+
+```js
+import http from "node:http";
+import { startTunnel } from "@dpkrn/nodetunnel";
+
+const PORT = 8080;
+
+const server = http.createServer((req, res) => {
+  res.writeHead(200, { "Content-Type": "text/plain" });
+  res.end("Hello from localhost\n");
+});
+
+server.listen(PORT, async () => {
+  try {
+    const { url, stop } = await startTunnel(String(PORT));
+    console.log("Public URL:", url);
+
+    process.on("SIGINT", () => {
+      stop();
+      server.close(() => process.exit(0));
+    });
+  } catch (e) {
+    console.error("Tunnel failed:", e.message);
+  }
+});
+```
+
+1. Start your tunnel **server** (port **9000**).
+2. Run your script: `node app.js`
+3. Open the printed **public URL** in a browser or `curl` it.
+
+---
+
+## API
+
+### `startTunnel(port, options?)`
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `port` | `string` | Local port your HTTP server listens on (e.g. `"8080"`). |
+| `options` | `object` (optional) | `{ host?: string, serverPort?: number }` — tunnel server address (default `localhost:9000`). |
+
+**Returns** a `Promise` resolving to:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | `string` | Public URL assigned by the server (e.g. `http://subdomain.localhost:3000`). |
+| `stop` | `() => void` | Stops the tunnel and closes the connection. |
+
+On failure (cannot connect, handshake error), the promise **rejects**. Use `try/catch`.
+
+---
+
+## Express example
+
+Start the HTTP server first, then call `startTunnel` with the **same port**.
+
+```js
+import express from "express";
+import { startTunnel } from "@dpkrn/nodetunnel";
+
+const app = express();
+const PORT = process.env.PORT || 8080;
+
+app.get("/", (req, res) => {
+  res.send("OK");
+});
+
+app.listen(PORT, async () => {
+  console.log(`http://127.0.0.1:${PORT}`);
+  try {
+    const { url, stop } = await startTunnel(String(PORT));
+    console.log("Public:", url);
+    process.once("SIGINT", () => {
+      stop();
+      process.exit(0);
+    });
+  } catch (e) {
+    console.error("Tunnel error:", e.message);
+  }
+});
+```
+
+---
+
+## Troubleshooting
+
+- **`Tunnel failed` / connection refused** — Start the tunnel server on the host/port you pass in `options` (default `localhost:9000`).
+- **Wrong path when running scripts** — Run from the `nodetunnel` directory, or use `node nodetunnel/cmd/test-lib/main.js` from the repo root.
+- **Port already in use** — Another process may be bound to your app port; stop it or change `PORT`.
+
+---
+
+## CLI — `mytunnel` (release install, ngrok-style)
+
+Besides embedding **nodetunnel** in a Node app, you can install the **`mytunnel`** CLI from **[devtunnel](https://github.com/DpkRn/devtunnel) releases** — same idea as **ngrok**: one binary, one command, expose a local port. It speaks the same tunnel server + yamux protocol as this library.
+
+```
+Internet ──► Tunnel Server ──► yamux stream ──► mytunnel ──► localhost:<port>
+```
+
+The **`mytunnel`** binary lets you expose any local port with a single command (no Node required for the client).
+
+### Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DpkRn/devtunnel/master/install.sh | bash
+```
+
+Auto-detects your OS and CPU architecture (macOS Apple Silicon, macOS Intel, Linux x86_64) and installs to `/usr/local/bin`.
+
+**Or build the Go client from source** (from the [devtunnel](https://github.com/DpkRn/devtunnel) or [gotunnel](https://github.com/DpkRn/gotunnel) repo):
+
+```bash
+go build -o mytunnel ./cmd/client
+sudo mv mytunnel /usr/local/bin/
+```
+
+### Usage
+
+```bash
+mytunnel http <port>
+```
+
+**Example — expose a dev server on port 3000:**
+
+```
+$ mytunnel http 3000
+
+  ╔══════════════════════════════════════════════════╗
+  ║   🚇  mytunnel — tunnel is live                  ║
+  ╠══════════════════════════════════════════════════╣
+  ║  🌍  Public   →  http://abc123.example.com        ║
+  ║  💻  Local    →  http://localhost:3000            ║
+  ╠══════════════════════════════════════════════════╣
+  ║  ⚡  Forwarding requests...                      ║
+  ║  🛑  Press Ctrl+C to stop                        ║
+  ╚══════════════════════════════════════════════════╝
+```
+
+Press `Ctrl+C` to stop.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `mytunnel http <port>` | Forward public HTTP traffic to `localhost:<port>` |
+| `mytunnel help` | Show help |
+
+You still need the **tunnel server** running (e.g. on `localhost:9000`) for both **nodetunnel** and **mytunnel**.
+
+---
+
+## Publishing to npm (maintainers)
+
+This package is published as **`@dpkrn/nodetunnel`** ([scoped package](https://docs.npmjs.com/about-scopes)). **`publishConfig.access`** is set to **`"public"`** so anyone can install it without an npm org.
+
+1. Bump **`version`** in `package.json` (semver).
+2. Dry run: `npm pack` — inspect the tarball.
+3. Log in: `npm login` (account must have permission to publish under the **`@dpkrn`** scope).
+4. From the **`nodetunnel`** directory: `npm publish`
+
+Adjust **`repository`**, **`bugs`**, and **`homepage`** in `package.json` if your Git remote or default branch differs.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/cmd/test-lib/main.js

@@ -0,0 +1,41 @@
+import express from "express";
+import { startTunnel } from "../../pkg/tunnel/tunnel.js";
+
+const app = express();
+app.set("etag", false);
+const PORT = process.env.PORT || 8080;
+/** Random id per process — if this doesn’t match your terminal on each restart, another process is bound to the port. */
+const INSTANCE = Math.random().toString(36).slice(2, 10);
+
+app.get("/health", (req, res) => {
+  res.status(200).json({
+    status: "OK",
+    uptime: process.uptime(),
+    timestamp: Date.now(),
+    message: "Server is healthy 🚀",
+  });
+});
+
+const ROOT_DELAY_MS = 10_000;
+
+// Return a Promise so Express 5’s router waits (see router Layer.handleRequest).
+app.get("/", async (req, res) => {
+  
+  await new Promise((resolve) => setTimeout(resolve, ROOT_DELAY_MS));
+  res.send("Backend is running");
+});
+
+app.listen(PORT, async () => {
+  console.log(`listening on http://127.0.0.1:${PORT}`);
+  console.log("Leave this terminal open; press Ctrl+C to stop.");
+  try {
+    const { url, stop } = await startTunnel(String(PORT));
+    console.log("🌍 Public URL:", url);
+    process.once("SIGINT", () => {
+      stop();
+      process.exit(0);
+    });
+  } catch (e) {
+    console.error("Tunnel failed (is devtunnel server on :9000?):", e.message);
+  }
+});

package/internal/models/protocol/request.js

@@ -0,0 +1,12 @@
+/**
+ * Wire format: JSON line from tunnel server → client (per yamux stream).
+ * Matches gotunnel / devtunnel Go `TunnelRequest`.
+ *
+ * @typedef {Object} TunnelRequest
+ * @property {string} Method
+ * @property {string} Path
+ * @property {Record<string, string[]>} [Headers]
+ * @property {string} [Body] base64 (Go encoding/json for []byte)
+ */
+
+module.exports = {};

package/internal/models/protocol/response.js

@@ -0,0 +1,11 @@
+/**
+ * Wire format: JSON line from client → tunnel server (per yamux stream).
+ * Matches gotunnel / devtunnel Go `TunnelResponse`.
+ *
+ * @typedef {Object} TunnelResponse
+ * @property {number} Status
+ * @property {Record<string, string[]>} Headers
+ * @property {string} Body base64 (Go encoding/json for []byte)
+ */
+
+module.exports = {};

package/internal/tunnel/tunnel.js

@@ -0,0 +1,239 @@
+import net from 'node:net';
+import { Session } from 'yamux-js/lib/session.js';
+
+const defaultMuxConfig = {
+  enableKeepAlive: false,
+  logger: () => {},
+};
+
+/**
+ * Read until first LF; returns trimmed line (without \n) and any bytes after it.
+ * @param {import('net').Socket} socket
+ */
+function readPublicUrlLine(socket) {
+  return new Promise((resolve, reject) => {
+    let buffer = Buffer.alloc(0);
+
+    const onError = (err) => {
+      socket.off('data', onData);
+      reject(err);
+    };
+
+    const onData = (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      const nl = buffer.indexOf(0x0a);
+      if (nl >= 0) {
+        socket.off('data', onData);
+        socket.off('error', onError);
+        const line = buffer.subarray(0, nl).toString('utf8').trim();
+        const remainder = buffer.subarray(nl + 1);
+        resolve({ line, remainder });
+      }
+    };
+
+    socket.on('data', onData);
+    socket.on('error', onError);
+  });
+}
+
+/**
+ * Read one line (LF-terminated) from a yamux duplex stream.
+ * @param {import('stream').Duplex} stream
+ */
+function readJsonLine(stream) {
+  return new Promise((resolve, reject) => {
+    let buffer = Buffer.alloc(0);
+
+    const onError = (err) => {
+      stream.off('data', onData);
+      reject(err);
+    };
+
+    const onData = (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      const nl = buffer.indexOf(0x0a);
+      if (nl >= 0) {
+        stream.off('data', onData);
+        stream.off('error', onError);
+        const line = buffer.subarray(0, nl).toString('utf8');
+        resolve(line);
+      }
+    };
+
+    stream.on('data', onData);
+    stream.on('error', onError);
+  });
+}
+
+/** @param {unknown} body */
+function decodeRequestBody(body) {
+  if (body == null || body === '') return Buffer.alloc(0);
+  if (typeof body === 'string') return Buffer.from(body, 'base64');
+  if (Buffer.isBuffer(body)) return body;
+  if (Array.isArray(body)) return Buffer.from(body);
+  return Buffer.alloc(0);
+}
+
+/** @param {Headers | import('http').IncomingHttpHeaders} h */
+function headersToObject(h) {
+  const out = {};
+  if (h && typeof h.forEach === 'function') {
+    h.forEach((value, key) => {
+      if (!out[key]) out[key] = [];
+      out[key].push(value);
+    });
+    return out;
+  }
+  for (const [key, val] of Object.entries(h || {})) {
+    if (val == null) continue;
+    out[key] = Array.isArray(val) ? val : [val];
+  }
+  return out;
+}
+
+/**
+ * @param {import('stream').Duplex} stream
+ * @param {string} port
+ */
+async function handleStream(stream, port) {
+  try {
+    const line = await readJsonLine(stream);
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    const method = req.Method || 'GET';
+    const path = req.Path || '/';
+    const target = new URL(path, `http://127.0.0.1:${port}`).toString();
+    const body = decodeRequestBody(req.Body);
+
+    const headers = new Headers();
+    const raw = req.Headers || {};
+    for (const [k, vals] of Object.entries(raw)) {
+      if (!Array.isArray(vals)) continue;
+      for (const v of vals) {
+        if (v != null) headers.append(k, String(v));
+      }
+    }
+
+    /** @type {{ method: string; headers: Headers; body?: Buffer }} */
+    const init = { method, headers };
+    if (body.length) init.body = body;
+
+    const resp = await fetch(target, init);
+
+    const respBody = Buffer.from(await resp.arrayBuffer());
+    const payload = {
+      Status: resp.status,
+      Headers: headersToObject(resp.headers),
+      Body: respBody.toString('base64'),
+    };
+
+    stream.end(Buffer.from(`${JSON.stringify(payload)}\n`, 'utf8'));
+  } catch (e) {
+    try {
+      stream.destroy();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * @typedef {Object} TunnelOptions
+ * @property {string} [host] tunnel server host (default localhost)
+ * @property {number} [serverPort] tunnel server TCP port (default 9000)
+ */
+
+class Tunnel {
+  /**
+   * @param {string} localPort local HTTP port to forward to
+   * @param {TunnelOptions} [options]
+   */
+  constructor(localPort, options = {}) {
+    this.localPort = localPort;
+    this.serverHost = options.host ?? 'localhost';
+    this.serverPort = options.serverPort ?? 9000;
+    /** @type {import('net').Socket | null} */
+    this.socket = null;
+    /** @type {InstanceType<typeof Session> | null} */
+    this.session = null;
+    this.publicUrl = '';
+    this._stopped = false;
+  }
+
+  /**
+   * Connect, read assigned public URL (plaintext line before yamux), start yamux client.
+   * Matches devtunnel server: URL line first, then hashicorp-compatible yamux.
+   */
+  async connect() {
+    const socket = net.createConnection({
+      host: this.serverHost,
+      port: this.serverPort,
+    });
+
+    await new Promise((resolve, reject) => {
+      socket.once('connect', resolve);
+      socket.once('error', reject);
+    });
+
+    const { line, remainder } = await readPublicUrlLine(socket);
+    this.publicUrl = `http://${line}`;
+
+    const session = new Session(true, defaultMuxConfig, (stream) => {
+      handleStream(stream, this.localPort);
+    });
+
+    this.socket = socket;
+    this.session = session;
+
+    if (remainder.length) {
+      session.write(remainder);
+    }
+    socket.pipe(session);
+    session.pipe(socket);
+
+    session.on('error', () => {});
+    socket.on('error', () => {});
+  }
+
+  getPublicUrl() {
+    return this.publicUrl;
+  }
+
+  stop() {
+    if (this._stopped) return;
+    this._stopped = true;
+    try {
+      if (this.session) {
+        this.session.close();
+        this.session = null;
+      }
+    } catch {
+      /* ignore */
+    }
+    try {
+      if (this.socket) {
+        this.socket.destroy();
+        this.socket = null;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * @param {string} localPort
+ * @param {TunnelOptions} [options]
+ */
+async function newTunnel(localPort, options) {
+  const t = new Tunnel(localPort, options);
+  await t.connect();
+  return t;
+}
+
+export { Tunnel, newTunnel };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@dpkrn/nodetunnel",
+  "version": "1.0.0",
+  "description": "Expose a local HTTP server through a devtunnel/gotunnel-compatible server (yamux + JSON). Node.js 18+.",
+  "keywords": [
+    "tunnel",
+    "ngrok",
+    "yamux",
+    "devtunnel",
+    "gotunnel",
+    "localhost",
+    "expose",
+    "http",
+    "multiplex"
+  ],
+  "homepage": "https://github.com/DpkRn/NGROK/tree/main/nodetunnel#readme",
+  "bugs": {
+    "url": "https://github.com/DpkRn/NGROK/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DpkRn/NGROK.git",
+    "directory": "nodetunnel"
+  },
+  "license": "MIT",
+  "author": "DpkRn (https://github.com/DpkRn)",
+  "type": "module",
+  "main": "./pkg/tunnel/tunnel.js",
+  "exports": {
+    ".": {
+      "import": "./pkg/tunnel/tunnel.js",
+      "default": "./pkg/tunnel/tunnel.js"
+    },
+    "./pkg/tunnel": "./pkg/tunnel/tunnel.js",
+    "./pkg/tunnel/tunnel.js": "./pkg/tunnel/tunnel.js"
+  },
+  "files": [
+    "pkg",
+    "internal",
+    "cmd",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test-lib": "node cmd/test-lib/main.js",
+    "prepublishOnly": "node -e \"import('./pkg/tunnel/tunnel.js').then(() => console.log('pack ok')).catch(e => { console.error(e); process.exit(1); })\""
+  },
+  "dependencies": {
+    "yamux-js": "^0.2.0"
+  },
+  "devDependencies": {
+    "express": "^5.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/pkg/tunnel/tunnel.js

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * Public API: expose a local HTTP server through a gotunnel-compatible tunnel server.
+ *
+ * @example
+ * import http from 'node:http';
+ * import { startTunnel } from '@dpkrn/nodetunnel';
+ *
+ * const server = http.createServer((req, res) => {
+ *   res.end('ok');
+ * });
+ * server.listen(8080, async () => {
+ *   const { url, stop } = await startTunnel('8080');
+ *   console.log('Public URL:', url);
+ *   process.on('SIGINT', () => { stop(); process.exit(0); });
+ * });
+ */
+
+import { newTunnel } from '../../internal/tunnel/tunnel.js';
+
+/**
+ * Connect to the tunnel server and forward public HTTP traffic to localhost:<port>.
+ *
+ * @param {string} port local port (e.g. "8080")
+ * @param {{ host?: string, serverPort?: number }} [options] tunnel server (default localhost:9000)
+ * @returns {Promise<{ url: string, stop: () => void }>}
+ */
+async function startTunnel(port, options) {
+  const tunnel = await newTunnel(String(port), options);
+
+  console.log('✅Public url:', tunnel.getPublicUrl());
+
+  return {
+    url: tunnel.getPublicUrl(),
+    stop: () => tunnel.stop(),
+  };
+}
+
+export { startTunnel };