@dpkrn/nodetunnel 1.0.9 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing unreleased yet.
+
+## [1.0.10] - 2026-04-12
+
+### Changed
+
+- Expanded README with clearer coverage of what nodetunnel does and how to use it.
+
+## [1.0.9] - 2026-04-12
+
+### Added
+
+- Makefile with `pkg` (publish) and `test` targets for maintainers.
+- Contributor Covenant Code of Conduct.
+- Local traffic inspector: HTTP UI plus WebSocket streaming of request/response logs (via `ws`).
+- Structured logging store for tunneled HTTP exchanges.
+
+### Changed
+
+- Refactor of the published tunnel package layout and dependencies.
+- Clearer logging during tunnel setup and while forwarding requests.
+
+## [1.0.8] - 2026-04-12
+
+### Changed
+
+- Maintenance release (version alignment).
+
+## [1.0.7] - 2026-04-12
+
+### Changed
+
+- Default tunnel server host set to `clickly.cv`.
+- Public URL string returned by the tunnel client updated for consistency with the server.
+- Tunnel handshake and messaging updated (connection UUID and success-line formatting for the assigned URL).
+
+## [1.0.4] - 2026-04-03
+
+### Added
+
+- Node.js tunnel library: expose a local HTTP server through a gotunnel/yamux-compatible remote (`startTunnel` and related APIs).
+
+## [1.0.2] - 2026-04-03
+
+### Added
+
+- Initial `@dpkrn/nodetunnel` package scaffold.
+
+[Unreleased]: https://github.com/DpkRn/nodetunnel/compare/v1.0.10...HEAD
+[1.0.10]: https://github.com/DpkRn/nodetunnel/compare/v1.0.9...v1.0.10
+[1.0.9]: https://github.com/DpkRn/nodetunnel/compare/v1.0.8...v1.0.9
+[1.0.8]: https://github.com/DpkRn/nodetunnel/compare/v1.0.7...v1.0.8
+[1.0.7]: https://github.com/DpkRn/nodetunnel/compare/v1.0.4...v1.0.7
+[1.0.4]: https://github.com/DpkRn/nodetunnel/compare/v1.0.2...v1.0.4
+[1.0.2]: https://github.com/DpkRn/nodetunnel/releases/tag/v1.0.2

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`.
 
 ---
 
@@ -13,14 +44,6 @@ Give your **local** HTTP server a **public URL** from Node.js — useful for web
 
 ---
 
-## Requirements
-
-- **Node.js 18+**
-- Your app listening on a port (e.g. `8080`)
-- A **tunnel server** reachable from your machine (default: `localhost:9000`)
-
----
-
 ## Install
 
 ```bash
@@ -129,7 +152,7 @@ server.listen(PORT, async () => {
   });
 
   // console.log("Public:", url);
-  // Open the Inspector URL from stderr in a browser (e.g. http://127.0.0.1:4040)
+  // Open the Inspector URL from stderr in a browser (e.g. http://localhost:4040)
 
   process.once("SIGINT", () => {
     stop();
@@ -204,7 +227,7 @@ Errors **reject** the promise — use `try/catch`.
 | `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'`, `'127.0.0.1:9090'`). Display URL follows the same rules as the public banner. |
+| `inspectorAddr` | `string` | `':4040'` | Listen address for the inspector (e.g. `':4040'`, `'localhost:9090'`). Display URL follows the same rules as the public banner. |
 
 ---
 

package/cmd/test-lib/main.js

@@ -4,6 +4,7 @@ import { startTunnel } from "../../pkg/tunnel/tunnel.js";
 
 const app = express();
 app.set("etag", false);
+app.use(express.json());
 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);
@@ -26,6 +27,20 @@ app.get("/", async (req, res) => {
   res.send("Backend is running");
 });
 
+/**
+ * POST echo: path params (`:category`, `:itemId`), query string, and JSON body.
+ * Example: POST /test/widgets/42?verbose=1&tag=a with body `{"name":"x"}`
+ */
+app.post("/test/:category/:itemId", (req, res) => {
+  console.log("server received request");
+  console.log("req.body",req.body);
+  res.status(200).json({
+    pathParams: req.params,
+    query: req.query,
+    body: req.body,
+  });
+});
+
 app.listen(PORT, async () => {
   console.log(`listening on http://localhost:${PORT}`);
   try {