Adapter Configuration

Adapters handle connection management, channel subscriptions, and inter-node communication in Sockudo. The adapter you choose determines how Sockudo scales horizontally.

Available Adapters

Local

Single-instance, in-memory adapter. No external dependencies.

Redis

Pub/Sub-based horizontal scaling using Redis.

Redis Cluster

Distributed Redis Cluster support for high availability.

NATS

Lightweight messaging with NATS for horizontal scaling.

Adapter Selection

Set the adapter driver in your configuration:

{
  "adapter": {
    "driver": "redis",
    "enable_socket_counting": true
  }
}

Or via environment variable:

ADAPTER_DRIVER=redis  # local, redis, redis-cluster, nats

Local Adapter

The local adapter stores all connection and subscription data in memory. It’s suitable for:

Single-instance deployments
Development and testing
Low-traffic applications

Configuration

{
  "adapter": {
    "driver": "local",
    "enable_socket_counting": true
  }
}

driver

string

required

Set to "local" for in-memory adapter.

enable_socket_counting

boolean

default:"true"

Enable counting of active sockets per channel. Disable for performance if you don’t use the get_sockets_count API.

The local adapter does not support horizontal scaling. All connections must connect to the same instance.

Redis Adapter

The Redis adapter uses Redis Pub/Sub for inter-node communication, enabling horizontal scaling across multiple Sockudo instances.

Configuration

{
  "adapter": {
    "driver": "redis"
  },
  "database": {
    "redis": {
      "host": "localhost",
      "port": 6379,
      "password": "your-password",
      "db": 0,
      "key_prefix": "sockudo:"
    }
  }
}

Environment Variables

ADAPTER_DRIVER=redis
DATABASE_REDIS_HOST=localhost
DATABASE_REDIS_PORT=6379
DATABASE_REDIS_PASSWORD=secret
DATABASE_REDIS_DB=0
DATABASE_REDIS_KEY_PREFIX=sockudo:

Redis URL Override

You can use a single URL to configure Redis:

REDIS_URL=redis://username:password@host:port/db

This overrides all individual Redis configuration settings.

Redis Configuration Options

database.redis.host

string

default:"localhost"

Redis server hostname or IP address.

database.redis.port

number

default:"6379"

Redis server port.

database.redis.username

string

Redis username for ACL authentication (Redis 6+).

database.redis.password

string

Redis password for authentication.

database.redis.db

number

default:"0"

Redis database number (0-15).

database.redis.key_prefix

string

default:"sockudo:"

Prefix for all Redis keys to avoid collisions with other applications.

Redis Sentinel

Redis Sentinel provides high availability for Redis by automatically handling master failover.

Configuration

{
  "adapter": {
    "driver": "redis"
  },
  "database": {
    "redis": {
      "sentinels": [
        { "host": "sentinel1.example.com", "port": 26379 },
        { "host": "sentinel2.example.com", "port": 26379 },
        { "host": "sentinel3.example.com", "port": 26379 }
      ],
      "sentinel_password": "optional-sentinel-auth",
      "name": "mymaster",
      "password": "optional-redis-master-password",
      "username": "optional-username",
      "db": 0,
      "key_prefix": "sockudo:"
    }
  }
}

database.redis.sentinels

array

Array of sentinel nodes with host and port fields.

database.redis.sentinel_password

string

Password for authenticating with sentinel nodes (if required).

database.redis.name

string

default:"mymaster"

The master name monitored by sentinels.

database.redis.password

string

Password for the Redis master instance.

database.redis.username

string

Username for Redis ACL authentication.

When sentinels are configured, the connection URL is automatically built in the format: redis+sentinel://[sentinelpass@]host1:port1,host2:port2/master-name/db[?password=masterpass]

Redis Cluster Adapter

Redis Cluster provides automatic sharding and high availability across multiple Redis nodes.

Configuration

{
  "adapter": {
    "driver": "redis-cluster",
    "cluster": {
      "nodes": [
        "redis-1:7000",
        "redis-2:7001",
        "redis-3:7002"
      ],
      "prefix": "sockudo_adapter:",
      "request_timeout_ms": 5000,
      "use_connection_manager": true
    },
    "cluster_health": {
      "enabled": true,
      "heartbeat_interval_ms": 10000,
      "node_timeout_ms": 30000,
      "cleanup_interval_ms": 10000
    }
  }
}

Environment Variables

ADAPTER_DRIVER=redis-cluster

# Comma-separated list of cluster nodes
REDIS_CLUSTER_NODES=redis-1:7000,redis-2:7001,redis-3:7002
# or
DATABASE_REDIS_CLUSTER_NODES=redis-1:7000,redis-2:7001,redis-3:7002

# Optional auth/TLS
DATABASE_REDIS_CLUSTER_USERNAME=user
DATABASE_REDIS_CLUSTER_PASSWORD=secret
DATABASE_REDIS_CLUSTER_USE_TLS=false

Redis Cluster Options

adapter.cluster.nodes

array

required

Array of Redis cluster node addresses in host:port format. Accepts redis://host:port or rediss://host:port URLs.

adapter.cluster.prefix

string

default:"sockudo_adapter:"

Key prefix for adapter data in Redis Cluster.

adapter.cluster.request_timeout_ms

number

default:"5000"

Timeout for Redis Cluster requests in milliseconds.

adapter.cluster.use_connection_manager

