WebSocket Configuration

Configure WebSocket buffer limits, backpressure, and compression settings

Sockudo provides extensive WebSocket configuration options to handle high-throughput scenarios, slow consumers, and optimize bandwidth usage.

Buffer Configuration (Slow Consumer Handling)

Sockudo uses bounded buffers to protect against slow consumers that can’t keep up with message delivery. This prevents unbounded memory growth.

Three Buffer Limit Modes

1. Message count only (default, fastest) - No size tracking overhead
2. Byte size only - Precise memory control
3. Both limits - Whichever triggers first (most precise)

Mode 1: Message Count Only (Default)

{
  "websocket": {
    "max_messages": 1000,
    "max_bytes": null,
    "disconnect_on_buffer_full": false
  }
}

WEBSOCKET_MAX_MESSAGES=1000
WEBSOCKET_MAX_BYTES=none
WEBSOCKET_DISCONNECT_ON_BUFFER_FULL=false

Limits the number of messages buffered per connection. Fastest mode with zero overhead for size tracking.

Mode 2: Byte Size Only

{
  "websocket": {
    "max_messages": null,
    "max_bytes": 1048576,
    "disconnect_on_buffer_full": true
  }
}

WEBSOCKET_MAX_MESSAGES=none
WEBSOCKET_MAX_BYTES=1048576  # 1MB
WEBSOCKET_DISCONNECT_ON_BUFFER_FULL=true

Limits total bytes buffered per connection. Provides precise memory control (e.g., 1MB = exactly 1MB max).

Mode 3: Both Limits

{
  "websocket": {
    "max_messages": 1000,
    "max_bytes": 1048576,
    "disconnect_on_buffer_full": true
  }
}

WEBSOCKET_MAX_MESSAGES=1000
WEBSOCKET_MAX_BYTES=1048576
WEBSOCKET_DISCONNECT_ON_BUFFER_FULL=true

Enforces both limits. Connection is closed or messages dropped when either limit is reached.

Buffer Configuration Options

websocket.max_messages · number · default: "1000"

Maximum number of messages buffered per connection. Set to null or 0 to disable. Default: 1000.

websocket.max_bytes · number · default: "null"

Maximum bytes buffered per connection. Set to null or 0 to disable. Example: 1048576 for 1MB.

websocket.disconnect_on_buffer_full · boolean · default: "false"

When true, disconnects slow clients when buffer is full (error code 4100). When false, drops new messages silently (logged as warning).

Buffer Behavior

When a client cannot consume messages fast enough:

1. Messages queue up in the per-connection buffer
2. Once any configured limit is reached:
   • If disconnect_on_buffer_full: true → Connection closed with error code 4100 (client should reconnect with backoff)
   • If disconnect_on_buffer_full: false → New messages dropped silently (logged as warning)

Performance Characteristics

Message-Only Mode

• Zero overhead for size tracking
• Uses bounded channel capacity
• Fastest mode
• Memory usage depends on average message size (~1-2KB typical)

Byte-Only Mode

• Atomic counter tracking (~1-2ns per message)
• Large channel capacity (10,000 messages)
• Precise memory control
• Example: 1MB byte limit per connection × 10,000 connections = ~10GB worst case

Both Modes

• Atomic counter + channel capacity check
• Most precise control
• Slight overhead from dual checking

WebSocket Connection Settings

{
  "websocket": {
    "max_message_size": 67108864,
    "max_frame_size": 16777216,
    "write_buffer_size": 16384,
    "max_backpressure": 1048576,
    "auto_ping": true,
    "ping_interval": 30,
    "idle_timeout": 120,
    "compression": "disabled"
  }
}

websocket.max_message_size · number · default: "67108864"

Maximum size of a single WebSocket message in bytes (default: 64MB).

websocket.max_frame_size · number · default: "16777216"

Maximum size of a single WebSocket frame in bytes (default: 16MB).

websocket.write_buffer_size · number · default: "16384"

Size of the write buffer for each WebSocket connection in bytes (default: 16KB).

websocket.max_backpressure · number · default: "1048576"

Maximum backpressure before applying flow control in bytes (default: 1MB).

websocket.auto_ping · boolean · default: "true"

Automatically send WebSocket ping frames to keep connections alive.

websocket.ping_interval · number · default: "30"

Interval between ping frames in seconds.

websocket.idle_timeout · number · default: "120"

Idle timeout in seconds before closing inactive connections.

websocket.compression · string · default: "disabled"

WebSocket per-message compression. Options: disabled, enabled. Note: This is separate from Sockudo’s delta compression feature.

Environment Variables

