WebSocket Proxy Tool

A Node.js WebSocket proxy designed for debugging and testing WebSocket-based applications. This tool allows you to inspect connections, and simulate network failures by controlling live connections from the terminal.

Features

• Transparent Proxying: Forwards messages and crucial headers between client and target.

• Connection Management: List, close, and forcefully disconnect connections by ID.

• Automated Testing: Schedule single or repeating connection actions on a timer.

• Message Type Handling: Automatically converts messages to a string to prevent unexpected binary data.

Installation

1. Make sure you have Node.js and npm installed.

2. Place the websocket_proxy.js and package.json files in the same directory.

3. Install the required dependencies by running the following command in your terminal:

   npm install
   

Configuration

Before running, open websocket_proxy.js and change the TARGET_WS_URL constant to the URL of the WebSocket server you want to proxy.

const TARGET_WS_URL = 'wss://ws.example.com/';

Usage

Update the client

Replace the URL of the target WebSocket server with ws://localhost:8080/

Running the Server

Start the proxy server by running the following command:

npm start

The server will listen for incoming WebSocket connections on port 8080 by default.

Terminal Commands

Once the server is running, you can use the following commands in the terminal to interact with the proxy:

• help: Shows the list of available commands.

• list: Lists all active connections with their unique IDs and states.

• close <ID | first>: Performs a clean WebSocket close on the specified connection ID. Use first to target the first connection in the list.

• disconnect <ID | first>: Forcefully terminates a connection without a proper handshake, simulating a sudden network drop.

• schedule <close | disconnect> <seconds> | random repeating: Schedules a repeating action on the first connection. The action will be performed every <seconds> (or a random duration between 1 and 20 seconds).

• unschedule repeating: Cancels the currently scheduled repeating task.

• exit: Closes all connections and shuts down the proxy server.

Running Tests

To run the tests, use:

npm test