Rate Limiting - Sockudo

Overview

Rate limiting protects your Sockudo server from abuse and ensures fair resource allocation across applications. It provides per-application limits for HTTP API requests, preventing any single app from overwhelming the server. Key Benefits:

Prevents API abuse and DoS attacks
Ensures fair resource allocation
Configurable per-application limits
Multiple backend drivers (memory, Redis, Redis Cluster)

Quick Start

Basic Configuration

config/config.json

{
  "rate_limiter": {
    "enabled": true,
    "driver": "memory"
  }
}

Environment Variable

RATE_LIMITER_ENABLED=true
RATE_LIMITER_DRIVER=memory

Configuration

Global Settings

{
  "rate_limiter": {
    "enabled": true,
    "driver": "memory"
  }
}

Option	Values	Description
`enabled`	`true`/`false`	Enable/disable rate limiting globally
`driver`	`memory`, `redis`, `redis-cluster`, `none`	Rate limiter backend

Per-App Limits

Configure rate limits for individual applications:

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

Option	Default	Description
`max_client_events_per_second`	`1000`	Maximum events per second per app

Rate Limiter Drivers

Memory Driver (Default)

Best for: Single-node deployments, development, testing

{
  "rate_limiter": {
    "enabled": true,
    "driver": "memory"
  }
}

Characteristics:

In-memory counters (fast)
No external dependencies
Per-node limits (not shared across instances)
Lost on server restart

Use when:

Running single Sockudo instance
Development/testing environment
Low-traffic applications

Redis Driver

Best for: Multi-node deployments with shared limits

{
  "rate_limiter": {
    "enabled": true,
    "driver": "redis"
  },
  "database": {
    "redis": {
      "host": "localhost",
      "port": 6379,
      "password": "optional-password",
      "db": 0
    }
  }
}

Characteristics:

Shared counters across all nodes
Cluster-wide rate limits
Persistent across restarts (with Redis persistence)
Slightly higher latency (~1-2ms)

Use when:

Running multiple Sockudo instances
Need cluster-wide rate limits
Production deployments

Redis Cluster Driver

Best for: High-availability deployments with Redis Cluster

{
  "rate_limiter": {
    "enabled": true,
    "driver": "redis-cluster"
  },
  "redis_cluster": {
    "nodes": [
      "redis1:6379",
      "redis2:6379",
      "redis3:6379"
    ]
  }
}

Characteristics:

Distributed across Redis Cluster
High availability
Automatic failover
Horizontal scalability

Use when:

High-availability requirements
Large-scale deployments
Redis Cluster infrastructure

None Driver

Best for: Disabling rate limiting

{
  "rate_limiter": {
    "enabled": false,
    "driver": "none"
  }
}

Use when:

Behind external rate limiter (e.g., nginx, API gateway)
Trusted internal network
Development with no limits

Rate Limiting Behavior

HTTP API Endpoints

Rate limiting is enforced on these endpoints:

Endpoint	Rate Limited	Limit Type
`POST /apps/:app_id/events`	✅ Yes	Per-app
`POST /apps/:app_id/batch_events`	✅ Yes	Per-app
`GET /apps/:app_id/channels`	✅ Yes	Per-app
`GET /apps/:app_id/channels/:channel`	✅ Yes	Per-app
`GET /apps/:app_id/channels/:channel/users`	✅ Yes	Per-app
Health endpoints (`/up/:app_id`)	❌ No	N/A
Metrics endpoint (`/metrics`)	❌ No	N/A

Rate Limit Algorithm

Sockudo uses a token bucket algorithm:

Each app has a bucket with max capacity = max_client_events_per_second
Tokens refill at rate of max_client_events_per_second per second
Each request consumes 1 token
If no tokens available, request is rejected with 429 Too Many Requests

Response Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1678901234

Header	Description
`X-RateLimit-Limit`	Maximum requests per second
`X-RateLimit-Remaining`	Tokens remaining in current window
`X-RateLimit-Reset`	Unix timestamp when limit resets

