TrustGate provides robust WebSocket support, allowing you to proxy and manage WebSocket connections between clients and upstream services. This document explains how to configure and use WebSocket functionality in TrustGate.

​
Overview

WebSockets enable bidirectional, real-time communication between clients and servers. TrustGate acts as a proxy for WebSocket connections, providing features such as:

  • Connection management and load balancing
  • Health checks for upstream services
  • Plugin execution for WebSocket messages
  • Two communication modes: direct and multiplexed

​
Configuration

To enable WebSocket support for an upstream service, you need to include a websocket_config section in your upstream configuration.

​
Example Configuration

{
    "name": "my-websocket-service",
    "algorithm": "round-robin",
    "targets": [{
        "host": "localhost",
        "port": 3001,
        "protocol": "http",
        "weight": 100,
        "priority": 1,
        "path": "/ws/dummy"
    }],
    "websocket_config": {
        "enable_direct_communication": false,
        "return_error_details": true,
        "ping_period": "30s",
        "pong_wait": "2m",
        "handshake_timeout": "5s",
        "read_buffer_size": 4096,
        "write_buffer_size": 4096
    },
    "health_checks": {
        "passive": true,
        "threshold": 3,
        "interval": 60
    }
}

​
WebSocket Configuration Options

OptionTypeDescriptionDefault
enable_direct_communicationbooleanWhen true, each client connection gets its own dedicated connection to the upstream service. When false, connections are multiplexed.false
return_error_detailsbooleanWhen true, detailed error messages are returned to clients.false
ping_periodstringThe interval for sending ping messages to keep connections alive (e.g., ”30s”).”30s”
pong_waitstringThe timeout for receiving pong responses (e.g., “2m”).”45s”
handshake_timeoutstringThe timeout for the initial WebSocket handshake (e.g., “5s”).“5s”
read_buffer_sizeintegerThe size of the read buffer in bytes.4096
write_buffer_sizeintegerThe size of the write buffer in bytes.4096

​
Health Check Configuration

Health checks help ensure that only healthy upstream services receive WebSocket connections.

OptionTypeDescriptionDefault
passivebooleanWhen true, enables passive health checks that monitor actual traffic.false
pathstringThe path to use for active health checks.""
headersobjectHeaders to include in health check requests.{}
thresholdintegerNumber of failures before marking a target as unhealthy.3
intervalintegerTime in seconds before resetting the failure count.60

​
Communication Modes

TrustGate supports two communication modes for WebSockets:

​
Direct Communication Mode

In direct communication mode (enable_direct_communication: true), each client connection gets its own dedicated connection to the upstream service. This mode is useful when:

  • You need to preserve connection-specific state on the upstream service
  • You want to ensure a 1:1 mapping between client and upstream connections
  • You need to minimize latency

​
Multiplexed Mode

In multiplexed mode (enable_direct_communication: false), TrustGate maintains a pool of connections to upstream services and routes messages from multiple clients through these shared connections. This mode is useful when:

  • You want to reduce the number of connections to your upstream services
  • Your upstream services don’t need to maintain connection-specific state
  • You want to optimize resource usage

​
Path Configuration

WebSocket endpoints should be configured with paths that include /ws/ to be properly identified by TrustGate. For example:

/ws/chat
/ws/notifications
/ws/live-updates

​
Plugin Support

TrustGate’s plugin system works with WebSocket connections, allowing you to:

  • Execute plugins at the PreRequest stage (before forwarding messages to upstream)
  • Execute plugins at the PostResponse stage (before returning messages to clients)
  • Modify message content
  • Implement custom authentication or authorization
  • Add logging or metrics collection

​
Error Handling

When return_error_details is enabled, TrustGate will send detailed error messages to clients when issues occur, such as:

  • Connection failures to upstream services
  • Plugin execution errors
  • Timeout errors

​
Best Practices

  1. Set appropriate timeouts: Configure ping_period, pong_wait, and handshake_timeout based on your application’s needs.
  2. Enable health checks: Use health checks to ensure traffic is only sent to healthy upstream services.
  3. Choose the right communication mode: Use direct communication when you need 1:1 connection mapping, and multiplexed mode when optimizing for resource usage.
  4. Monitor connection counts: Set appropriate max_connections in your global WebSocket configuration to prevent resource exhaustion.
  5. Implement proper error handling: Client applications should handle reconnection logic when connections are closed.

​
Global WebSocket Configuration

In addition to per-upstream configuration, TrustGate has global WebSocket settings in its main configuration:

websocket:
  max_connections: 10000  # Maximum number of concurrent WebSocket connections
  ping_period: "30s"      # Default ping period
  pong_wait: "45s"        # Default pong wait timeout