@yousolution/node-red-contrib-you-tunnel-websocket 1.1.1 → 1.2.0

package/AGENTS.md

@@ -0,0 +1,45 @@
+# AI Development Rules
+
+Before modifying production code:
+
+1. Read `STABILITY_CONTRACT.md`.
+2. Identify the RWT-\* invariants affected by the change.
+3. Inspect the relevant implementation and existing tests.
+4. Do not weaken or remove tests to make them pass.
+5. Every bug fix must include a regression test when technically possible.
+6. Do not increase timeouts to hide races.
+7. Do not add retries without identifying the root cause.
+8. Run all pertinent tests after every modification.
+9. Do not use `--forceExit` to hide resource leaks.
+10. Keep changes minimal and scoped to the current task.
+11. Do not refactor unrelated code.
+
+## Stability Contract
+
+`STABILITY_CONTRACT.md` is normative.
+
+Do not weaken, remove, or modify an RWT-\* invariant merely to make an implementation or test pass.
+
+If the intended system behavior changes:
+
+1. Update `STABILITY_CONTRACT.md`.
+2. Explain why the invariant changed.
+3. Add or update the relevant regression test.
+4. Verify that dependent invariants remain satisfied.
+
+Known Issues, Stability Risks, and Open Questions in the Stability Contract are not invariants and must not be treated as requirements without additional evidence.
+
+## Workflow
+
+For each task:
+
+1. Read `STABILITY_CONTRACT.md`.
+2. Inspect the relevant implementation.
+3. Inspect existing tests.
+4. Identify affected invariants, known issues, and stability risks.
+5. Write or reproduce the regression test.
+6. Make the smallest production change necessary.
+7. Run the focused test.
+8. Run the relevant existing suites.
+9. Verify affected RWT-\* invariants.
+10. Report changed files, tests executed, invariant impact, and remaining risks.

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.2.0] - 2026-09-10
+
+### Added
+- New `wstunnel command` node for sending commands to connected tunnel clients (fire-and-forget)
+- `wstunnel server` node output: emits `connect` and `disconnect` events when tunnels register or close
+- `wstunnel server` node input: accepts any message to trigger a server metrics snapshot via `getMetrics().snapshot()`
+- Metrics snapshot includes: `active_tunnels`, `active_streams`, `bytes_in_total`, `bytes_out_total`, `event_loop_lag_ms`, per-tunnel `tunnels_detail`
+- `STABILITY_CONTRACT.md` — 4 RWT invariants (RWT-001 through RWT-004) with regression tests
+- `AGENTS.md` — AI development rules and workflow
+- Regression tests for all KI fixes, output events, metrics input, concurrent deployment, and command node
+
+### Fixed
+- KI-001: Inverted host/path default logic — configured values were discarded
+- KI-002: tunnelIdHeaderName HTML default mismatch — editor default did not match runtime
+- KI-003: Leftover debug log statement at info level — changed to debug level
+- KI-004: console.error used in production code — replaced with logger.error
+- KI-005: License inconsistency — package.json declared MIT while source files declared Apache-2.0
+- `data/flows.json`: Fixed `host` and `tunnelIdHeaderName` for Docker compatibility
+
+### Changed
+- `wstunnel server` node now accepts input (1 input, was 0)
+- Replaced `setTimeout` with deterministic `setImmediate`/`Promise.resolve` in all test files
+- Updated `@remotelinker/reverse-ws-tunnel` dependency
+
+---
+
+## [1.1.2] - 2026-05-04
+
+### Fixed
+- Add proper cleanup of existing server on port before starting
+- Replace console.log/warn/error with proper logger
+- Improve error handling during server start/stop
+
+### Changed
+- Update @remotelinker/reverse-ws-tunnel from ^1.0.10 to ^1.0.11
+- Add log context for each tunnel node
+
+---
+
+## [1.1.1] - 2025-??-??
+
+### Changed
+- Update @remotelinker/reverse-ws-tunnel from ^1.0.9 to ^1.0.10
+
+---
+
+## [1.1.0] - 2025-??-??
+
+### Fixed
+- Fix server configuration issues
+
+### Changed
+- Disable wstunnel client node temporarily
+- Switch from local/beta package to published reverse-ws-tunnel package
+
+### Documentation
+- Update README to match current codebase
+
+---
+
+## [1.0.1-dev-3] - 2025-??-??
+
+### Added
+- Initial wstunnel client node for reverse WebSocket tunneling
+
+### Changed
+- Update version to 1.0.1-dev-3
+- Update dependencies
+- Improve documentation
+- Disable wstunnel client node
+
+---
+
+## [1.0.1] - 2025-??-??
+
+### Added
+- Add configurable log level dropdown in wstunnel configuration (trace, debug, info, warning, error)
+
+### Fixed
+- Remove old connections when redeploying flows
+
+### Changed
+- First release with reverse tunnel functionality
+
+---
+
+## [1.0.0] - 2025-??-??
+
+### Added
+- Initial release with WebSocket tunnel support
+- MSSQL integration
+
+---
+
+[1.2.0]: https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket/compare/v1.1.2...v1.2.0
+[1.1.2]: https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket/tree/v1.0.0

