WebSocket Tunnel Client

A simple, command-line WebSocket-based tunnel client that allows you to expose your local server to the internet through a tunnel server.

This tool connects to a compatible WebSocket tunnel server (like the one in the parent directory of this project) and forwards incoming public requests to a specified local server.

Features

• Expose any local HTTP/HTTPS server to a public URL.
• Connects via secure (WSS) or insecure (WS) WebSockets.
• Simple command-line interface.
• Automatic reconnection attempts on disconnect.
• Configurable tunnel server URL.

Installation

Install the client globally using npm:

# Option 1: Install directly from the source code (for development)
cd client # Navigate to this directory
npm install -g .

# Option 2: Install from NPM (if published)
# npm install -g websocket-tunnel-client

This installation makes the tunnel-client command available system-wide in your terminal.

Usage

The basic command structure is:

tunnel-client <local-server-url> [options]

Arguments:

• <local-server-url>: Required. The full URL of your local server that you want to expose. Include the protocol (http or https).
  • Example: http://localhost:3000
  • Example: https://127.0.0.1:8443

Options:

• -s, --server-url <url>: The WebSocket URL (ws:// or wss://) of the tunnel server to connect to.
  • Defaults to ws://localhost:8080 (useful if running the server locally).
  • For a deployed server (e.g., on Fly.io), use its public WebSocket address like wss://your-app-name.fly.dev.
• -h, --help: Display help information and exit.

Examples:

1. Expose local server http://localhost:5000 using the default tunnel server (ws://localhost:8080):

   tunnel-client http://localhost:5000

2. Expose local server http://127.0.0.1:8080 using a specific, deployed tunnel server:

   tunnel-client http://127.0.0.1:8080 -s wss://my-tunnel-app.fly.dev

3. Expose a local HTTPS server:

   tunnel-client https://localhost:8443

Upon successful connection, the client will print the assigned public URL.

How It Works

1. The tunnel-client CLI connects to the specified --server-url via WebSocket.
2. The tunnel server accepts the connection and assigns a unique Tunnel ID.
3. The client prints the public URL constructed from the server URL and the Tunnel ID (e.g., https://my-tunnel-app.fly.dev/<tunnel-id>).
4. When an HTTP request hits the public URL:
   • The tunnel server forwards the request details (method, path, headers, body) to the connected client over the WebSocket.
   • The tunnel-client receives the details and makes an equivalent HTTP/HTTPS request to your <local-server-url>.
   • The response from your local server (status, headers, body) is captured by the tunnel-client.
   • The client sends the response details back to the tunnel server over the WebSocket.
   • The tunnel server sends the HTTP response back to the original requester.

Development (Contributing)

1. Clone the main project repository.
2. Navigate to the client directory: cd client
3. Install development dependencies: npm install
4. Make your code changes in tunnel-client.js.
5. You can run the client directly during development without global installation:

   node tunnel-client.js http://localhost:3000 --server-url ws://localhost:8080

License

MIT

Running as a Service (Optional)

For persistent operation after global installation, you can use a process manager like PM2:

pm2 start $(which tunnel-client) --name "my-tunnel" -- <local-server-url> [options]
# Example:
pm2 start $(which tunnel-client) --name "api-tunnel" -- http://localhost:3001 -s wss://my-tunnel-server.com