@dpkrn/nodetunnel 1.1.0 → 1.1.1

package/README.md

@@ -16,7 +16,7 @@ From **Node.js**, you get a **public URL** for webhooks, demos, sharing a dev se
 - No port forwarding or firewall configuration needed
 - Works behind NAT or private networks
 - Simple integration with existing Node.js HTTP servers (Express, Fastify, plain `http`, etc.)
-- Traffic inspector: capture traffic, replay, and modify requests as many times as you need
+- Optional **traffic inspector**: local dashboard to capture tunneled requests, inspect them, and replay against your app
 
 Incoming traffic reaches the public URL, is forwarded through the tunnel, and is proxied to your local HTTP server (e.g., `localhost:8080`).
 
@@ -40,7 +40,7 @@ This enables exposing local development servers without port forwarding, firewal
 - **No separate tunnel process** — call one function from your app.
 - **Works with your existing server** — Express, Fastify, or plain `http`.
 - **Simple API** — you get a public `url` and a `stop()` when you are done.
-- **Optional traffic inspector** — local dashboard on loopback to browse captures, replay requests, modify and pick a theme (see below).
+- **Optional traffic inspector** — pass `inspector: true` to start a local HTTP UI on loopback (captures, replay, headers/bodies). By default the inspector is **off**. Themes are chosen **inside the inspector UI** (not via `startTunnel` options).
 
 ---
 
@@ -54,8 +54,6 @@ This package is **ESM** (`import` / `export`).
 
 ---
 
-
-
 ## Quick Example
 
 ```js
@@ -69,8 +67,8 @@ app.get("/", (req, res) => res.send("OK"));
 
 app.listen(PORT, async () => {
   const { url, stop } = await startTunnel(String(PORT));
-  //url is your public url using you can access publicly your server
-  //stop() is method that will close your connection on error
+  // `url` — public URL for your server
+  // `stop()` — closes the tunnel connection
 });
 ```
 
@@ -107,29 +105,33 @@ Run with `node app.js`. Open the printed URL in a browser or share it for webhoo
 
 ---
 
-## Traffic inspector (local dashboard)
+## Traffic inspector (optional local dashboard)
+
+**Default:** `inspector` is **`false`** if you omit options or do not set `inspector`. No inspector server, no capture buffer, no extra listen port.
 
-When enabled (default), nodetunnel starts a small **HTTP server on your machine** (default `http://localhost:4040`) with:
+When **`inspector: true`**:
 
-- **Live traffic** — requests proxied through the tunnel appear in the UI (WebSocket updates).
-- **History** — recent captures kept in memory (configurable count); reload the page to fetch `/logs`.
-- **Inspect** — request/response headers and bodies for each capture.
-- **Modify** — modify request header/path and can replay.
-- **Replay** — send a capture again to your local app, or edit method/path/headers/body and replay (aligned with the **gotunnel** inspector behavior).
+1. Starts a small **HTTP server on your machine** (default listen **`http://127.0.0.1:4040`**) that serves the inspector UI (override with `inspectorAddr`).
+2. **Captures** each tunneled request/response in memory (up to **`logs`** entries) so the UI can list them and push updates over WebSocket.
 
-The startup banner prints **Inspector →** with that URL. Set `inspector: false` if you do not want the UI or an extra listen port.
+When **`inspector` stays false** (the default):
 
-### Themes
+- No inspector process runs — nothing listens on the inspector port.
+- No traffic is stored for inspection (`logs` and `inspectorAddr` are ignored).
+- The startup banner omits the **Inspector →** line.
 
-The UI supports three built-in palettes via `themes` in `startTunnel` options:
+### What you get with the inspector enabled
 
-| Value | Appearance |
-|--------|----------------|
-| **`"dark"`** (default) | Dark panels, blue accents — similar to GitHub-dark style. |
-| **`"terminal"`** | Green-on-black “CRT” / terminal aesthetic, monospace UI font. |
-| **`"light"`** | Light gray/white background, high-contrast text for bright environments. |
+- **Live traffic** — tunneled requests appear in the UI (WebSocket updates).
+- **History** — recent captures in memory (size limited by `logs`).
+- **Inspect** — request/response headers and bodies (when captured).
+- **Replay** — send a capture again to your local app, or edit method/path/headers/body and replay.
 
-### Example: themes and inspector options
+### Themes (inspector UI only)
+
+Postman-style and Terminal-style palettes are available from the **Theme** dropdown in the inspector page; the choice is stored in the browser (localStorage). You do **not** configure themes on `startTunnel`.
+
+### Example: inspector enabled with custom port and log limit
 
 ```js
 import http from "node:http";
@@ -144,16 +146,11 @@ const server = http.createServer((req, res) => {
 
 server.listen(PORT, async () => {
   const { url, stop } = await startTunnel(String(PORT), {
-    // Inspector (defaults: enabled, :4040, dark theme, 100 logs)
     inspector: true,
     inspectorAddr: ":4040",
-    themes: "terminal", // try: "dark" | "terminal" | "light"
     logs: 100,
   });
 
-  // console.log("Public:", url);
-  // Open the Inspector URL from stderr in a browser (e.g. http://localhost:4040)
-
   process.once("SIGINT", () => {
     stop();
     server.close(() => process.exit(0));
@@ -161,14 +158,14 @@ server.listen(PORT, async () => {
 });
 ```
 