Rate Limit Exceeded

When rate limit is exceeded, the server returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1678901234

{
  "error": "Rate limit exceeded for app: my-app"
}

Client behavior:

Wait until X-RateLimit-Reset timestamp
Implement exponential backoff
Queue requests client-side

Use Cases

1. Preventing API Abuse

Problem: Malicious client making excessive API calls Solution:

{
  "apps": [
    {
      "id": "public-app",
      "max_client_events_per_second": 100  // Low limit for public apps
    }
  ]
}

Result: API abuse blocked, server remains stable

2. Fair Resource Allocation

Problem: One app consuming all server resources Solution:

{
  "apps": [
    {
      "id": "premium-app",
      "max_client_events_per_second": 10000  // High limit
    },
    {
      "id": "free-app",
      "max_client_events_per_second": 100    // Low limit
    }
  ]
}

Result: Resources fairly distributed across tiers

3. Multi-Tenant SaaS

Problem: Need different limits per customer Solution:

{
  "apps": [
    {
      "id": "customer-1",
      "max_client_events_per_second": 1000
    },
    {
      "id": "customer-2",
      "max_client_events_per_second": 5000
    }
  ]
}

Result: Each customer gets appropriate limits based on plan

4. Development vs Production

Problem: Different limits for different environments Solution:

# Development
RATE_LIMITER_ENABLED=false

# Production
RATE_LIMITER_ENABLED=true
RATE_LIMITER_DRIVER=redis

Result: No limits in dev, enforced in production

Best Practices

1. Set Appropriate Limits

Too low: Legitimate traffic gets blocked Too high: Doesn’t prevent abuse Just right: Allows normal usage, blocks abuse

// Good starting points
{
  "free-tier": 100,      // 100 events/sec
  "standard-tier": 1000, // 1k events/sec
  "premium-tier": 10000  // 10k events/sec
}

2. Use Redis for Multi-Node Deployments

{
  "rate_limiter": {
    "driver": "redis"  // Share limits across nodes
  }
}

Memory driver gives each node independent limits, effectively multiplying the limit by number of nodes.

3. Monitor Rate Limit Metrics

Track rate limit hits via Prometheus metrics:

# Rate limit exceeded count
sockudo_rate_limit_exceeded_total{app_id="my-app"}

# Current rate limit usage
sockudo_rate_limit_remaining{app_id="my-app"}

4. Implement Client-Side Backoff