WEBSOCKET_MAX_MESSAGE_SIZE=67108864
WEBSOCKET_MAX_FRAME_SIZE=16777216
WEBSOCKET_WRITE_BUFFER_SIZE=16384
WEBSOCKET_MAX_BACKPRESSURE=1048576
WEBSOCKET_AUTO_PING=true
WEBSOCKET_PING_INTERVAL=30
WEBSOCKET_IDLE_TIMEOUT=120
WEBSOCKET_COMPRESSION=disabled

Payload Limits

# Maximum payload size in kilobytes
WEBSOCKET_MAX_PAYLOAD_KB=64

websocket_max_payload_kb · number · default: "64"

Maximum message payload size in kilobytes. Applies to both client-to-server and server-to-client messages.

Activity Timeout

# Connection activity timeout (seconds)
ACTIVITY_TIMEOUT=120

activity_timeout · number · default: "120"

Time in seconds before marking a connection as inactive. Used for cleanup and monitoring.

Compression Settings

WebSocket Compression

Standard WebSocket per-message deflate compression:

{
  "websocket": {
    "compression": "enabled"
  }
}

WebSocket compression adds CPU overhead and may not provide significant benefits for already-compressed data (JSON with delta compression). Test thoroughly before enabling in production.

Delta Compression (Recommended)

For high-frequency updates with similar consecutive messages, use Sockudo’s built-in delta compression:

{
  "delta_compression": {
    "enabled": true,
    "algorithm": "fossil",
    "full_message_interval": 10,
    "min_message_size": 100
  }
}

See the Delta Compression guide for details.

Connection Limits

Limits are configured per-app in the app manager:

{
  "app_manager": {
    "driver": "memory",
    "array": {
      "apps": [
        {
          "id": "app-id",
          "key": "app-key",
          "secret": "app-secret",
          "max_connections": 100000,
          "max_client_events_per_second": 1000
        }
      ]
    }
  }
}

Or via environment variables for the default app:

SOCKUDO_DEFAULT_APP_MAX_CONNECTIONS=1000
SOCKUDO_DEFAULT_APP_MAX_CLIENT_EVENTS_PER_SECOND=100

Memory Estimation

Per-Connection Memory

Estimate memory usage based on buffer configuration:

Message-only mode:
  Memory per connection = max_messages × avg_message_size
  Example: 1000 messages × 2KB = 2MB per connection

Byte-only mode:
  Memory per connection = max_bytes
  Example: 1MB per connection (exact)

Both modes:
  Memory per connection = min(max_messages × avg_message_size, max_bytes)

Total Memory

Total memory = connections × memory_per_connection

Example with 10,000 connections:
  Message-only (1000 msgs, 2KB avg): 10,000 × 2MB = 20GB
  Byte-only (1MB limit): 10,000 × 1MB = 10GB

Best Practices

Development

• Use default message-only mode (fastest)
• Set higher limits for testing (e.g., 10,000 messages)
• Use disconnect_on_buffer_full: false to avoid reconnection storms
• Enable debug logging to see buffer warnings

Production

• Use byte limits for predictable memory usage
• Set disconnect_on_buffer_full: true to protect server resources
• Monitor buffer full events via metrics
• Adjust limits based on:
  • Average message size
  • Expected burst rates
  • Available memory
  • Client reconnection behavior

High-Throughput Scenarios

• Increase max_bytes to handle bursts (e.g., 2-5MB)
• Enable delta compression to reduce message sizes
• Use Redis Cluster adapter for horizontal scaling
• Monitor per-connection buffer usage via metrics

Low-Latency Requirements

• Keep buffers small to detect slow consumers quickly
• Set disconnect_on_buffer_full: true
• Enable auto-ping with short intervals (10-15 seconds)
• Monitor idle timeout and adjust based on network conditions

Monitoring

Key metrics to monitor:

• sockudo_websocket_connections_total - Active connections
• sockudo_websocket_messages_sent_total - Messages sent
• sockudo_websocket_buffer_full_total - Buffer overflow events
• sockudo_websocket_disconnects_total - Disconnections by reason

# View metrics
curl http://localhost:9601/metrics | grep websocket

Troubleshooting

Slow Consumer Detection

If clients are being disconnected with error code 4100:

1. Check if clients are actually slow (network issues, processing delays)
2. Increase buffer limits if clients have legitimate bursts
3. Reduce message frequency from publishers
4. Enable delta compression to reduce message sizes
5. Consider using disconnect_on_buffer_full: false if reconnections cause issues

High Memory Usage

1. Check max_messages and max_bytes settings
2. Monitor average message size
3. Reduce limits or switch to byte-only mode
4. Enable delta compression
5. Implement client-side throttling

Connection Drops

1. Check idle_timeout and ping_interval settings
2. Ensure clients respond to ping frames
3. Monitor network conditions
4. Adjust timeouts based on client behavior

Next Steps

Environment Variables

Complete reference of all configuration options

Delta Compression

Reduce bandwidth with delta compression

Monitoring

Set up Prometheus metrics