package/README.md

@@ -39,11 +39,22 @@ Creates a WebSocket server that can tunnel HTTP traffic over WebSocket connectio
 
 #### Inputs
 
-*none*
+| Property | Type | Description |
+|---|---|---|
+| `*` | `any` | Send any message to request a metrics snapshot on the output |
 
 #### Outputs
 
-*none*
+Emits messages when tunnels connect, disconnect, or when metrics are requested:
+
+| Property | Type | Description |
+|---|---|---|
+| `event` | `string` | `"connect"` when a tunnel is registered, `"disconnect"` when it closes, `"metrics"` when a snapshot is returned |
+| `tunnelId` | `string` | The unique tunnel identifier (UUID) — present on connect/disconnect events |
+| `remoteAddress` | `string` | The client IP address — present on connect/disconnect events |
+| `connectedAt` | `number` | `Date.now()` when the tunnel was registered — present on connect events |
+| `serverPort` | `number` | The port the WebSocket server is listening on |
+| `payload` | `object` | On metrics events: the full snapshot object with aggregate and per-tunnel metrics |
 
 #### Details
 
@@ -54,6 +65,37 @@ Status indicators:
 - 🟢 **listening on port [port]**: Server is active and listening
 - 🟢 **clients [count]**: Number of connected WebSocket clients
 
+### wstunnel command
+
+Sends commands to connected tunnel clients via WebSocket.
+
+#### Properties
+
+- **Name**: Optional name for the node
+- **wstunnel**: Reference to a wstunnel configuration node *(required)*
+
+#### Inputs
+
+| Property | Type | Description |
+|---|---|---|
+| `payload` | `object` | Command payload (may contain `tunnelId`, `command`, `args`) |
+| `tunnelId` | `string` | Target tunnel UUID (alternative to `payload.tunnelId`) |
+| `command` | `string` | Command name to send, e.g. `"kill"` (alternative to `payload.command`) |
+| `args` | `object` | Optional arguments for the command (alternative to `payload.args`) |
+
+#### Outputs
+
+Two outputs:
+
+- **Output 0 (success)**: Command delivered. `msg.payload` is `true`.
+- **Output 1 (failure)**: Tunnel not found or not connected. `msg.payload` is `false`, `msg.error` contains the reason.
+
+#### Details
+
+The node sends a command to a connected tunnel client. The target tunnel is identified by its `tunnelId`. If the tunnel exists and its WebSocket is open, the command is delivered and output 0 fires. If the tunnel does not exist or is disconnected, output 1 fires with an error message.
+
+Missing `tunnelId` or `command` sends the message to output 1 with an error.
+
 ## Usage
 
 ### Basic Setup
@@ -67,6 +109,44 @@ Status indicators:
 
 3. The server will start listening for WebSocket connections
 
+### Monitoring Connections
+
+Connect the **wstunnel server** output to a `switch` node to route connect and disconnect events:
+
+```
+[wstunnel server] → [switch: event == "connect"]  → [notification flow]
+                   → [switch: event == "disconnect"] → [cleanup flow]
+```
+
+### Monitoring Metrics
+
+Wire an `inject` node to the **wstunnel server** input to periodically request metrics:
+
+```
+[inject: every 5s] → [wstunnel server] → [debug: metrics]
+```
+
+The output `msg.payload` contains:
+
+| Field | Description |
+|---|---|
+| `active_tunnels` | Number of currently active tunnels |
+| `active_streams` | Number of active TCP streams |
+| `bytes_in_total / bytes_out_total` | Aggregate byte counters |
+| `event_loop_lag_ms` | `{ p50, p99 }` event loop lag |
+| `tunnels_detail` | Per-tunnel: `remoteAddress`, `streamCount`, `bytesIn`, `bytesOut`, `agentVersion` |
+
+### Sending Commands to Clients
+
+Wire a trigger to a **wstunnel command** node to send commands to connected clients:
+
+```
+[inject: {tunnelId: "uuid", command: "kill"}]
+  → [wstunnel command]
+    → output 0 → [debug: success]
+    → output 1 → [debug: failure]
+```
+
 ### Connection URLs
 
 WebSocket servers are accessible at:
@@ -92,5 +172,4 @@ Apache-2.0
 
 Andrea Trentin (<andrea.trentin@yousolution.cloud>)
 
-Repository: [yousolution-cloud/node-red-contrib-you-tunnel-websocket](https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket)</content>
-<parameter name="filePath">README.md
+Repository: [yousolution-cloud/node-red-contrib-you-tunnel-websocket](https://github.com/yousolution-cloud/node-red-contrib-you-tunnel-websocket)

package/STABILITY_CONTRACT.md

@@ -0,0 +1,299 @@
+# Stability Contract
+
+This document is normative. It defines the project's **RWT-\*** invariants — properties that must be preserved across all production changes.
+
+## What Is an Invariant?
+
+An RWT-\* invariant is a property of the system that must remain true across production changes.
+
+An invariant describes required behavior or compatibility, not a particular implementation.
+
+Implementation details may change as long as the invariant remains satisfied.
+
+Known bugs, temporary workarounds, coding conventions, and developer workflow rules are not invariants unless explicitly justified as stability requirements.
+
+## How to Use This Contract
+
+Before modifying production code:
+
+1. Identify which RWT-\* invariants may be affected by the change.
+2. Verify the tests that protect those invariants (if they exist).
+3. Evaluate whether the change preserves all affected invariants.
+4. Add or update regression tests when necessary.
+5. If an invariant must intentionally change, update this file first.
+
+This contract does not replace AGENTS.md. It supplements it with stability-specific constraints.
+
+## Contract Scope
+
+This document defines stability properties only. It must not be used to justify unrelated refactoring, cleanup, or behavior changes.
+
+The contract describes what must remain true, not how the implementation must achieve it.
+
+## Evidence and Authority
+
+The Stability Contract is normative, but each invariant should be supported by repository evidence.
+
+Evidence may include:
+
+- Production code
+- Automated tests
+- Integration tests
+- Project documentation
+- CHANGELOG entries
+- Commit history
+- External framework contracts relied upon by the project
+
+When evidence is insufficient to establish a required behavior, document the behavior as a Known Issue or Open Question rather than promoting it to an invariant.
+
+---
+
+## Invariants
+
+### RWT-001 — Exclusive Server Ownership of a Port
+
+**Status:** Active
+
+**Invariant**
+
+A replacement managed WebSocket server must not be started on a port until the previously managed server on that port has completed its shutdown. At no point during a replacement operation may the implementation intentionally start the replacement while the previous server is still active.
+
+**Why it matters**
+
+If two servers attempt to bind the same port simultaneously, the second will fail with a port-in-use error, or both may enter an undefined state. This prevents orphaned server processes from accumulating across Node-RED redeployments.
+
+**Scope**
+
+- `nodes/wsTunnel.js` — `WSTunnelServer` constructor
+
+**Protected by**
+
+Automated tests:
+
+- `test/rwt-001-port-exclusivity.test.js` — 2 tests (mock-based ordering verification)
+- `test/rwt-001-port-release.test.js` — 2 tests (deterministic port-binding verification)
+
+Historical evidence:
+
+- CHANGELOG v1.0.1: "Remove old connections when redeploying flows"
+- CHANGELOG v1.1.2: "Add proper cleanup of existing server on port before starting"
+- Commit `0f2b273`: "fix: remove old connection when deploy"
+
+**Potential violations**
+
+- Starting a new server before the previous stop completes.
+- Removing the cleanup-before-start sequence.
+- Parallel deployments of multiple `wstunnel server` nodes on the same port without serializing the cleanup.
+
+**Verification**
+
+Deploy two `wstunnel server` nodes on the same port sequentially. Verify via Node-RED logs that the cleanup message appears before the start message for each deployment.
+
+---
+
+### RWT-002 — Node Shutdown Must Signal Completion
+
+**Status:** Active
+
+**Invariant**
+
+When a `WSTunnelServer` node receives a Node-RED close event, its shutdown handler must always signal completion by invoking `done()`, including failure paths.
+
+**Why it matters**
+
+Node-RED uses the `done()` callback to determine that a node has finished its shutdown sequence. If `done()` is not called, Node-RED will hang indefinitely, preventing redeployment or shutdown of the flow.
+
+**Scope**
+
+- `nodes/wsTunnel.js` — `WSTunnelServer.on('close')` handler
+
+**Protected by**
+
+Automated tests:
+
+- `test/rwt-002-shutdown-completion.test.js` — 4 tests
+
+Historical evidence:
+
+- Node-RED framework contract: `done()` must be called in `on('close')`.
+- The `done()` call exists in both success and error branches of the current implementation.
+
+**Potential violations**
+
+- Adding a new code path in `on('close')` that does not call `done()`.
+- Throwing an exception before `done()` is reached without a catch.
+- Removing the `done()` call in the error branch.
+
+**Verification**
+
+Deploy a `wstunnel server` node, then remove or redeploy it. Verify that Node-RED does not hang on the deployment.
+
+---
+
+### RWT-003 — Node Runtime/Editor Compatibility
+
+**Status:** Active
+
+**Invariant**
+
+Every Node-RED node type exposed by the package must have a corresponding editor definition, and the runtime and editor definitions must refer to the same node type. A node type must remain loadable and configurable through the Node-RED editor after production changes.
+
+**Why it matters**
+
+Node-RED uses the type name as the binding key between the editor UI (HTML) and the runtime (JS). A mismatch causes the node to be invisible in the editor, to fail to load, or to exhibit undefined behavior.
+
+**Scope**
+
+- `nodes/wsTunnel.js` — `RED.nodes.registerType()` calls
+- `nodes/wsTunnel.html` — `data-template-name` and `data-help-name` attributes
+
+**Protected by**
+
+Automated tests:
+
+- `test/rwt-003-runtime-editor-compatibility.test.js` — 5 tests
+
+Historical evidence:
+
+- Node-RED framework contract: type names must be consistent across JS and HTML.
+- The current code has exact matches for the three active node types: `wstunnel`, `wstunnel server`, and `wstunnel command`.
+
+**Potential violations**
+
+- Renaming a type in JS without updating the HTML template and help attributes.
+- Adding a new `RED.nodes.registerType()` call without corresponding HTML.
+- Changing the type name of an existing node.
+
+**Verification**
+
+After modifying type registrations, load the Node-RED editor and verify that both node types appear in the palette. Verify that each can be dragged onto the canvas and configured.
+
+---
+
+### RWT-004 — Persisted Flow Configuration Compatibility
+
+**Status:** Active
+
+**Invariant**
+
+Existing Node-RED flows using the currently supported `wstunnel` configuration properties must remain loadable after a package upgrade, and their persisted configuration values must retain their existing behavior. Removing or renaming a persisted configuration property requires an explicit migration strategy.
+
+**Why it matters**
+
+Node-RED stores node configuration in flow JSON files. If configuration properties are removed or renamed, existing flows will lose their configured values, causing silent failures or fallback to unexpected defaults. This breaks deployments that upgrade the module.
+
+**Scope**
+
+- `nodes/wsTunnel.js` — `WSTunnelNode` constructor (options object)
+- `nodes/wsTunnel.html` — `wstunnel` registration defaults
+
+**Protected by**
+
+Automated tests:
+
+- `test/rwt-004-persisted-config-compatibility.test.js` — 5 tests
+
+Historical evidence:
+
+- Node-RED framework contract: config node properties are persisted in flow JSON.
+- `data/flows.json` stores `name`, `host`, `port`, `path`, `tunnelIdHeaderName`, and `logLevel` as persisted properties.
+
+**Potential violations**
+
+- Removing a property from the `options` object without deprecation.
+- Renaming a property without providing a migration path.
+- Changing the type or semantics of an existing property.
+
+**Verification**
+
+Create a flow JSON file with all current configuration properties set, then deploy the updated module. Verify that all values are preserved and functional in the editor.
+
+---
+
+## Known Stability Risks
+
+These are potentially dangerous implementation characteristics that should be considered before modifying affected areas. Known Stability Risks are advisory. They must not be treated as requirements and must not be converted into invariants without additional evidence.
+
+### Risk: Global Mutable State in `instances` Object
+
+- **Area:** `nodes/wsTunnel.js` line 19
+- **Nature:** The `instances` object is module-level mutable state shared across all node instances. If two `wstunnel server` nodes deploy concurrently on the same port, the stop/start sequence may interleave, causing one node to overwrite the other's state.
+- **Existing test:** None.
+- **What to verify:** Before modifying server lifecycle logic, consider whether concurrency needs to be addressed with per-port locking or serialization.
+
+### Risk: Global Logger Context Override
+
+- **Area:** `nodes/wsTunnel.js` lines 47–48
+- **Nature:** `setLogContext` and `setLogLevel` affect the global logger. If multiple `wstunnel server` nodes are deployed, the last deployed node's context and level win for all nodes.
+- **Existing test:** None.
+- **What to verify:** Before modifying logger configuration, consider whether per-node logger instances are needed.
+
+---
+
+## Known Issues
+
+Known defects or suspicious behavior discovered during contract analysis. Known Issues are non-normative and are documented for visibility only.
+
+### KI-001 — Inverted host/path Default Logic *(Resolved)*
+
+- **Area:** `nodes/wsTunnel.js` lines 52–53
+- **Nature:** The ternary expressions `node.tunnelConfig.options.host ? '' : undefined` were inverted. When `host` had a value (truthy), it was set to `''` (empty string). When falsy, it was set to `undefined`. The same applied to `path`. This meant configured host/path values were discarded.
+- **Resolution:** Replaced with `host || undefined` and `path || undefined`. Configured values now pass through to `startWebSocketServer` correctly.
+- **Regression test:** `test/ki-001-host-path-passthrough.test.js` (4 tests)
+
+### KI-002 — tunnelIdHeaderName Default Mismatch *(Resolved)*
+
+- **Area:** `nodes/wsTunnel.js` line 32 vs `nodes/wsTunnel.html` line 77
+- **Nature:** The constructor defaults `tunnelIdHeaderName` to `'x-tunnel-id'`, but the HTML registration defaulted it to `''`. When a user did not configure this field, the runtime value differed from the editor default.
+- **Resolution:** Updated HTML default from `''` to `'x-tunnel-id'` to match constructor, documentation, and library examples.
+- **Regression test:** `test/ki-002-tunnel-id-header-default.test.js` (3 tests)
+
+### KI-003 — Leftover Debug Log Statement *(Resolved)*
+
+- **Area:** `nodes/wsTunnel.js` line 117
+- **Nature:** `logger.info('[DEBUG] Close called for node ...')` was a debug statement left in production code using info level. It produced unnecessary log noise in every deployment.
+- **Resolution:** Changed to `logger.debug(...)` and removed `[DEBUG]` prefix. Message now only appears when debug logging is enabled.
+- **Regression test:** `test/ki-003-debug-log-level.test.js` (3 tests)
+
+### KI-004 — console.error in Production Code *(Resolved)*
+
+- **Area:** `nodes/wsTunnel.js` line 127
+- **Nature:** `console.error` was used directly instead of the project's `logger.error`. This bypassed log level filtering and produced inconsistent output format.
+- **Resolution:** Replaced with `logger.error` to maintain logging consistency with the start-failure path.
+- **Regression test:** `test/ki-004-console-error-usage.test.js` (1 test)
+
+### KI-005 — License Inconsistency *(Resolved)*
+
+- **Area:** `README.md` (Apache-2.0), `package.json` (MIT), `nodes/wsTunnel.js` header (Apache-2.0), `nodes/wsTunnel.html` header (Apache-2.0).
+- **Nature:** The license declarations were inconsistent across files. `package.json` declared MIT while all other files declared Apache-2.0.
+- **Resolution:** Updated `package.json` from `"license": "MIT"` to `"license": "Apache-2.0"` to match the source files and README.
+
+---
+
+## Open Questions
+
+These are behaviors important to the project for which the repository does not provide sufficient evidence to define a formal invariant. Open Questions are unknown and must not be assumed to be requirements.
+
+*(No open questions remain.)*
+
+---
+
+## Contract Change Policy
+
+A modification to an existing RWT-\* invariant requires:
+
+1. An explicit update to this file (STABILITY_CONTRACT.md).
+2. A written explanation of the changed semantics and the reason for the change.
+3. An update or addition of regression tests for the affected invariant.
+4. Verification that no dependent invariants are violated.
+
+The Stability Contract must never be weakened, removed, or modified solely to make an implementation or test pass. A contract change is appropriate only when the intended system behavior has actually changed.
+
+New invariants may only be added when:
+
+- There is concrete evidence in the repository (code, tests, documentation, CHANGELOG, or commit history) that the property is intentionally protected.
+- The invariant is formulated as a verifiable property, not a vague guideline.
+- The invariant is not a restatement of a rule already in AGENTS.md.
+- The invariant represents a meaningful stability or compatibility requirement.
+
+Implementation details may change without modifying an invariant when the invariant itself remains satisfied.