@yousolution/node-red-contrib-you-tunnel-websocket 1.2.0
Module to create websockeet tunnel for NODE-RED
node-red-contrib-you-tunnel-websocket
A Node-RED node collection for creating WebSocket tunnels that enable HTTP traffic routing over WebSocket connections.
Install
Install via Node-RED palette manager, or:
npm install @yousolution/node-red-contrib-you-tunnel-websocket
Nodes
wstunnel
Configuration node for WebSocket tunnel server settings.
Properties
- Name: Descriptive name for the tunnel configuration (required)
- Host: Hostname or IP address to bind the WebSocket server (default:
localhost) - Port: Port number for the WebSocket server (default:
443) - Path: Optional path component for the WebSocket URL
- Tunnel ID Header: HTTP header name used to identify tunnel connections (default:
x-tunnel-id) - Log Level: Logging verbosity level (
trace,debug,info,warning,error)
wstunnel server
Creates a WebSocket server that can tunnel HTTP traffic over WebSocket connections.
Properties
- Name: Optional name for the node
- wstunnel: Reference to a wstunnel configuration node (required)
Inputs
| Property | Type | Description |
|---|---|---|
* |
any |
Send any message to request a metrics snapshot on the output |
Outputs
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
The server node creates a WebSocket server that listens for client connections. HTTP traffic can be tunneled through established WebSocket connections using tunnel ID headers.
Status indicators:
- 🔴 disconnected: Server is not running
- 🟢 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.payloadistrue. - Output 1 (failure): Tunnel not found or not connected.
msg.payloadisfalse,msg.errorcontains 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
Add a wstunnel configuration node:
- Set Name, Host, Port, and other options
Add a wstunnel server node:
- Select the configuration node
- Deploy the flow
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:
ws://[host]:[port][/path]
For secure connections:
wss://[host]:[port][/path]
Requirements
- Node-RED: >= 2.0.0
- Node.js: >= 12.0.0
License
Apache-2.0
Author
Andrea Trentin ([email protected])
Repository: yousolution-cloud/node-red-contrib-you-tunnel-websocket