async function sendWithBackoff(event, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      await sendEvent(event);
      return;
    } catch (error) {
      if (error.status === 429) {
        const resetTime = error.headers['x-ratelimit-reset'];
        const waitMs = (resetTime * 1000) - Date.now();
        await sleep(Math.max(waitMs, 1000 * Math.pow(2, i)));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Rate limit exceeded after retries');
}

5. Consider External Rate Limiters

For advanced scenarios, use nginx or API gateway:

# Nginx rate limiting
limit_req_zone $binary_remote_addr zone=api:10m rate=100r/s;

server {
  location /apps/ {
    limit_req zone=api burst=20;
    proxy_pass http://sockudo;
  }
}

Monitoring

Prometheus Metrics

# Rate limit exceeded count by app
sockudo_rate_limit_exceeded_total{app_id="my-app"} 142

# Current remaining tokens
sockudo_rate_limit_remaining{app_id="my-app"} 758

# Rate limit configuration
sockudo_rate_limit_max{app_id="my-app"} 1000

Logs

[WARN] Rate limit exceeded for app: my-app (limit: 1000/sec)
[INFO] Rate limiter initialized with driver: redis
[DEBUG] Rate limit check: app=my-app, remaining=742/1000

Troubleshooting

Rate Limits Not Enforced

Check 1: Is rate limiting enabled?

grep -A 2 "rate_limiter" config/config.json

Check 2: Are per-app limits configured?

grep "max_client_events_per_second" config/config.json

Check 3: Check logs for initialization

grep "rate limiter" sockudo.log

Legitimate Traffic Blocked

Symptom: Users reporting 429 errors during normal usage Solution: Increase per-app limit

{
  "apps": [{
    "id": "my-app",
    "max_client_events_per_second": 2000  // Increase from 1000
  }]
}

Multi-Node Limit Multiplication

Symptom: Effective limit is higher than configured (e.g., 3000 instead of 1000) Cause: Using memory driver with 3 nodes (1000 × 3 = 3000) Solution: Switch to Redis driver for shared limits

{
  "rate_limiter": {
    "driver": "redis"
  }
}

Redis Connection Issues

Symptom: Rate limiting not working with Redis driver Check Redis connection:

redis-cli -h localhost -p 6379 ping

Check Sockudo logs:

grep "redis" sockudo.log | grep -i error

Fallback: Use memory driver temporarily

{
  "rate_limiter": {
    "driver": "memory"  // Temporary fallback
  }
}

Migration Guide

Enabling Rate Limiting

1. Enable in configuration:

{
  "rate_limiter": {
    "enabled": true,
    "driver": "memory"
  }
}

2. Configure per-app limits:

{
  "apps": [{
    "max_client_events_per_second": 1000
  }]
}

3. Monitor for blocked requests:

grep "Rate limit exceeded" sockudo.log

4. Adjust limits based on usage:

{
  "max_client_events_per_second": 2000  // Increase if needed
}

Switching from Memory to Redis

1. Configure Redis connection:

{
  "database": {
    "redis": {
      "host": "localhost",
      "port": 6379
    }
  }
}

2. Update rate limiter driver:

{
  "rate_limiter": {
    "driver": "redis"
  }
}

3. Restart Sockudo:

systemctl restart sockudo

4. Verify Redis keys:

redis-cli keys "sockudo:rate_limit:*"

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

​Overview

​Quick Start

​Basic Configuration

​Environment Variable

​Configuration

​Global Settings

​Per-App Limits

​Rate Limiter Drivers

​Memory Driver (Default)

​Redis Driver

​Redis Cluster Driver

​None Driver

​Rate Limiting Behavior

​HTTP API Endpoints

​Rate Limit Algorithm

​Response Headers

​Rate Limit Exceeded

​Use Cases

​1. Preventing API Abuse

​2. Fair Resource Allocation

​3. Multi-Tenant SaaS

​4. Development vs Production

​Best Practices

​1. Set Appropriate Limits

​2. Use Redis for Multi-Node Deployments

​3. Monitor Rate Limit Metrics

​4. Implement Client-Side Backoff

​5. Consider External Rate Limiters

​Monitoring

​Prometheus Metrics

​Logs

​Troubleshooting

​Rate Limits Not Enforced

​Legitimate Traffic Blocked

​Multi-Node Limit Multiplication

​Redis Connection Issues

​Migration Guide

​Enabling Rate Limiting

​Switching from Memory to Redis

​Next Steps

Webhooks

Presence Channels

Build docs developers (and LLMs) love

Overview

Quick Start

Basic Configuration

Environment Variable

Configuration

Global Settings

Per-App Limits

Rate Limiter Drivers

Memory Driver (Default)

Redis Driver

Redis Cluster Driver

None Driver

Rate Limiting Behavior

HTTP API Endpoints

Rate Limit Algorithm

Response Headers

Rate Limit Exceeded

Use Cases

1. Preventing API Abuse

2. Fair Resource Allocation

3. Multi-Tenant SaaS

4. Development vs Production

Best Practices

1. Set Appropriate Limits

2. Use Redis for Multi-Node Deployments

3. Monitor Rate Limit Metrics

4. Implement Client-Side Backoff

5. Consider External Rate Limiters

Monitoring

Prometheus Metrics

Logs

Troubleshooting

Rate Limits Not Enforced

Legitimate Traffic Blocked

Multi-Node Limit Multiplication

Redis Connection Issues

Migration Guide

Enabling Rate Limiting

Switching from Memory to Redis

Next Steps