WebSocket Support

Local Proxy Inspector (LPI) v1.2.0 introduces full WebSocket support, allowing you to proxy and debug WebSocket connections alongside regular HTTP traffic.

Overview

WebSocket support enables LPI to:

  • Proxy WebSocket connections transparently
  • Route different paths to different backend servers
  • Monitor WebSocket connection lifecycle
  • Track message counts and data volume
  • Display connections in the web UI

Basic Usage

Simple WebSocket Proxy

To proxy all WebSocket traffic to a single backend:

lpi --proxy 3000 --target ws://localhost:8080

This will proxy both HTTP and WebSocket traffic to the target server.

Path-Based Routing

Route different paths to different backends using the --route flags:

lpi --proxy 3000 \
    --route "/app/*" --route-target "ws://localhost:8080" \
    --route "/api/*" --route-target "http://localhost:3001" \
    --route "/*" --route-target "http://localhost:80"

This configuration:

  • Routes /app/* WebSocket connections to port 8080
  • Routes /api/* HTTP requests to port 3001
  • Routes everything else to port 80

Configuration File

For complex routing, use a YAML configuration file:

# routes.yaml
routes:
  - path: "/app/*"
    target: "ws://localhost:8080"
    websocket: true
  - path: "/api/*"
    target: "http://localhost:3001"
    websocket: false
  - path: "/*"
    target: "http://localhost:80"
    websocket: false

Then run:

lpi --proxy 3000 --config routes.yaml

WebSocket Features

Connection Tracking

LPI tracks WebSocket connections with:

  • Connection duration
  • Message count (sent/received)
  • Data volume (bytes sent/received)
  • Connection status and errors

UI Integration

WebSocket connections appear in the main request list with:

  • WebSocket icon indicator
  • "WEBSOCKET" method label
  • Connection duration for long-lived connections
  • Connection statistics in detail view

Verbose Logging

Enable WebSocket message logging for debugging:

lpi --proxy 3000 --target ws://localhost:8080 --ws-verbose

This logs all WebSocket messages to the console (not stored in database).

Real-World Examples

Laravel Reverb / Broadcasting

# Route WebSocket traffic to Reverb, HTTP to Laravel
lpi --proxy 3000 \
    --route "/app/*" --route-target "ws://localhost:8080" \
    --route "/*" --route-target "http://localhost:80"

Socket.IO Application

# Socket.IO uses both HTTP and WebSocket on same path
lpi --proxy 3000 \
    --route "/socket.io/*" --route-target "ws://localhost:3001" \
    --route "/*" --route-target "http://localhost:3000"

Microservices with WebSocket

# microservices.yaml
routes:
  - path: "/chat/*"
    target: "ws://chat-service:8080"
    websocket: true
  - path: "/notifications/*"
    target: "ws://notification-service:8081"
    websocket: true
  - path: "/api/*"
    target: "http://api-gateway:3000"
    websocket: false
  - path: "/*"
    target: "http://frontend:80"
    websocket: false

Technical Details

WebSocket Detection

LPI automatically detects WebSocket upgrade requests by checking for:

  • Connection: Upgrade header
  • Upgrade: websocket header

Protocol Support

  • Supports both ws:// and wss:// protocols
  • Automatic protocol selection based on target URL
  • Preserves WebSocket subprotocols and extensions

Route Matching

  • Routes are evaluated in order (first match wins)
  • Supports wildcard patterns with *
  • More specific routes should be defined first

Performance

  • Minimal overhead for WebSocket frame forwarding
  • Efficient bidirectional message copying
  • No message buffering (real-time forwarding)

Limitations

Mock Mode

WebSocket connections are not affected by --always-reply mock mode. They always attempt to connect to the real backend server.

Message Storage

By default, individual WebSocket messages are not stored in the database (only connection metadata). Use --ws-verbose for debugging message content.

Binary Messages

Binary WebSocket messages are forwarded correctly but may not display properly in verbose mode.

Troubleshooting

Connection Fails Immediately

Check that:

  • Target WebSocket server is running
  • Route configuration matches the WebSocket path
  • No firewall blocking WebSocket connections

"WebSocket not supported on this route"

This error occurs when:

  • A WebSocket request matches a route with websocket: false
  • Solution: Update route configuration to allow WebSocket

Messages Not Appearing

Remember that:

  • Individual messages are not stored by default
  • Use --ws-verbose to see message content
  • Check browser console for client-side errors

See Also