boolean

default:"true"

Use connection pooling for better performance.

Cluster Health Monitoring

adapter.cluster_health.enabled

boolean

default:"true"

Enable cluster health checks and automatic node failure detection.

adapter.cluster_health.heartbeat_interval_ms

number

default:"10000"

Interval between heartbeat checks in milliseconds.

adapter.cluster_health.node_timeout_ms

number

default:"30000"

Time to wait before marking a node as failed.

adapter.cluster_health.cleanup_interval_ms

number

default:"10000"

Interval for cleaning up failed node metadata.

NATS Adapter

NATS is a lightweight, high-performance messaging system ideal for microservices architectures.

Configuration

ADAPTER_DRIVER=nats

# Comma-separated list of NATS servers
NATS_SERVERS=nats://nats-1:4222,nats://nats-2:4222

# Authentication (optional)
NATS_USERNAME=user
NATS_PASSWORD=secret
# or
NATS_TOKEN=auth-token

# Connection settings
NATS_CONNECTION_TIMEOUT_MS=5000
NATS_REQUEST_TIMEOUT_MS=5000

NATS_SERVERS

string

required

Comma-separated list of NATS server URLs (e.g., nats://host:port).

NATS_USERNAME

string

NATS username for authentication.

NATS_PASSWORD

string

NATS password for authentication.

NATS_TOKEN

string

NATS authentication token (alternative to username/password).

NATS_CONNECTION_TIMEOUT_MS

number

default:"5000"

Connection timeout in milliseconds.

NATS_REQUEST_TIMEOUT_MS

number

default:"5000"

Request timeout in milliseconds.

Unix Socket Configuration

For deployments behind a reverse proxy, you can use Unix domain sockets instead of TCP/IP:

{
  "unix_socket": {
    "enabled": true,
    "path": "/var/run/sockudo/sockudo.sock",
    "permission_mode": "660"
  }
}

Environment Variables

UNIX_SOCKET_ENABLED=true
UNIX_SOCKET_PATH=/var/run/sockudo/sockudo.sock
UNIX_SOCKET_PERMISSION_MODE=660

unix_socket.enabled

boolean

default:"false"

Enable Unix socket server (disables HTTP/HTTPS when enabled).

unix_socket.path

string

default:"/var/run/sockudo/sockudo.sock"

Path to Unix socket file.

unix_socket.permission_mode

string

default:"660"

Socket file permissions in octal notation (e.g., “660”, “755”).

Nginx Example

upstream sockudo {
    server unix:/var/run/sockudo/sockudo.sock;
}

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://sockudo;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Unix sockets are only available on Unix-like systems (Linux, macOS). On Windows, this configuration is ignored.

Feature Compilation

Adapters must be compiled into the binary. Use Cargo features during build:

# Local only (default, fastest)
cargo build --release

# With Redis
cargo build --release --features "local,redis"

# With Redis Cluster
cargo build --release --features "local,redis-cluster"

# With NATS
cargo build --release --features "local,nats"

# All adapters
cargo build --release --features full

If you configure an adapter that wasn’t compiled in, Sockudo will fall back to the local adapter with a warning.

Performance Considerations

Socket Counting

The enable_socket_counting option tracks the number of active connections per channel. This is used by the get_sockets_count API but has a small performance overhead. Disable if you don’t need this metric:

ADAPTER_ENABLE_SOCKET_COUNTING=false

Redis Connection Pooling

Redis adapters use connection pooling automatically. Adjust pool size via:

REDIS_CONNECTION_POOL_SIZE=10
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

Adapter Configuration

Available Adapters

Local

Redis

Redis Cluster

NATS

Adapter Selection

Local Adapter

Configuration

Redis Adapter

Configuration

Environment Variables

Redis URL Override

Redis Configuration Options

Redis Sentinel

Configuration

Redis Cluster Adapter

Configuration

Environment Variables

Redis Cluster Options

Cluster Health Monitoring

NATS Adapter

Configuration

Unix Socket Configuration

Environment Variables

Nginx Example

Feature Compilation

Performance Considerations

Socket Counting

Redis Connection Pooling

Next Steps

Backend Configuration

Horizontal Scaling Guide

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

Documentation Index

​Available Adapters

Local

Redis

Redis Cluster

NATS

​Adapter Selection

​Local Adapter

​Configuration

​Redis Adapter

​Configuration

​Environment Variables

​Redis URL Override

​Redis Configuration Options

​Redis Sentinel

​Configuration

​Redis Cluster Adapter

​Configuration

​Environment Variables

​Redis Cluster Options

​Cluster Health Monitoring

​NATS Adapter

​Configuration

​Unix Socket Configuration

​Environment Variables

​Nginx Example

​Feature Compilation

​Performance Considerations

​Socket Counting

​Redis Connection Pooling

​Next Steps

Backend Configuration

Horizontal Scaling Guide

Available Adapters

Adapter Selection

Local Adapter

Configuration

Redis Adapter

Configuration

Environment Variables

Redis URL Override

Redis Configuration Options

Redis Sentinel

Configuration

Redis Cluster Adapter

Configuration

Environment Variables

Redis Cluster Options

Cluster Health Monitoring

NATS Adapter

Configuration

Unix Socket Configuration

Environment Variables

Nginx Example

Feature Compilation

Performance Considerations

Socket Counting

Redis Connection Pooling

Next Steps