-### Example: tunnel only (no inspector)
+Open the **Inspector →** URL printed on startup (e.g. `http://127.0.0.1:4040`).
 
-```js
-import { startTunnel } from "@dpkrn/nodetunnel";
+### Example: tunnel only (default — same as omitting options)
 
-const { url, stop } = await startTunnel("8080", {
-  inspector: false,
-});
+`startTunnel(port)` / `startTunnel(port, {})` already keeps the inspector off. You only need `inspector: false` if you merge options from elsewhere and want to force it off:
+
+```js
+const { url, stop } = await startTunnel("8080"); // no inspector
 ```
 
 ---
@@ -207,27 +204,26 @@ app.listen(PORT, async () => {
 | Argument | Description |
 |----------|-------------|
 | `port` | String, e.g. `"8080"` — must match the port your HTTP server uses. |
-| `options` | Optional. Object — see **Options** below (tunnel server address, inspector, themes, etc.). |
+| `options` | Optional. See **Options** below. |
 
 **Returns:** `{ url, stop }`
 
 | Field | Description |
 |-------|-------------|
 | `url` | Public URL people can hit. |
-| `stop` | Call to tear down the tunnel. |
+| `stop` | Call to tear down the tunnel (and the inspector, if it was started). |
 
 Errors **reject** the promise — use `try/catch`.
 
 ### Options (`startTunnel` second argument)
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `host` | `string` | `'clickly.cv'` | Hostname of the tunnel **control** server. |
-| `serverPort` | `number` | `9000` | TCP port of the tunnel server. |
-| `inspector` | `boolean` | `true` | If `true`, start the local traffic inspector UI (see [Traffic inspector](#traffic-inspector-local-dashboard)). If `false`, no extra HTTP server and no Inspector line in the banner. |
-| `themes` | `string` | `'dark'` | Inspector palette: `'dark'`, `'terminal'`, or `'light'`. |
-| `logs` | `number` | `100` | Maximum number of request/response captures kept in memory for the inspector. |
-| `inspectorAddr` | `string` | `':4040'` | Listen address for the inspector (e.g. `':4040'`, `'localhost:9090'`). Display URL follows the same rules as the public banner. |
+| Field | Type | Default | Applies when |
+|-------|------|---------|----------------|
+| `host` | `string` | `'clickly.cv'` | Always — tunnel control server hostname. |
+| `serverPort` | `number` | `9000` | Always — TCP port of the tunnel server. |
+| `inspector` | `boolean` | `false` | Always — if `false` (default), no inspector UI, no capture store, and inspector-only options below are ignored. Set `true` to enable the local inspector. |
+| `logs` | `number` | `100` | **`inspector: true` only** — max request/response captures kept in memory. |
+| `inspectorAddr` | `string` | `':4040'` | **`inspector: true` only** — listen address for the inspector (e.g. `':4040'`, `'localhost:9090'`). |
 
 ---
 

package/cmd/test-lib/main.js

@@ -44,7 +44,11 @@ app.post("/test/:category/:itemId", (req, res) => {
 app.listen(PORT, async () => {
   console.log(`listening on http://localhost:${PORT}`);
   try {
-    const { url, stop } = await startTunnel(String(PORT));
+    const { url, stop } = await startTunnel(String(PORT),{
+      inspector: true,
+      inspectorAddr: ':5040',
+      logs: 100,
+    });
     process.once("SIGINT", () => {
       stop();
       process.exit(0);

package/internal/inspector/inspector.js

@@ -43,13 +43,9 @@ export function inspectorHTTPBaseURL(opts) {
   return `http://${addr}`;
 }
 
-/** @param {string | undefined} themes */
-function themeSeedFromOpts(themes) {
-  const t = String(themes ?? '')
-    .trim()
-    .toLowerCase();
-  if (t === 'terminal') return 'terminal';
-  return 'postman';
+/** Default HTML theme before localStorage applies (UI also has a theme switcher). */
+function defaultInspectorThemeSeed() {
+  return 'terminal';
 }
 
 /** @param {string} host */
@@ -409,7 +405,7 @@ function parseListenAddr(addr) {
 }
 
 /**
- * @param {{ inspector?: boolean; themes?: string; inspectorAddr?: string }} opts
+ * @param {{ inspector?: boolean; inspectorAddr?: string }} opts
  * @param {string} localPort digits — forwarded app port for default replay base in UI
  * @returns {() => void}
  */
@@ -418,7 +414,7 @@ export function startInspector(opts, localPort) {
     return () => {};
   }
 
-  const themeSeed = themeSeedFromOpts(opts.themes);
+  const themeSeed = defaultInspectorThemeSeed();
   let addr = String(opts.inspectorAddr ?? '').trim();
   if (!addr) addr = defaultInspectorAddr;
 

package/internal/inspector/logstore.js

@@ -10,6 +10,9 @@ let requestLogs = [];
 /** @type {((entry: Record<string, unknown>) => void) | null} */
 let inspectorSubscriber = null;
 
+/** When false (tunnel started with `inspector: false`), captures are not stored. */
+let trafficCaptureEnabled = true;
+
 /**
  * Wire live inspector WebSocket broadcast (optional).
  * @param {((entry: Record<string, unknown>) => void) | null} fn
@@ -18,6 +21,13 @@ export function setInspectorSubscriber(fn) {
   inspectorSubscriber = fn;
 }
 
+/**
+ * @param {boolean} enabled
+ */
+export function setTrafficCaptureEnabled(enabled) {
+  trafficCaptureEnabled = !!enabled;
+}
+
 /**
  * @param {number} n
  */
@@ -33,6 +43,7 @@ export function setMaxRequestLogs(n) {
  * @param {Record<string, unknown>} entry
  */
 export function addLog(entry) {
+  if (!trafficCaptureEnabled) return;
   requestLogs.push(entry);
   if (requestLogs.length > maxRequestLogs) {
     requestLogs = requestLogs.slice(requestLogs.length - maxRequestLogs);

package/internal/tunnel/tunnel.js

@@ -1,7 +1,12 @@
 import { randomUUID } from 'node:crypto';
 import net from 'node:net';
 import { Session } from 'yamux-js/lib/session.js';
-import { addLog, newLogId, setMaxRequestLogs } from '../inspector/logstore.js';
+import {
+  addLog,
+  newLogId,
+  setMaxRequestLogs,
+  setTrafficCaptureEnabled,
+} from '../inspector/logstore.js';
 import { startInspector } from '../inspector/inspector.js';
 // import { version } from '../../../package.json' with { type: 'json' };
 
@@ -167,18 +172,17 @@ async function handleStream(stream, port) {
  * @typedef {Object} TunnelOptions
  * @property {string} [host] tunnel server host (default clickly.cv)
  * @property {number} [serverPort] tunnel server TCP port (default 9000)
- * @property {boolean} [inspector] traffic inspector UI (default true)
- * @property {string} [themes] inspector palette: "dark" | "terminal" | "light"
- * @property {number} [logs] max request logs in memory (default 100)
- * @property {string} [inspectorAddr] inspector listen address (default ":4040")
+ * @property {boolean} [inspector] traffic inspector UI (default false). When false, no inspector server, no in-memory traffic capture, and `logs` / `inspectorAddr` are ignored.
+ * @property {number} [logs] max request/response captures in memory for the inspector (default 100). Only used when `inspector` is true.
+ * @property {string} [inspectorAddr] inspector listen address (default ":4040"). Only used when `inspector` is true.
  */
 
 function defaultTunnelOptions() {
   return {
     host: 'clickly.cv',
     serverPort: 9000,
-    inspector: true,
-    themes: 'dark',
+    themes: 'terminal',
+    inspector: false,
     logs: 100,
     inspectorAddr: '',
   };
@@ -193,13 +197,15 @@ function applyTunnelOptions(options) {
   if (!options || typeof options !== 'object') {
     return /** @type {TunnelOptions & typeof d} */ ({ ...d });
   }
+  const inspector =
+    options.inspector !== undefined ? !!options.inspector : d.inspector;
   return {
     host: options.host ?? d.host,
     serverPort: options.serverPort ?? d.serverPort,
-    inspector: options.inspector !== undefined ? !!options.inspector : d.inspector,
-    themes: options.themes ?? d.themes,
-    logs: options.logs > 0 ? options.logs : d.logs,
-    inspectorAddr: options.inspectorAddr ?? d.inspectorAddr,
+    inspector,
+    logs:
+      inspector && options.logs > 0 ? options.logs : d.logs,
+    inspectorAddr: inspector ? (options.inspectorAddr ?? d.inspectorAddr) : d.inspectorAddr,
   };
 }
 
@@ -306,7 +312,10 @@ class Tunnel {
  */
 async function newTunnel(localPort, options) {
   const opts = applyTunnelOptions(options);
-  setMaxRequestLogs(opts.logs);
+  setTrafficCaptureEnabled(opts.inspector);
+  if (opts.inspector) {
+    setMaxRequestLogs(opts.logs);
+  }
   const t = new Tunnel(localPort, opts);
   await t.connect();
   t._stopInspector = startInspector(opts, localPort);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpkrn/nodetunnel",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Expose a local HTTP server through a devtunnel/gotunnel-compatible server (yamux + JSON). Node.js 18+.",
   "keywords": [
     "tunnel",

package/pkg/tunnel/tunnel.js

@@ -51,10 +51,9 @@ function printSuccess(publicURL, localURL, inspectorURL) {
  *   host?: string,
  *   serverPort?: number,
  *   inspector?: boolean,
- *   themes?: 'dark' | 'terminal' | 'light' | string,
  *   logs?: number,
  *   inspectorAddr?: string,
- * }} [options]
+ * }} [options] Omit or leave defaults for tunnel-only (`inspector` defaults to false).
  * @returns {Promise<{ url: string, stop: () => void }>}
  */
 async function startTunnel(port, options) {