Architecture

System architecture and core components of Sockudo

Overview

Sockudo is built with a modular architecture that enables horizontal scaling, flexible backend storage, and high-performance real-time communication. The server uses an adapter pattern throughout, allowing you to swap implementations based on your infrastructure needs.

Core Components

Sockudo’s architecture is composed of several key subsystems:

Connection Manager & Adapters

The Connection Manager handles all WebSocket connections and channel subscriptions. It uses an adapter pattern to support different scaling strategies:

• Local Adapter - In-memory implementation for single-node deployments
• Redis Adapter - Distributed pub/sub using Redis for horizontal scaling
• Redis Cluster Adapter - High-availability setup with Redis Cluster
• NATS Adapter - Cloud-native messaging with NATS for multi-region deployments

All adapters implement the same ConnectionManager trait, making it easy to switch between implementations without changing application code.

// Example: Adapter trait interface
pub trait ConnectionManager: Send + Sync {
    async fn add_to_channel(&self, app_id: &str, channel: &str, socket_id: &SocketId) -> Result<()>;
    async fn remove_from_channel(&self, app_id: &str, channel: &str, socket_id: &SocketId) -> Result<bool>;
    async fn broadcast(&self, app_id: &str, channel: &str, message: &str) -> Result<()>;
    // ... other methods
}

App Manager

The App Manager handles application configuration and credentials. It supports multiple backend storage options:

• Memory - In-memory storage for development
• MySQL - Traditional relational database
• PostgreSQL - Advanced relational database with JSON support
• ScyllaDB - High-performance NoSQL database
• DynamoDB - AWS managed NoSQL service

App configurations are cached in memory with configurable TTL to reduce database load.

Cache Manager

The Cache Manager provides a flexible caching layer for:

• Channel data caching
• App configuration caching
• Presence member lists
• Rate limiting counters

Supported backends:

• Memory - Local LRU cache
• Redis - Distributed caching
• Redis Cluster - High-availability distributed caching

Queue Manager

The Queue Manager handles asynchronous job processing, primarily for webhooks:

• Memory Queue - In-process queue for single-node setups
• Redis Queue - Distributed queue with Redis
• Redis Cluster Queue - High-availability queue
• SQS - AWS managed queue service

Webhooks are batched and processed asynchronously to avoid blocking message delivery.

Horizontal Scaling

Sockudo achieves horizontal scaling through its adapter architecture:

1. Choose an adapter

   Select Redis, Redis Cluster, or NATS as your connection adapter. This enables pub/sub across multiple server instances.

2. Configure shared state

   Use a database-backed App Manager (MySQL, PostgreSQL, DynamoDB) so all instances share the same application configuration.

3. Deploy multiple instances

   Launch multiple Sockudo instances with identical configuration. Each instance maintains its own local connections.

4. Load balance connections

   Use a load balancer with sticky sessions to distribute WebSocket connections across instances.

How Messages Flow

1. Client A connects to Instance 1 and subscribes to channel-1
2. Client B connects to Instance 2 and subscribes to channel-1
3. API request publishes message to channel-1 on Instance 1
4. Instance 1 publishes message to Redis/NATS adapter
5. Instance 2 receives message from adapter and delivers to Client B

Message Flow

The path of a message through Sockudo:

1. HTTP API receives event - REST endpoint accepts event data
2. Authentication - HMAC-SHA256 signature validation
3. Channel broadcast - Message sent to adapter for distribution
4. Tag filtering (optional) - Server-side filtering based on subscriber filters
5. Delta compression (optional) - Compute and send delta instead of full message
6. WebSocket delivery - Message serialized and sent to connected clients
7. Webhook queuing - Event queued for webhook delivery if configured

Performance Optimizations

Connection Pooling

All database and Redis connections use connection pooling automatically. Pool sizes are configurable:

{
  "database_pooling": {
    "min": 5,
    "max": 20,
    "timeout": 30
  }
}

Bounded Buffers

WebSocket connections use bounded buffers to prevent slow consumers from exhausting memory:

• Message-based limits - Maximum number of queued messages (default: 1000)
• Byte-based limits - Maximum buffer size in bytes (optional)
• Backpressure handling - Disconnect or drop messages when buffer is full

Zero-Copy Message Parsing

Sockudo uses sonic-rs for JSON parsing with minimal allocations and zero-copy string handling where possible.

Lock-Free Data Structures

Critical paths use lock-free algorithms and atomic operations to minimize contention:

• Atomic counters for metrics
• Lock-free channel caches
• Optimistic concurrency for presence updates

Security Architecture

Authentication Layers

1. WebSocket Authentication - App key validation on connection
2. Channel Authentication - HMAC signatures for private/presence channels
3. API Authentication - Pusher-compatible request signing
4. Origin Validation - Per-app CORS origin checking

Rate Limiting

Multi-level rate limiting protects against abuse:

• HTTP API rate limiting - Per-IP limits on REST endpoints
• WebSocket rate limiting - Per-connection message rate limits
• Backend rate limiting - Redis-based distributed rate limiting

TLS/SSL Support

Sockudo supports TLS termination with:

• Certificate-based HTTPS
• Automatic HTTP to HTTPS redirect
• Unix socket support for reverse proxy deployments

Monitoring & Observability

Sockudo exposes metrics and health endpoints:

• Prometheus metrics - /metrics endpoint with detailed server statistics
• Health checks - /up and /up/{app_id} for load balancer health probes
• Structured logging - JSON or human-readable logs with configurable levels
• Debug mode - Detailed tracing for troubleshooting

Configuration Hierarchy

Configuration values are resolved in this order (highest priority first):

1. Environment variables - ADAPTER_DRIVER=redis
2. Command-line arguments - --config /path/to/config.json
3. Config file - config/config.json
4. Default values - Hardcoded defaults

This allows flexible deployment across different environments while maintaining sensible defaults.

Next Steps

Pusher Protocol

Learn about protocol compatibility and message formats

Channels

Understand channel types and subscription management

Authentication

Implement HMAC authentication for private channels

Configuration

Configure Sockudo for your deployment