@dpkrn/nodetunnel 1.0.8 → 1.0.10

package/README.md

@@ -1,6 +1,37 @@
 # @dpkrn/nodetunnel
 
-Give your **local** HTTP server a **public URL** from Node.js — useful for webhooks, demos, sharing a dev server, or testing from another device.
+Package **nodetunnel** exposes a local HTTP server on a public URL by establishing a persistent outbound TCP connection to a tunnel server.
+
+It creates an outbound connection to a tunnel server and forwards incoming requests to your local application (e.g., `localhost:8080`).
+
+From **Node.js**, you get a **public URL** for webhooks, demos, sharing a dev server, or testing from another device — without a separate tunnel daemon.
+
+## Introduction
+
+### Benefits
+
+- Sharing your local server with others
+- Testing webhooks (Stripe, GitHub, etc.)
+- Remote debugging without deployment
+- 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
+
+Incoming traffic reaches the public URL, is forwarded through the tunnel, and is proxied to your local HTTP server (e.g., `localhost:8080`).
+
+This enables exposing local development servers without port forwarding, firewall changes, or public hosting.
+
+### Requirements
+
+- **Node.js 18+**
+- A **tunnel server** must be running and reachable (configure `host` / `serverPort` — see **Options** under [API](#api) below).
+- The port passed to `startTunnel` must match your local HTTP server port.
+- Your local server must be running **before** or **concurrently** with `startTunnel`.
+
+## Overview
+
+**nodetunnel** exposes a local HTTP server on a public URL by connecting to a tunnel server you run separately. Traffic hits the tunnel first, then your app on `localhost`.
 
 ---
 
@@ -9,14 +40,7 @@ Give your **local** HTTP server a **public URL** from Node.js — useful for web
 - **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.
-
----
-
-## Requirements
-
-- **Node.js 18+**
-- Your app listening on a port (e.g. `8080`)
-- A **tunnel server** reachable from your machine (default: `localhost:9000`)
+- **Optional traffic inspector** — local dashboard on loopback to browse captures, replay requests, modify and pick a theme (see below).
 
 ---
 
@@ -83,6 +107,72 @@ Run with `node app.js`. Open the printed URL in a browser or share it for webhoo
 
 ---
 
+## Traffic inspector (local dashboard)
+
+When enabled (default), nodetunnel starts a small **HTTP server on your machine** (default `http://localhost:4040`) with:
+
+- **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).
+
+The startup banner prints **Inspector →** with that URL. Set `inspector: false` if you do not want the UI or an extra listen port.
+
+### Themes
+
+The UI supports three built-in palettes via `themes` in `startTunnel` options:
+
+| 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. |
+
+### Example: themes and inspector options
+
+```js
+import http from "node:http";
+import { startTunnel } from "@dpkrn/nodetunnel";
+
+const PORT = 3000;
+
+const server = http.createServer((req, res) => {
+  res.setHeader("Content-Type", "text/plain");
+  res.end("hello\n");
+});
+
+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));
+  });
+});
+```
+
+### Example: tunnel only (no inspector)
+
+```js
+import { startTunnel } from "@dpkrn/nodetunnel";
+
+const { url, stop } = await startTunnel("8080", {
+  inspector: false,
+});
+```
+
+---
+
 ## Express (same idea)
 
 ```js
@@ -117,7 +207,7 @@ app.listen(PORT, async () => {
 | Argument | Description |
 |----------|-------------|
 | `port` | String, e.g. `"8080"` — must match the port your HTTP server uses. |
-| `options` | Optional. `{ host?: string, serverPort?: number }` — where to reach your tunnel server (defaults: `localhost` and `9000`). |
+| `options` | Optional. Object — see **Options** below (tunnel server address, inspector, themes, etc.). |
 
 **Returns:** `{ url, stop }`
 
@@ -128,6 +218,17 @@ app.listen(PORT, async () => {
 
 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. |
+
 ---
 
 ## Troubleshooting

package/cmd/test-lib/main.js

@@ -1,5 +1,5 @@
 import express from "express";
-import { startTunnel } from "@dpkrn/nodetunnel";
+import { startTunnel } from "../../pkg/tunnel/tunnel.js";
 
 
 const app = express();
@@ -27,7 +27,7 @@ app.get("/", async (req, res) => {
 });
 
 app.listen(PORT, async () => {
-  console.log(`listening on http://127.0.0.1:${PORT}`);
+  console.log(`listening on http://localhost:${PORT}`);
   try {
     const { url, stop } = await startTunnel(String(PORT));
     process.once("SIGINT", () => {

package/internal/tunnel/inspector-page.html

@@ -0,0 +1,482 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>Tunnel traffic — dev</title>
+<style>
+/* Theme tokens: dark (default), terminal (green CRT), light */
+body.theme-dark {
+  --bg: #0d1117;
+  --panel: #161b22;
+  --border: #30363d;
+  --text: #e6edf3;
+  --muted: #8b949e;
+  --accent: #58a6ff;
+  --green: #3fb950;
+  --danger: #f85149;
+  --row-alt: #21262d;
+  --log-card: #1c2128;
+  --kv-td: #1c2128;
+  --kv-input-bg: #0d1117;
+  --btn-hover: #262c36;
+  --btn-primary: #238636;
+  --btn-primary-border: #2ea043;
+  --btn-primary-hover: #2ea043;
+  --selected-ring: #388bfd;
+  --err-bg: rgba(248, 81, 73, 0.13);
+  --font-ui: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+body.theme-terminal {
+  --bg: #070807;
+  --panel: #0a0f0a;
+  --border: #1e4a28;
+  --text: #c8f0c8;
+  --muted: #5a8a5a;
+  --accent: #00ff88;
+  --green: #39ff14;
+  --danger: #ff6b6b;
+  --row-alt: #0f1810;
+  --log-card: #0c120d;
+  --kv-td: #080d09;
+  --kv-input-bg: #050805;
+  --btn-hover: #142818;
+  --btn-primary: #1a6b2e;
+  --btn-primary-border: #39ff14;
+  --btn-primary-hover: #228b3a;
+  --selected-ring: #39ff14;
+  --err-bg: rgba(255, 107, 107, 0.12);
+  --font-ui: "JetBrains Mono", "SF Mono", "Cascadia Mono", "Cascadia Code", Consolas, monospace;
+  --font-mono: "JetBrains Mono", "SF Mono", "Cascadia Mono", Menlo, monospace;
+}
+body.theme-light {
+  --bg: #f6f8fa;
+  --panel: #ffffff;
+  --border: #d0d7de;
+  --text: #1f2328;
+  --muted: #656d76;
+  --accent: #0969da;
+  --green: #1a7f37;
+  --danger: #cf222e;
+  --row-alt: #f3f4f6;
+  --log-card: #ffffff;
+  --kv-td: #f6f8fa;
+  --kv-input-bg: #ffffff;
+  --btn-hover: #eaeef2;
+  --btn-primary: #2da44e;
+  --btn-primary-border: #2da44e;
+  --btn-primary-hover: #2c974b;
+  --selected-ring: #0969da;
+  --err-bg: rgba(207, 34, 46, 0.08);
+  --font-ui: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+* { box-sizing: border-box; }
+body {
+  font-family: var(--font-ui);
+  margin: 0; padding: 1rem 1.25rem 2rem;
+  background: var(--bg); color: var(--text); min-height: 100vh;
+}
+body.theme-terminal {
+  text-shadow: 0 0 1px rgba(57, 255, 20, 0.15);
+}
+header { max-width: 1200px; margin: 0 auto 1rem; }
+header h1 { font-size: 1.25rem; font-weight: 600; margin: 0 0 0.35rem 0; }
+header p { margin: 0; color: var(--muted); font-size: 0.875rem; }
+.shell {
+  display: grid; grid-template-columns: minmax(300px, 38%) minmax(0, 1fr);
+  gap: 1rem; align-items: start; max-width: 1200px; margin: 0 auto;
+}
+@media (max-width: 880px) { .shell { grid-template-columns: 1fr; } }
+.col-left {
+  background: var(--panel); border: 1px solid var(--border); border-radius: 10px;
+  padding: 0.65rem 0.75rem; min-height: 200px;
+}
+.col-left .left-topbar {
+  display: flex; flex-wrap: wrap; gap: 0.5rem; justify-content: space-between; align-items: center;
+  margin-bottom: 0.65rem; padding-bottom: 0.5rem; border-bottom: 1px solid var(--border);
+}
+.col-right {
+  background: var(--panel); border: 1px solid var(--border); border-radius: 10px;
+  padding: 0.85rem 1rem 1rem; min-height: 280px;
+}
+.detail-toolbar {
+  display: flex; flex-wrap: wrap; justify-content: space-between; align-items: flex-start;
+  gap: 0.5rem; margin-bottom: 0.75rem;
+}
+.detail-toolbar .toolbar-actions { display: flex; gap: 0.45rem; flex-shrink: 0; }
+#detail-badge { font-size: 12px; color: var(--muted); max-width: 55%; line-height: 1.35; }
+.btn {
+  padding: 0.4rem 0.85rem; font-size: 13px; cursor: pointer; border-radius: 6px;
+  border: 1px solid var(--border); background: var(--row-alt); color: var(--text); font-weight: 500;
+}
+.btn:hover:not(:disabled) { background: var(--btn-hover); }
+.btn-primary { background: var(--btn-primary); border-color: var(--btn-primary-border); color: #fff; }
+.btn-primary:hover:not(:disabled) { background: var(--btn-primary-hover); }
+.btn-sm { padding: 0.25rem 0.55rem; font-size: 12px; }
+#log-list { display: flex; flex-direction: column; gap: 0.5rem; }
+.log-card {
+  background: var(--log-card); border: 1px solid var(--border); border-radius: 8px;
+  overflow: hidden;
+}
+.log-card.selected { box-shadow: 0 0 0 2px var(--accent); border-color: var(--selected-ring); }
+.log-card-head {
+  display: grid;
+  grid-template-columns: auto 1fr auto auto auto;
+  gap: 0.45rem 0.6rem; align-items: center;
+  padding: 0.5rem 0.6rem; font-size: 13px;
+}
+.log-card-head .method { font-weight: 600; color: var(--accent); }
+.log-card-head .path { font-family: var(--font-mono); font-size: 11px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.log-card-head .status { color: var(--green); font-weight: 600; font-size: 12px; }
+.log-card-head .ms { color: var(--muted); font-size: 11px; }
+.btn-toggle {
+  border: 1px solid var(--border); background: var(--row-alt); color: var(--text);
+  border-radius: 6px; padding: 0.25rem 0.5rem; font-size: 11px; cursor: pointer;
+}
+.btn-toggle:hover { border-color: var(--accent); color: var(--accent); }
+.section-title {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.08em;
+  color: var(--muted); margin: 0.85rem 0 0.45rem 0; font-weight: 600;
+}
+.section-title:first-of-type { margin-top: 0; }
+#req-slot { min-height: 1rem; }
+table.kv { width: 100%; border-collapse: collapse; font-size: 12px; margin: 0; }
+table.kv th {
+  text-align: left; vertical-align: top; width: 6.5rem;
+  padding: 0.4rem 0.55rem; border: 1px solid var(--border);
+  background: var(--row-alt); color: var(--muted); font-weight: 600;
+}
+table.kv td {
+  padding: 0.4rem 0.55rem; border: 1px solid var(--border);
+  word-break: break-word; background: var(--kv-td);
+}
+table.kv td pre, table.kv .mono {
+  margin: 0; font-family: var(--font-mono); font-size: 11px;
+  white-space: pre-wrap; max-height: 180px; overflow: auto;
+}
+table.kv-edit input[type="text"], table.kv-edit textarea {
+  width: 100%; margin: 0; padding: 0.35rem 0.45rem; font-size: 12px;
+  font-family: var(--font-mono);
+  border: 1px solid var(--border); border-radius: 4px; background: var(--kv-input-bg); color: var(--text);
+}
+table.kv-edit textarea { resize: vertical; min-height: 3.5rem; display: block; }
+table.kv-edit input:focus, table.kv-edit textarea:focus {
+  outline: none; border-color: var(--accent); box-shadow: 0 0 0 1px var(--accent);
+}
+.err-box {
+  color: var(--danger); font-family: var(--font-mono); font-size: 12px;
+  padding: 0.5rem; border: 1px solid var(--danger); border-radius: 6px; background: var(--err-bg);
+}
+</style>
+</head>
+<body class="__THEME_CLASS__">
+<header>
+  <h1>Tunnel traffic</h1>
+  <p>Left: request list. Right: request/response for the <strong>latest</strong> capture until you click <strong>Show</strong> on a row. Replay updates the Response panel.</p>
+</header>
+<div class="shell">
+  <aside class="col-left">
+    <div class="left-topbar">
+      <button type="button" class="btn btn-sm" id="btn-latest" title="Show most recent in the right panel">Latest</button>
+      <button type="button" class="btn btn-sm" id="clear-all">Clear all</button>
+    </div>
+    <div id="log-list"></div>
+  </aside>
+  <section class="col-right">
+    <div class="detail-toolbar">
+      <span id="detail-badge">No captures yet.</span>
+      <div class="toolbar-actions">
+        <button type="button" class="btn btn-sm btn-primary" id="btn-mod-replay" disabled>Modify</button>
+        <button type="button" class="btn btn-sm" id="btn-reset-req" disabled>Reset</button>
+      </div>
+    </div>
+    <div class="section-title">Request</div>
+    <div id="req-slot"><p style="color:var(--muted);font-size:13px;margin:0">Waiting for traffic…</p></div>
+    <div class="section-title"><span id="resp-label">Response</span></div>
+    <div id="resp-slot"></div>
+  </section>
+</div>
+<script>
+(function () {
+  var proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  var ws = new WebSocket(proto + '//' + location.host + '/ws');
+  var logList = document.getElementById('log-list');
+  var clearAllBtn = document.getElementById('clear-all');
+  var btnLatest = document.getElementById('btn-latest');
+  var detailBadge = document.getElementById('detail-badge');
+  var reqSlot = document.getElementById('req-slot');
+  var respSlot = document.getElementById('resp-slot');
+  var respLabel = document.getElementById('resp-label');
+  var btnModReplay = document.getElementById('btn-mod-replay');
+  var btnResetReq = document.getElementById('btn-reset-req');
+  var originals = {};
+  var latestId = null;
+  var focusedId = null;
+  var editing = false;
+  var respIsReplay = false;
+
+  function effectiveId() {
+    return focusedId || latestId;
+  }
+  function updateCardSelection() {
+    var nodes = logList.querySelectorAll('.log-card');
+    var i;
+    for (i = 0; i < nodes.length; i++) {
+      nodes[i].classList.toggle('selected', focusedId && nodes[i].getAttribute('data-id') === focusedId);
+    }
+  }
+  function updateBadge() {
+    var id = effectiveId();
+    if (!id || !originals[id]) {
+      detailBadge.textContent = 'No captures yet.';
+      return;
+    }
+    var log = originals[id];
+    var verb = focusedId ? 'Selected' : 'Latest';
+    detailBadge.textContent = verb + ' · ' + log.method + ' ' + log.path + ' · ' + String(log.status);
+  }
+
+  function escapeHtml(s) {
+    if (s == null) return '';
+    var d = document.createElement('div');
+    d.textContent = s;
+    return d.innerHTML;
+  }
+  function escapeAttr(s) {
+    return String(s == null ? '' : s).replace(/&/g,'&amp;').replace(/"/g,'&quot;').replace(/</g,'&lt;');
+  }
+  function headerRows(h) {
+    if (!h || typeof h !== 'object') return '';
+    var keys = Object.keys(h).sort();
+    var i, k, parts = [];
+    for (i = 0; i < keys.length; i++) {
+      k = keys[i];
+      parts.push('<tr><th>' + escapeHtml(k) + '</th><td class="mono">' + escapeHtml(Array.isArray(h[k]) ? h[k].join(', ') : String(h[k])) + '</td></tr>');
+    }
+    return parts.join('');
+  }
+  function renderReqView(log) {
+    return '<table class="kv"><tbody>' +
+      '<tr><th>Method</th><td class="mono">' + escapeHtml(log.method) + '</td></tr>' +
+      '<tr><th>Path</th><td class="mono">' + escapeHtml(log.path) + '</td></tr>' +
+      headerRows(log.headers) +
+      '<tr><th>Body</th><td><pre>' + escapeHtml(log.body != null ? String(log.body) : '') + '</pre></td></tr>' +
+      '</tbody></table>';
+  }
+  function renderReqEdit(log) {
+    var h = log.headers || {};
+    return '<table class="kv kv-edit"><tbody>' +
+      '<tr><th>Method</th><td><input type="text" class="f-method" value="' + escapeAttr(log.method) + '"/></td></tr>' +
+      '<tr><th>Path</th><td><input type="text" class="f-path" value="' + escapeAttr(log.path) + '"/></td></tr>' +
+      '<tr><th>Headers</th><td><textarea class="f-headers" rows="5">' + escapeHtml(JSON.stringify(h, null, 2)) + '</textarea></td></tr>' +
+      '<tr><th>Body</th><td><textarea class="f-body" rows="6">' + escapeHtml(log.body != null ? String(log.body) : '') + '</textarea></td></tr>' +
+      '</tbody></table>';
+  }
+  function renderRespTable(log) {
+    return '<table class="kv"><tbody>' +
+      '<tr><th>Status</th><td class="mono">' + escapeHtml(String(log.status)) + '</td></tr>' +
+      headerRows(log.resp_headers) +
+      '<tr><th>Body</th><td><pre>' + escapeHtml(log.resp_body != null ? String(log.resp_body) : '') + '</pre></td></tr>' +
+      '</tbody></table>';
+  }
+  function renderReplayKv(data) {
+    if (data.error) {
+      return '<div class="err-box">' + escapeHtml(String(data.error)) + '</div>';
+    }
+    return '<table class="kv"><tbody>' +
+      '<tr><th>Status</th><td class="mono">' + escapeHtml(String(data.status)) + '</td></tr>' +
+      headerRows(data.headers) +
+      '<tr><th>Body</th><td><pre>' + escapeHtml(data.body != null ? String(data.body) : '') + '</pre></td></tr>' +
+      '</tbody></table>';
+  }
+  function snapshotLog(log) {
+    try {
+      return JSON.parse(JSON.stringify(log));
+    } catch (e) {
+      return log;
+    }
+  }
+  function syncModReplayBtn() {
+    var ed = !!reqSlot.querySelector('.kv-edit');
+    btnModReplay.textContent = ed ? 'Replay' : 'Modify';
+  }
+  function getPayloadFromPanel() {
+    var id = effectiveId();
+    if (!id || !originals[id]) throw new Error('no selection');
+    var edit = reqSlot.querySelector('.kv-edit');
+    if (edit) {
+      var method = reqSlot.querySelector('.f-method').value;
+      var path = reqSlot.querySelector('.f-path').value;
+      var body = reqSlot.querySelector('.f-body').value;
+      var headersRaw = reqSlot.querySelector('.f-headers').value.trim();
+      var headers = {};
+      if (headersRaw) headers = JSON.parse(headersRaw);
+      return { method: method, path: path, headers: headers, body: body };
+    }
+    var o = originals[id];
+    return {
+      method: o.method,
+      path: o.path,
+      headers: o.headers || {},
+      body: o.body != null ? String(o.body) : ''
+    };
+  }
+  function paint() {
+    var id = effectiveId();
+    updateBadge();
+    updateCardSelection();
+    if (!id || !originals[id]) {
+      reqSlot.innerHTML = '<p style="color:var(--muted);font-size:13px;margin:0">Waiting for traffic…</p>';
+      respSlot.innerHTML = '';
+      respLabel.textContent = 'Response';
+      btnModReplay.disabled = true;
+      btnResetReq.disabled = true;
+      return;
+    }
+    btnModReplay.disabled = false;
+    btnResetReq.disabled = false;
+    var log = originals[id];
+    if (!editing) {
+      reqSlot.innerHTML = renderReqView(log);
+    } else {
+      reqSlot.innerHTML = renderReqEdit(log);
+    }
+    if (!respIsReplay) {
+      respSlot.innerHTML = renderRespTable(log);
+      respLabel.textContent = 'Response';
+    }
+    syncModReplayBtn();
+  }
+  function wireCardHead(card, id) {
+    card.querySelector('.btn-toggle').addEventListener('click', function (e) {
+      e.stopPropagation();
+      focusedId = id;
+      editing = false;
+      respIsReplay = false;
+      paint();
+    });
+  }
+  function appendLogCard(log) {
+    var id = log.id || ('tmp-' + Date.now() + '-' + Math.random());
+    log.id = id;
+    originals[id] = snapshotLog(log);
+    latestId = id;
+    var card = document.createElement('article');
+    card.className = 'log-card';
+    card.setAttribute('data-id', id);
+    card.innerHTML =
+      '<div class="log-card-head">' +
+        '<span class="method">' + escapeHtml(log.method) + '</span>' +
+        '<span class="path" title="' + escapeAttr(log.path) + '">' + escapeHtml(log.path) + '</span>' +
+        '<span class="status">' + escapeHtml(String(log.status)) + '</span>' +
+        '<span class="ms">' + escapeHtml(String(log.duration_ms != null ? log.duration_ms : '')) + ' ms</span>' +
+        '<button type="button" class="btn-toggle">Show</button>' +
+      '</div>';
+    wireCardHead(card, id);
+    logList.insertBefore(card, logList.firstChild);
+    if (focusedId === null) {
+      editing = false;
+      respIsReplay = false;
+      paint();
+    }
+    return card;
+  }
+  function clearAll() {
+    logList.innerHTML = '';
+    originals = {};
+    latestId = null;
+    focusedId = null;
+    editing = false;
+    respIsReplay = false;
+    paint();
+  }
+  function loadHistory() {
+    fetch('/logs').then(function (res) { return res.json(); }).then(function (logs) {
+      if (!Array.isArray(logs) || !logs.length) return;
+      var i;
+      for (i = 0; i < logs.length; i++) appendLogCard(logs[i]);
+    }).catch(function () {});
+  }
+
+  btnLatest.onclick = function () {
+    focusedId = null;
+    editing = false;
+    respIsReplay = false;
+    paint();
+  };
+  btnModReplay.onclick = function () {
+    var id = effectiveId();
+    if (!id || !originals[id]) return;
+    if (btnModReplay.textContent === 'Modify') {
+      editing = true;
+      paint();
+      return;
+    }
+    var payload;
+    try {
+      payload = getPayloadFromPanel();
+    } catch (err) {
+      respIsReplay = true;
+      respLabel.textContent = 'Response';
+      respSlot.innerHTML = '<div class="err-box">' + escapeHtml(err.message) + '</div>';
+      return;
+    }
+    if (typeof payload.method !== 'string' || !payload.method.trim()) {
+      respIsReplay = true;
+      respSlot.innerHTML = '<div class="err-box">method required</div>';
+      return;
+    }
+    if (typeof payload.path !== 'string') {
+      respIsReplay = true;
+      respSlot.innerHTML = '<div class="err-box">path required</div>';
+      return;
+    }
+    btnModReplay.disabled = true;
+    respIsReplay = true;
+    respLabel.textContent = 'Response (replay)';
+    respSlot.innerHTML = '<p style="color:var(--muted);margin:0">…</p>';
+    fetch('/replay', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        method: payload.method,
+        path: payload.path,
+        headers: payload.headers || {},
+        body: payload.body != null ? payload.body : ''
+      })
+    }).then(function (res) { return res.json(); })
+      .then(function (data) {
+        respSlot.innerHTML = renderReplayKv(data);
+      })
+      .catch(function (err) {
+        respSlot.innerHTML = '<div class="err-box">' + escapeHtml(String(err)) + '</div>';
+      })
+      .finally(function () {
+        btnModReplay.disabled = false;
+      });
+  };
+  btnResetReq.onclick = function () {
+    var id = effectiveId();
+    if (!id || !originals[id]) return;
+    editing = false;
+    respIsReplay = false;
+    paint();
+  };
+  reqSlot.addEventListener('input', function () {
+    syncModReplayBtn();
+  });
+
+  loadHistory();
+  paint();
+
+  ws.onmessage = function (event) {
+    appendLogCard(JSON.parse(event.data));
+  };
+
+  clearAllBtn.onclick = clearAll;
+})();
+</script>
+</body>
+</html>

package/internal/tunnel/inspector.js

@@ -0,0 +1,266 @@
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { WebSocketServer } from 'ws';
+import { getLogs, setInspectorSubscriber } from './logstore.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INSPECTOR_PAGE_HTML = readFileSync(join(__dirname, 'inspector-page.html'), 'utf8');
+
+const defaultInspectorAddr = ':4040';
+
+/** @param {{ inspectorAddr?: string }} opts */
+export function inspectorHTTPBaseURL(opts) {
+  let addr = String(opts.inspectorAddr ?? '').trim();
+  if (!addr) addr = defaultInspectorAddr;
+  if (addr.startsWith('http://') || addr.startsWith('https://')) return addr;
+  if (addr.startsWith(':')) return `http://127.0.0.1${addr}`;
+  return `http://${addr}`;
+}
+
+/** @param {string | undefined} s */
+function normalizeInspectorTheme(s) {
+  const t = String(s ?? '')
+    .trim()
+    .toLowerCase();
+  if (t === 'terminal') return 'theme-terminal';
+  if (t === 'light') return 'theme-light';
+  if (t === 'dark' || t === '') return 'theme-dark';
+  return 'theme-dark';
+}
+
+const replayHeaderBlocklist = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailers',
+  'transfer-encoding',
+  'upgrade',
+  'host',
+]);
+
+/**
+ * @param {string} localPort
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse) => Promise<void>}
+ */
+function createReplayHandler(localPort) {
+  return async (req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+    if (req.method !== 'POST') {
+      res.writeHead(405);
+      res.end(JSON.stringify({ error: 'use POST' }));
+      return;
+    }
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    const raw = Buffer.concat(chunks);
+    if (raw.length > 10 << 20) {
+      res.writeHead(400);
+      res.end(JSON.stringify({ error: 'body too large' }));
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw.toString('utf8'));
+    } catch (e) {
+      res.writeHead(400);
+      res.end(JSON.stringify({ error: `invalid JSON: ${e instanceof Error ? e.message : String(e)}` }));
+      return;
+    }
+    let method = String(payload.method ?? 'GET')
+      .trim()
+      .toUpperCase();
+    if (!method) method = 'GET';
+    let path = String(payload.path ?? '/').trim();
+    if (!path) path = '/';
+    if (!path.startsWith('/')) path = `/${path}`;
+    const target = `http://127.0.0.1:${localPort}${path}`;
+    const headers = new Headers();
+    const h = payload.headers && typeof payload.headers === 'object' ? payload.headers : {};
+    for (const [k, vals] of Object.entries(h)) {
+      if (replayHeaderBlocklist.has(k.toLowerCase())) continue;
+      const arr = Array.isArray(vals) ? vals : [vals];
+      for (const v of arr) {
+        if (v != null) headers.append(k, String(v));
+      }
+    }
+    /** @type {{ method: string; headers: Headers; body?: string; signal?: AbortSignal }} */
+    const init = { method, headers };
+    const bodyStr = payload.body != null ? String(payload.body) : '';
+    // Forward any non-empty body for arbitrary methods (DELETE, PUT, PATCH, POST, etc.).
+    // The Fetch API rejects a body on GET and HEAD only — match that so replay works for the rest.
+    if (bodyStr.length > 0 && method !== 'GET' && method !== 'HEAD') {
+      init.body = bodyStr;
+    }
+    const ac = new AbortController();
+    const to = setTimeout(() => ac.abort(), 60_000);
+    try {
+      const resp = await fetch(target, { ...init, signal: ac.signal });
+      clearTimeout(to);
+      const b = Buffer.from(await resp.arrayBuffer());
+      const slice = b.length > 10 << 20 ? b.subarray(0, 10 << 20) : b;
+      const bodyOut = slice.toString('utf8');
+      /** @type {Record<string, string[]>} */
+      const headersOut = {};
+      resp.headers.forEach((value, key) => {
+        const canon = key;
+        if (!headersOut[canon]) headersOut[canon] = [];
+        headersOut[canon].push(value);
+      });
+      res.writeHead(200);
+      res.end(
+        JSON.stringify({
+          status: resp.status,
+          headers: headersOut,
+          body: bodyOut,
+        }),
+      );
+    } catch (e) {
+      clearTimeout(to);
+      res.writeHead(502);
+      res.end(JSON.stringify({ error: String(e instanceof Error ? e.message : e) }));
+    }
+  };
+}
+
+/**
+ * @param {string} addr
+ * @returns {{ host?: string; port: number }}
+ */
+function parseListenAddr(addr) {
+  const s = String(addr).trim();
+  if (!s) return { port: 4040 };
+  if (s.startsWith('http://') || s.startsWith('https://')) {
+    const u = new URL(s);
+    const port = Number(u.port);
+    return {
+      host: u.hostname || 'localhost',
+      port: Number.isFinite(port) && port > 0 ? port : u.protocol === 'https:' ? 443 : 80,
+    };
+  }
+  if (s.startsWith(':')) {
+    const port = Number(s.slice(1));
+    return { port: Number.isFinite(port) ? port : 4040 };
+  }
+  const lastColon = s.lastIndexOf(':');
+  if (lastColon > 0) {
+    const host = s.slice(0, lastColon);
+    const port = Number(s.slice(lastColon + 1));
+    if (Number.isFinite(port)) return { host, port };
+  }
+  if (/^\d+$/.test(s)) return { port: Number(s) };
+  return { port: 4040 };
+}
+
+/**
+ * @param {{ inspector?: boolean; themes?: string; inspectorAddr?: string }} opts
+ * @param {string} localPort
+ * @returns {() => void}
+ */
+export function startInspector(opts, localPort) {
+  if (opts.inspector === false) {
+    return () => {};
+  }
+
+  const themeClass = normalizeInspectorTheme(opts.themes);
+  let addr = String(opts.inspectorAddr ?? '').trim();
+  if (!addr) addr = defaultInspectorAddr;
+
+  /** @type {Set<import('ws').WebSocket>} */
+  const clients = new Set();
+
+  function broadcast(entry) {
+    const msg = JSON.stringify(entry);
+    for (const ws of clients) {
+      try {
+        ws.send(msg);
+      } catch {
+        clients.delete(ws);
+      }
+    }
+  }
+
+  setInspectorSubscriber(broadcast);
+
+  const replay = createReplayHandler(localPort);
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const pathname = url.pathname;
+    if (req.method === 'GET' && pathname === '/') {
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      const page = INSPECTOR_PAGE_HTML.replace('__THEME_CLASS__', themeClass);
+      res.end(page);
+      return;
+    }
+    if (req.method === 'GET' && pathname === '/logs') {
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify(getLogs(), null, 2));
+      return;
+    }
+    if (req.method === 'POST' && pathname === '/replay') {
+      replay(req, res).catch(() => {
+        try {
+          if (!res.headersSent) res.writeHead(500);
+          res.end(JSON.stringify({ error: 'replay failed' }));
+        } catch {
+          /* ignore */
+        }
+      });
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
+
+  server.maxHeadersCount = 2000;
+
+  const wss = new WebSocketServer({ noServer: true });
+  wss.on('connection', (ws) => {
+    clients.add(ws);
+    ws.on('close', () => clients.delete(ws));
+    ws.on('error', () => clients.delete(ws));
+    ws.on('message', () => {});
+  });
+
+  server.on('upgrade', (request, socket, head) => {
+    const path = new URL(request.url || '/', 'http://127.0.0.1').pathname;
+    if (path === '/ws') {
+      wss.handleUpgrade(request, socket, head, (ws) => {
+        wss.emit('connection', ws, request);
+      });
+    } else {
+      socket.destroy();
+    }
+  });
+
+  const listenOpts = parseListenAddr(addr);
+  server.listen(listenOpts, () => {
+    console.error(`nodetunnel: traffic inspector → ${inspectorHTTPBaseURL(opts)}`);
+  });
+
+  server.on('error', (err) => {
+    console.error(`nodetunnel: inspector stopped: ${err.message}`);
+  });
+
+  return () => {
+    setInspectorSubscriber(null);
+    for (const ws of clients) {
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+    }
+    clients.clear();
+    try {
+      wss.close();
+    } catch {
+      /* ignore */
+    }
+    server.close();
+  };
+}

package/internal/tunnel/logstore.js

@@ -0,0 +1,65 @@
+import { randomUUID } from 'node:crypto';
+
+const defaultMaxRequestLogs = 100;
+
+/** @type {number} */
+let maxRequestLogs = defaultMaxRequestLogs;
+/** @type {Array<Record<string, unknown>>} */
+let requestLogs = [];
+
+/** @type {((entry: Record<string, unknown>) => void) | null} */
+let inspectorSubscriber = null;
+
+/**
+ * Wire live inspector WebSocket broadcast (optional).
+ * @param {((entry: Record<string, unknown>) => void) | null} fn
+ */
+export function setInspectorSubscriber(fn) {
+  inspectorSubscriber = fn;
+}
+
+/**
+ * @param {number} n
+ */
+export function setMaxRequestLogs(n) {
+  if (n < 1) n = defaultMaxRequestLogs;
+  maxRequestLogs = n;
+  if (requestLogs.length > maxRequestLogs) {
+    requestLogs = requestLogs.slice(requestLogs.length - maxRequestLogs);
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} entry
+ */
+export function addLog(entry) {
+  requestLogs.push(entry);
+  if (requestLogs.length > maxRequestLogs) {
+    requestLogs = requestLogs.slice(requestLogs.length - maxRequestLogs);
+  }
+  const sub = inspectorSubscriber;
+  if (sub) {
+    setImmediate(() => {
+      try {
+        sub(entry);
+      } catch {
+        /* ignore */
+      }
+    });
+  }
+}
+
+/**
+ * Newest entries are last (matches gotunnel GetLogs).
+ * @returns {Record<string, unknown>[]}
+ */
+export function getLogs() {
+  return requestLogs.slice();
+}
+
+/**
+ * @returns {string}
+ */
+export function newLogId() {
+  return randomUUID();
+}

package/internal/tunnel/tunnel.js

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import net from 'node:net';
 import { Session } from 'yamux-js/lib/session.js';
+import { addLog, newLogId, setMaxRequestLogs } from './logstore.js';
+import { startInspector } from './inspector.js';
 // import { version } from '../../../package.json' with { type: 'json' };
 
 const defaultMuxConfig = {
@@ -98,6 +100,7 @@ function headersToObject(h) {
  * @param {string} port
  */
 async function handleStream(stream, port) {
+  const started = Date.now();
   try {
     const line = await readJsonLine(stream);
     let req;
@@ -135,6 +138,19 @@ async function handleStream(stream, port) {
     };
 
     stream.end(Buffer.from(`${JSON.stringify(payload)}\n`, 'utf8'));
+
+    addLog({
+      id: newLogId(),
+      method,
+      path,
+      headers: raw,
+      body: body.toString('utf8'),
+      status: resp.status,
+      resp_body: respBody.toString('utf8'),
+      resp_headers: headersToObject(resp.headers),
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - started,
+    });
   } catch (e) {
     try {
       stream.destroy();
@@ -146,17 +162,52 @@ async function handleStream(stream, port) {
 
 /**
  * @typedef {Object} TunnelOptions
- * @property {string} [host] tunnel server host (default localhost)
+ * @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")
+ */
+
+function defaultTunnelOptions() {
+  return {
+    host: 'clickly.cv',
+    serverPort: 9000,
+    inspector: true,
+    themes: 'dark',
+    logs: 100,
+    inspectorAddr: '',
+  };
+}
+
+/**
+ * @param {TunnelOptions | undefined} options
+ * @returns {TunnelOptions & ReturnType<typeof defaultTunnelOptions>}
  */
+function applyTunnelOptions(options) {
+  const d = defaultTunnelOptions();
+  if (!options || typeof options !== 'object') {
+    return /** @type {TunnelOptions & typeof d} */ ({ ...d });
+  }
+  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,
+  };
+}
 
 class Tunnel {
   /**
    * @param {string} localPort local HTTP port to forward to
-   * @param {TunnelOptions} [options]
+   * @param {TunnelOptions} [options] merged options
    */
   constructor(localPort, options = {}) {
     this.localPort = localPort;
+    this.options = options;
     this.serverHost = options.host ?? 'clickly.cv';
     this.serverPort = options.serverPort ?? 9000;
     /** @type {import('net').Socket | null} */
@@ -165,6 +216,8 @@ class Tunnel {
     this.session = null;
     this.publicUrl = '';
     this._stopped = false;
+    /** @type {(() => void) | null} */
+    this._stopInspector = null;
   }
 
   /**
@@ -217,6 +270,14 @@ class Tunnel {
   stop() {
     if (this._stopped) return;
     this._stopped = true;
+    try {
+      if (this._stopInspector) {
+        this._stopInspector();
+        this._stopInspector = null;
+      }
+    } catch {
+      /* ignore */
+    }
     try {
       if (this.session) {
         this.session.close();
@@ -241,8 +302,11 @@ class Tunnel {
  * @param {TunnelOptions} [options]
  */
 async function newTunnel(localPort, options) {
-  const t = new Tunnel(localPort, options);
+  const opts = applyTunnelOptions(options);
+  setMaxRequestLogs(opts.logs);
+  const t = new Tunnel(localPort, opts);
   await t.connect();
+  t._stopInspector = startInspector(opts, localPort);
   return t;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpkrn/nodetunnel",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Expose a local HTTP server through a devtunnel/gotunnel-compatible server (yamux + JSON). Node.js 18+.",
   "keywords": [
     "tunnel",
@@ -49,7 +49,7 @@
     "prepublishOnly": "node -e \"import('./pkg/tunnel/tunnel.js').then(() => console.log('pack ok')).catch(e => { console.error(e); process.exit(1); })\""
   },
   "dependencies": {
-    "@dpkrn/nodetunnel": "^1.0.2",
+    "ws": "^8.18.0",
     "yamux-js": "^0.2.0"
   },
   "devDependencies": {

package/pkg/tunnel/tunnel.js

@@ -18,19 +18,24 @@
  */
 
 import { newTunnel } from '../../internal/tunnel/tunnel.js';
+import { inspectorHTTPBaseURL } from '../../internal/tunnel/inspector.js';
 
 /**
  * Print a formatted success message for the tunnel.
  * @param {string} publicURL
  * @param {string} localURL
+ * @param {string} [inspectorURL] when empty, inspector line is omitted
  */
-function printSuccess(publicURL, localURL) {
+function printSuccess(publicURL, localURL, inspectorURL) {
   console.log();
   console.log('  ╔══════════════════════════════════════════════════╗');
   console.log('  ║  🚇  nodetunnel — tunnel is live                 ║');
   console.log('  ╠══════════════════════════════════════════════════╣');
   console.log(`  ║  🌍  Public   →  ${publicURL.padEnd(32)}║`);
   console.log(`  ║  💻  Local    →  ${localURL.padEnd(32)}║`);
+  if (inspectorURL) {
+    console.log(`  ║  🔍  Inspector → ${inspectorURL.padEnd(32)}║`);
+  }
   console.log(`  ╠══════════════════════════════════════════════════╣`);
   console.log('  ║  ⚡  Forwarding requests...                      ║');
   console.log('  ║  🛑  Press Ctrl+C to stop                        ║');
@@ -42,7 +47,14 @@ function printSuccess(publicURL, localURL) {
  * 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)
+ * @param {{
+ *   host?: string,
+ *   serverPort?: number,
+ *   inspector?: boolean,
+ *   themes?: 'dark' | 'terminal' | 'light' | string,
+ *   logs?: number,
+ *   inspectorAddr?: string,
+ * }} [options]
  * @returns {Promise<{ url: string, stop: () => void }>}
  */
 async function startTunnel(port, options) {
@@ -50,7 +62,9 @@ async function startTunnel(port, options) {
 
   const publicURL = tunnel.getPublicUrl();
   const localURL = `http://localhost:${port}`;
-  printSuccess(publicURL, localURL);
+  const insp =
+    tunnel.options.inspector === false ? '' : inspectorHTTPBaseURL(tunnel.options);
+  printSuccess(publicURL, localURL, insp);
 
   return {
     url: publicURL,