ws-echo

A simple CLI tool to forward WebSocket messages between ports. Perfect for testing, development, and creating WebSocket proxies.

Installation

Global Installation

npm install -g ws-echo

Local Development

npm install
npm link

Run without Installation

npx ws-echo [options]

Usage

Basic Usage

# Forward messages from port 8080 to port 8081
ws-echo --port-in 8080 --port-out 8081

# Using short aliases
ws-echo -i 8080 -o 8081

# Echo messages on the same port (all clients receive each other's messages)
ws-echo --port-in 3000 --port-out 3000

Default Behavior

If no ports are specified, the tool will:

• Use port 8080 for input
• Use port 8081 for output

# This is equivalent to: ws-echo -i 8080 -o 8081
ws-echo

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --port-in | -i | Input port to receive WebSocket messages | 8080 | | --port-out | -o | Output port to forward WebSocket messages | 8081 | | --output-write | --ow | Output file to store messages with timestamps in JSON format | | | --input-read | --ir | Input file to read and replay messages with original timings | | | --loop | | Loop playback of input file every 5 seconds (only works with --ir) | false | | --help | -h | Show help | |

Examples

1. Message Forwarding (Different Ports)

ws-echo -i 8080 -o 8081

• Connect input clients to ws://localhost:8080
• Connect output clients to ws://localhost:8081
• Messages sent to port 8080 will be forwarded to all clients connected to port 8081

2. Message Echo (Same Port)

ws-echo -i 3000 -o 3000

• All clients connect to ws://localhost:3000
• Messages from any client are echoed to all other clients on the same port
• Perfect for chat applications or multi-client synchronization

3. Message Recording and Playback

# Record messages to a file
ws-echo -i 8080 -o 8081 --ow messages.json

# Replay recorded messages to output port
ws-echo -o 8081 --ir messages.json

# Replay messages in a continuous loop with 5-second delay between loops
ws-echo -o 8081 --ir messages.json --loop

• Messages are recorded with timestamps in JSON format
• During playback, messages are replayed with their original timing
• Playback starts automatically when output clients connect
• Use --loop to continuously replay messages with a 5-second delay between loops
• Perfect for testing, demos, and reproducing scenarios

4. Testing WebSocket Applications

# Terminal 1: Start the echo server
ws-echo -i 9000 -o 9001

# Terminal 2: Connect a test client to input port
wscat -c ws://localhost:9000

# Terminal 3: Connect a listener to output port
wscat -c ws://localhost:9001

Use Cases

• WebSocket Debugging: Monitor and forward WebSocket traffic
• Load Testing: Broadcast messages to multiple clients
• Development: Create mock WebSocket servers for testing
• Chat Applications: Echo messages between multiple clients
• Microservices: Forward WebSocket messages between services
• Message Recording: Save WebSocket traffic for later analysis
• Scenario Replay: Reproduce exact message sequences with original timing

Features

• ✅ Supports multiple concurrent connections
• ✅ Real-time message forwarding
• ✅ Same-port echo mode
• ✅ Message recording with timestamps
• ✅ Time-accurate message playback
• ✅ Continuous message loop playback
• ✅ Graceful shutdown handling
• ✅ Detailed connection logging
• ✅ Error handling and recovery
• ✅ Cross-platform compatibility

Output Example

🚀 Starting ws-echo...
📥 Input port: 8080
📤 Output port: 8081
✅ Input server listening on port 8080
✅ Output server listening on port 8081

📝 Usage:
   Connect input clients to:  ws://localhost:8080
   Connect output clients to: ws://localhost:8081

🔄 Ready to forward messages! Press Ctrl+C to stop.

📥 Input client connected: ::1:51234
📤 Output client connected: ::1:51235
💬 Received message from ::1:51234: Hello World!
📤 Forwarded message to 1 output client(s)

Requirements

• Node.js >= 14.0.0
• npm or yarn

Dependencies

• express: HTTP server framework
• ws: WebSocket library
• yargs: Command line argument parsing

License

MIT