Sockudo

https://sockudo.io/guide
Admin
Sockudo is a high-performance WebSocket server built in Rust that provides Pusher protocol...
Tokens:96,169
Snippets:821
Trust Score:2.1
Update:8 months ago
Show doc for...
Tokens:
Raw
### Quick Start Sockudo with Docker

Source: https://sockudo.io/guide/getting-started

Clones the Sockudo repository, sets up environment variables, and starts Sockudo using Docker Compose for a rapid deployment. This is the recommended method for a quick setup.

```bash
# Clone the repository
git clone https://github.com/sockudo/sockudo.git
cd sockudo

# Copy environment variables template
cp .env.example .env
# Edit .env file if needed (optional for basic setup)

# Quick setup and start
make quick-start
# Or, using docker-compose directly:
# docker-compose up -d
```

--------------------------------

### Install Rust using Rustup

Source: https://sockudo.io/guide/getting-started

Installs or updates Rust to the latest stable version using the official rustup script. This is a prerequisite for building Sockudo from source.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update
```

--------------------------------

### Run Sockudo Server from Source Build

Source: https://sockudo.io/guide/getting-started

Executes the compiled Sockudo binary from the `target/release/` directory. This starts the server with default in-memory configurations.

```bash
./target/release/sockudo
```

--------------------------------

### Mixed Webhook Configuration Example

Source: https://sockudo.io/guide/configuration/webhooks

Demonstrates a mixed webhook setup with multiple configurations. This includes webhooks sent to external URLs with custom headers and authentication, as well as triggering a Lambda function with specific filters.

```json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhooks/general",
      "event_types": ["channel_occupied", "channel_vacated"],
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    },
    {
      "lambda_function": "handleClientEvents",
      "event_types": ["client_event"],
      "filter": {
        "channel_type": "presence"
      }
    },
    {
      "url": "https://analytics.example.com/events",
      "event_types": ["member_added", "member_removed"],
      "headers": {
        "X-Source": "sockudo"
      },
      "filter": {
        "channel_prefix": "presence-chat"
      }
    }
  ]
}
```

--------------------------------

### Test Sockudo with Pusher JavaScript Client

Source: https://sockudo.io/guide/getting-started

Utilizes the Pusher JavaScript client to interact with Sockudo, leveraging its Pusher protocol compatibility. This example shows how to instantiate the client, connect to the server, subscribe to a channel, and bind to events. It requires `pusher-js` to be installed.

```javascript
import Pusher from 'pusher-js';

const pusher = new Pusher('demo-key', {
    wsHost: 'localhost',
    wsPort: 6001,
    forceTLS: false,
    enabledTransports: ['ws']
});

const channel = pusher.subscribe('test-channel');
channel.bind('test-event', function(data) {
    console.log('Event received:', data);
});
```

--------------------------------

### Secret Management Examples

Source: https://sockudo.io/guide/deployment

This section provides bash examples for managing secrets using different tools. It demonstrates how to store sensitive information like database passwords and API secrets using HashiCorp Vault, AWS Secrets Manager, and Kubernetes secrets, ensuring secure handling of credentials.

```bash
# Using HashiCorp Vault
valt kv put secret/sockudo \
  mysql_password=secure_password \
  redis_password=secure_redis_password \
  app_secret=secure_app_secret

# Using AWS Secrets Manager
aws secretsmanager create-secret \
  --name "sockudo/production" \
  --description "Sockudo production secrets" \
  --secret-string '{"mysql_password":"secure_password","redis_password":"secure_redis_password"}'

# Using Kubernetes secrets
kubectl create secret generic sockudo-secrets \
  --from-literal=mysql-password=secure_password \
  --from-literal=redis-password=secure_redis_password
```

--------------------------------

### Sockudo SSL Configuration Example

Source: https://sockudo.io/guide/configuration/ssl

A JSON configuration snippet showing how to enable SSL and specify the paths to the certificate and key files for Sockudo.

```json
{
  "ssl": {
    "enabled": true,
    "cert_path": "/shared/ssl/cert.pem",
    "key_path": "/shared/ssl/key.pem"
  }
}
```

--------------------------------

### Test Sockudo API Endpoints with cURL

Source: https://sockudo.io/guide/getting-started

Demonstrates how to test Sockudo's HTTP API endpoints using cURL commands. It includes examples for retrieving server usage statistics, performing health checks on applications, and sending events to channels. Authentication might be required for certain endpoints in production environments.

```bash
# Get server usage
curl http://localhost:6001/usage

# Get app info (health check)
curl http://localhost:6001/up/demo-app

# Send an event to a channel (requires proper authentication for production)
curl -X POST "http://localhost:6001/apps/demo-app/events" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-event",
    "channels": ["test-channel"],
    "data": {"message": "Hello World"}
  }'
```

--------------------------------

### Install Sockudo Application with Systemd Service

Source: https://sockudo.io/guide/deployment

This bash script automates the installation of the Sockudo application. It creates a dedicated user and group, sets up necessary directories, copies the binary and configuration files, and installs a systemd service for managing the Sockudo process. Ensure you have sudo privileges to execute this script.

```bash
#!/bin/bash
# install-sockudo.sh

set -e

SOCKUDO_USER="sockudo"
SOCKUDO_GROUP="sockudo"
SOCKUDO_HOME="/opt/sockudo"
BINARY_PATH="./target/release/sockudo"
CONFIG_PATH="./config/config.json"

echo "Installing Sockudo..."

# Create user and group
if ! id "$SOCKUDO_USER" &>/dev/null;
    then
    sudo groupadd "$SOCKUDO_GROUP"
    sudo useradd -r -g "$SOCKUDO_GROUP" -d "$SOCKUDO_HOME" -s /sbin/nologin "$SOCKUDO_USER"
    echo "Created user $SOCKUDO_USER"
fi

# Create directories
sudo mkdir -p "$SOCKUDO_HOME"/{config,ssl,logs}
sudo chown -R "$SOCKUDO_USER:$SOCKUDO_GROUP" "$SOCKUDO_HOME"

# Install binary
sudo cp "$BINARY_PATH" "$SOCKUDO_HOME/"
sudo chown "$SOCKUDO_USER:$SOCKUDO_GROUP" "$SOCKUDO_HOME/sockudo"
sudo chmod +x "$SOCKUDO_HOME/sockudo"

# Install configuration
sudo cp "$CONFIG_PATH" "$SOCKUDO_HOME/config/"
sudo chown "$SOCKUDO_USER:$SOCKUDO_GROUP" "$SOCKUDO_HOME/config/config.json"

# Install systemd service
sudo cp sockudo.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable sockudo.service

echo "Installation complete!"
echo "Start the service with: sudo systemctl start sockudo"
echo "Check status with: sudo systemctl status sockudo"

```

--------------------------------

### Basic SSL Configuration Example for Sockudo

Source: https://sockudo.io/guide/configuration/ssl

A minimal configuration to enable SSL/TLS for Sockudo, providing only the essential certificate and key paths.

```json
{
  "ssl": {
    "enabled": true,
    "cert_path": "/etc/ssl/certs/sockudo.crt",
    "key_path": "/etc/ssl/private/sockudo.key"
  }
}
```

--------------------------------

### Cache Key Patterns Examples

Source: https://sockudo.io/guide/configuration/cache

This section provides examples of structured cache keys used by Sockudo, including a default prefix and specific keys for applications, channels, presence data, and users. These patterns help in organizing and retrieving cached data efficiently.

```text
{prefix}app:{app_id}
{prefix}channel:{app_id}:{channel_name}
{prefix}presence:{app_id}:{channel_name}
{prefix}user:{app_id}:{user_id}

Examples with default prefix:
sockudo_cache:app:demo-app
sockudo_cache:channel:demo-app:presence-chat
sockudo_cache:presence:demo-app:presence-chat
sockudo_cache:user:demo-app:user123
```

--------------------------------

### Make Sockudo Binary Executable

Source: https://sockudo.io/guide/getting-started

Provides the command to make the Sockudo binary executable on systems where it might not have execute permissions by default. This is a common step after downloading or compiling the binary to ensure it can be run.

```bash
chmod +x ./target/release/sockudo
```

--------------------------------

### Clone and Build Sockudo from Source

Source: https://sockudo.io/guide/getting-started

Clones the Sockudo repository from GitHub and compiles the project using Cargo. The `--release` flag is used for a production-optimized build.

```bash
# Clone the Repository
git clone https://github.com/sockudo/sockudo.git
cd sockudo

# Build the Project
cargo build --release
```

--------------------------------

### Start Sockudo Server

Source: https://sockudo.io/guide/performance-benchmarks

Command to start the Sockudo server in release mode for benchmarking.

```bash
cargo run --release
```

--------------------------------

### Example Resource Allocation (Bash)

Source: https://sockudo.io/guide/scaling

Provides an example of resource allocation guidelines for each instance, including CPU, memory, network bandwidth, and connection capacity. This helps in planning infrastructure requirements.

```bash
# Example resource allocation per instance
CPU: 1-2 cores
Memory: 512MB - 2GB
Network: 1Gbps
Connections: 5,000-50,000 per instance
```

--------------------------------

### Get Server Usage

Source: https://sockudo.io/guide/getting-started

Retrieves information about the current usage statistics of the Sockudo server.

```APIDOC
## GET /usage

### Description
Retrieves information about the current usage statistics of the Sockudo server.

### Method
GET

### Endpoint
/usage

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **body** (object) - An object containing server usage statistics.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Mixed Webhook Configuration

Source: https://sockudo.io/guide/configuration/webhooks

Example demonstrating a mixed configuration with multiple webhook endpoints and an AWS Lambda function.

```APIDOC
## Mixed Webhook Configuration

### Description
This configuration showcases a flexible setup with multiple webhooks. It includes webhooks sending data to external URLs with custom headers, and an integration with an AWS Lambda function, with specific event types and filters for each.

### Method
Not Applicable (Configuration)

### Endpoint
Not Applicable (Configuration)

### Parameters
#### Request Body
- **webhooks** (array) - Required - A list of webhook configurations.
  - **url** (string) - Required (if not using lambda_function) - The URL endpoint for the webhook.
  - **event_types** (array of strings) - Required - The types of events that will trigger this webhook.
  - **headers** (object) - Optional - Custom headers to include in the webhook request.
  - **filter** (object) - Optional - Criteria to filter which events trigger the webhook.
    - **channel_prefix** (string) - Optional - Only trigger webhooks for channels starting with this prefix.
    - **channel_type** (string) - Optional - Only trigger webhooks for channels of this type (e.g., 'presence').
  - **lambda_function** (string) - Required (if not using url) - The name of the AWS Lambda function to invoke.

### Request Example
```json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhooks/general",
      "event_types": ["channel_occupied", "channel_vacated"],
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    },
    {
      "lambda_function": "handleClientEvents",
      "event_types": ["client_event"],
      "filter": {
        "channel_type": "presence"
      }
    },
    {
      "url": "https://analytics.example.com/events",
      "event_types": ["member_added", "member_removed"],
      "headers": {
        "X-Source": "sockudo"
      },
      "filter": {
        "channel_prefix": "presence-chat"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
Not Applicable (Configuration)

#### Response Example
Not Applicable (Configuration)
```

--------------------------------

### Configure Sockudo Adapter Driver and Redis Settings (Environment Variables)

Source: https://sockudo.io/guide/configuration/adapter

This example demonstrates setting the adapter driver to 'redis' using environment variables. It also shows how to specify the Redis connection URL, which the adapter will use for communication.

```bash
export ADAPTER_DRIVER=redis
export REDIS_URL=redis://redis:6379/0
```

--------------------------------

### Configure Sockudo Queue with Redis Driver (Environment Variables)

Source: https://sockudo.io/guide/configuration/queue

This example shows how to set up the queue driver and Redis connection using environment variables. It includes setting the `QUEUE_DRIVER` to 'redis' and providing the Redis connection URL.

```bash
export QUEUE_DRIVER=redis
export REDIS_URL=redis://redis:6379/0
```

--------------------------------

### Install and Use Certbot for Let's Encrypt Certificates

Source: https://sockudo.io/guide/configuration/ssl

Installs Certbot, obtains an SSL certificate using the standalone HTTP challenge, and configures automatic renewal via crontab. Assumes a Debian-based system for apt-get.

```bash
# Install Certbot
sudo apt-get update
sudo apt-get install certbot

# Obtain certificate (HTTP challenge)
sudo certbot certonly --standalone -d yourdomain.com

# Certificate files will be located at:
# /etc/letsencrypt/live/yourdomain.com/fullchain.pem
# /etc/letsencrypt/live/yourdomain.com/privkey.pem

# Add to crontab
sudo crontab -e

# Add line for automatic renewal (runs twice daily)
0 12 * * * /usr/bin/certbot renew --quiet
```

--------------------------------

### Example Sockudo Server Options Configuration (JSON)

Source: https://sockudo.io/guide/configuration

Provides an example of the JSON structure for configuring core server settings in Sockudo. This includes host, port, debug mode, and various operational parameters.

```json
{
  "debug": false,
  "host": "0.0.0.0",
  "port": 6001,
  "mode": "production",
  "path_prefix": "/",
  "shutdown_grace_period": 10,
  "websocket_max_payload_kb": 64,
  "user_authentication_timeout": 3600
}

```

--------------------------------

### Configure SQS Queue with Environment Variables

Source: https://sockudo.io/guide/configuration/queue

Example of configuring an SQS queue using environment variables. This includes setting the driver, region, queue URL prefix, and AWS credentials.

```bash
export QUEUE_DRIVER=sqs
export AWS_REGION=eu-west-1
export SQS_QUEUE_URL_PREFIX="https://sqs.eu-west-1.amazonaws.com/YOUR_ACCOUNT_ID/"
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
```

--------------------------------

### Cross-Compile Sockudo for Different Architectures (Bash)

Source: https://sockudo.io/guide/deployment

Demonstrates how to cross-compile Sockudo for different target architectures, such as `x86_64-unknown-linux-musl` for static linking and `aarch64-unknown-linux-gnu` for ARM64. This involves installing the target using `rustup` and then building with the specified target flag.

```bash
# Install target
rustup target add x86_64-unknown-linux-musl

# Build for musl (static linking)
cargo build --release --target x86_64-unknown-linux-musl

# For ARM64 (e.g., AWS Graviton)
rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu
```

--------------------------------

### Redis Monitoring Commands

Source: https://sockudo.io/guide/configuration/cache

This example shows essential `redis-cli` commands for monitoring Redis cache performance. It includes commands to retrieve memory usage statistics and general cache statistics.

```bash
# Get cache statistics
redis-cli info memory
redis-cli info stats
```

--------------------------------

### Configure Sockudo Redis Queue with Environment Variables

Source: https://sockudo.io/guide/configuration/queue

This example demonstrates setting Redis queue configurations via environment variables. It includes specifying the driver, a custom prefix, a URL override for the Redis connection, and the connection pool size.

```bash
QUEUE_DRIVER=redis
QUEUE_REDIS_PREFIX="sockudo_jobs:"
QUEUE_REDIS_URL="redis://my-queue-redis:6379/2"
REDIS_CONNECTION_POOL_SIZE=10
```

--------------------------------

### Disaster Recovery Script using Bash

Source: https://sockudo.io/guide/deployment

This bash script outlines the steps for disaster recovery, including deploying infrastructure, restoring configuration and database backups, and starting services. It assumes backups are available in specified directories. Dependencies include `tar`, `gunzip`, `mysql`, and `systemctl`.

```bash
#!/bin/bash
# disaster-recovery.sh

# 1. Deploy new infrastructure
# 2. Restore configuration
cd /backup/sockudo-config
latest_config=$(ls -t config_*.tar.gz | head -1)
tar -xzf "$latest_config" -C /

# 3. Restore database
cd /backup/sockudo
latest_db=$(ls -t sockudo_*.sql.gz | head -1)
gunzip -c "$latest_db" | mysql -h mysql.internal -u sockudo -p sockudo

# 4. Start services
systemctl start sockudo
systemctl enable sockudo

# 5. Verify recovery
curl http://localhost:6001/usage

```

--------------------------------

### Performance Troubleshooting: Message Flow Analysis

Source: https://sockudo.io/guide/troubleshooting

Provides bash commands to monitor message flow metrics and check for message bottlenecks, including an example for Redis adapter.

```bash
# Monitor metrics for message flow
curl http://localhost:9601/metrics | grep -E "(messages_sent|messages_received)"

# Check for message bottlenecks
redis-cli MONITOR | grep sockudo  # If using Redis adapter
```

--------------------------------

### Complete Sockudo Server Configuration Example

Source: https://sockudo.io/guide/configuration/server-options

This comprehensive JSON example shows a complete server configuration for Sockudo, integrating settings for debugging, host, port, mode, SSL, CORS, and instance.

```json
{
  "debug": false,
  "host": "0.0.0.0",
  "port": 6001,
  "mode": "production",
  "path_prefix": "/",
  "shutdown_grace_period": 30,
  "user_authentication_timeout": 3600,
  "websocket_max_payload_kb": 64,
  
  "ssl": {
    "enabled": true,
    "cert_path": "/etc/ssl/certs/sockudo.crt",
    "key_path": "/etc/ssl/private/sockudo.key",
    "redirect_http": true,
    "http_port": 80
  },
  
  "cors": {
    "credentials": true,
    "origin": ["https://myapp.com"],
    "methods": ["GET", "POST", "OPTIONS"],
    "allowed_headers": ["Authorization", "Content-Type", "X-Requested-With", "Accept"]
  },
  
  "instance": {
    "process_id": "sockudo-prod-01"
  }
}
```

--------------------------------

### Pull Sockudo Docker Image

Source: https://sockudo.io/guide/getting-started

Pulls the latest pre-built Sockudo Docker image from the Docker Hub registry. This allows running Sockudo without building it from source.

```bash
docker pull sockudo/sockudo:latest
```

--------------------------------

### Sockudo SSL Configuration with HTTP Redirect

Source: https://sockudo.io/guide/configuration/ssl

This example shows how to enable SSL/TLS for Sockudo and configure it to redirect all incoming HTTP traffic to HTTPS on a specified port.

```json
{
  "ssl": {
    "enabled": true,
    "cert_path": "/etc/letsencrypt/live/yourdomain.com/fullchain.pem",
    "key_path": "/etc/letsencrypt/live/yourdomain.com/privkey.pem",
    "redirect_http": true,
    "http_port": 80
  }
}
```

--------------------------------

### Configure Sockudo with Environment Variables

Source: https://sockudo.io/guide/getting-started

Sets up Sockudo configuration using environment variables, typically defined in a `.env` file. This method allows for flexible configuration of basic settings, drivers, default app details, and metrics. Each variable corresponds to a setting in the JSON configuration.

```bash
# Basic Settings
HOST=0.0.0.0
PORT=6001
DEBUG=true

# Drivers
ADAPTER_DRIVER=local
APP_MANAGER_DRIVER=memory
CACHE_DRIVER=memory
QUEUE_DRIVER=memory

# Default App (if not using persistent app manager)
SOCKUDO_DEFAULT_APP_ID=my-app
SOCKUDO_DEFAULT_APP_KEY=my-key
SOCKUDO_DEFAULT_APP_SECRET=my-secret
SOCKUDO_ENABLE_CLIENT_MESSAGES=true

# Metrics
METRICS_ENABLED=true
METRICS_PORT=9601
```

--------------------------------

### Test Sockudo with Basic WebSocket Client

Source: https://sockudo.io/guide/getting-started

Connects to a Sockudo server using a basic JavaScript WebSocket client. It demonstrates how to establish a connection, subscribe to a channel, and handle incoming messages. This is useful for initial testing of the WebSocket functionality.

```javascript
// Connect to Sockudo
const ws = new WebSocket('ws://localhost:6001/app/demo-key');

ws.onopen = function() {
    console.log('Connected to Sockudo');
    
    // Subscribe to a public channel
    ws.send(JSON.stringify({
        event: 'pusher:subscribe',
        data: {
            channel: 'test-channel'
        }
    }));
};

ws.onmessage = function(event) {
    console.log('Message received:', JSON.parse(event.data));
};
```

--------------------------------

### Production Environment Configuration (.env)

Source: https://sockudo.io/guide/deployment

This example `.env` file demonstrates how to configure production environment variables for Sockudo.io. It includes settings for database credentials, SSL, CORS, connection pooling, monitoring, and instance identification. These variables are typically used by the Docker Compose file or Kubernetes deployments.

```bash
# .env.production
MYSQ_ROOT_PASSWORD=secure_root_password_here
MYSQ_PASSWORD=secure_sockudo_password_here
SSL_ENABLED=true

# Redis Configuration
REDIS_PASSWORD=secure_redis_password

# Security
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
CORS_CREDENTIALS=true

# Performance
DATABASE_CONNECTION_POOL_SIZE=15
REDIS_CONNECTION_POOL_SIZE=10

# Monitoring
METRICS_ENABLED=true
LOG_LEVEL=info

# Instance identification
INSTANCE_PROCESS_ID=sockudo-prod-01

```

--------------------------------

### Example Sockudo App Manager Configuration (JSON)

Source: https://sockudo.io/guide/configuration

Demonstrates the JSON configuration for Sockudo's App Manager, responsible for managing application credentials and settings. This example uses the 'memory' driver and includes settings for application definitions and caching.

```json
{
  "app_manager": {
    "driver": "memory",
    "array": {
      "apps": [
        {
          "id": "app1",
          "key": "key1",
          "secret": "secret1",
          "max_connections": 1000,
          "enable_client_messages": true,
          "enabled": true,
          "max_client_events_per_second": 10000,
          "max_backend_events_per_second": null,
          "max_read_requests_per_second": null,
          "max_presence_members_per_channel": null,
          "max_presence_member_size_in_kb": null,
          "max_channel_name_length": null,
          "max_event_channels_at_once": null,
          "max_event_name_length": null,
          "max_event_payload_in_kb": null,
          "max_event_batch_size": null,
          "enable_user_authentication": null,
          "webhooks": null,
          "enable_watchlist_events": null,
          "allowed_origins": [
            "https://app.example.com",
            "*.staging.example.com",
            "localhost:3000"
          ]
        }
      ]
    },
    "cache": {
      "enabled": true,
      "ttl": 300
    }
  }
}

```

--------------------------------

### Configure Sockudo Queue with Redis Driver (JSON)

Source: https://sockudo.io/guide/configuration/queue

This example demonstrates how to configure the main queue settings in `config.json` to use Redis as the driver. It specifies the driver type and provides Redis-specific options such as concurrency, key prefix, and cluster mode.

```json
{
  "queue": {
    "driver": "redis",
    "redis": {
      "concurrency": 5,
      "prefix": "sockudo_queue:",
      "cluster_mode": false
    }
  }
}
```

--------------------------------

### Application Configuration Caching Example in JSON

Source: https://sockudo.io/guide/configuration/cache

This JSON snippet illustrates enabling caching for the application manager. It specifies that caching is enabled and sets a Time-To-Live (TTL) of 300 seconds for cached application configurations.

```json
{
  "app_manager": {
    "driver": "mysql",
    "cache": {
      "enabled": true,
      "ttl": 300
    }
  }
}
```

--------------------------------

### Configure Sockudo with JSON File

Source: https://sockudo.io/guide/getting-started

Defines the basic configuration for Sockudo using a `config.json` file. This includes settings for debugging, host, port, application manager, adapter, cache, and metrics. The `app_manager` section specifies the driver and details for managing applications.

```json
{
  "debug": true,
  "host": "0.0.0.0",
  "port": 6001,
  "app_manager": {
    "driver": "memory",
    "array": {
      "apps": [
        {
          "id": "my-first-app",
          "key": "app-key-123",
          "secret": "app-secret-xyz",
          "max_connections": 100,
          "enable_client_messages": true,
          "enabled": true,
          "max_client_events_per_second": 10
        }
      ]
    }
  },
  "adapter": {
    "driver": "local"
  },
  "cache": {
    "driver": "memory"
  },
  "metrics": {
    "enabled": true,
    "port": 9601
  }
}
```

--------------------------------

### Configure Redis Cluster Queue with Environment Variables

Source: https://sockudo.io/guide/configuration/queue

Example of configuring a Redis Cluster queue using environment variables. This method allows for dynamic configuration without modifying JSON files.

```bash
export QUEUE_DRIVER=redis-cluster
export REDIS_CLUSTER_NODES="redis://node1:7000,redis://node2:7000,redis://node3:7000"
export REDIS_CLUSTER_QUEUE_CONCURRENCY=8
export REDIS_CLUSTER_QUEUE_PREFIX="production_queue:"
```

--------------------------------

### Configure Sockudo Redis Cluster Queue with Environment Variables

Source: https://sockudo.io/guide/configuration/queue

This example shows how to configure Sockudo's queue for Redis Cluster using environment variables. It sets the driver, concurrency, prefix, and provides a comma-separated list of Redis cluster node URLs.

```bash
QUEUE_DRIVER=redis-cluster
REDIS_CLUSTER_QUEUE_CONCURRENCY=5
REDIS_CLUSTER_QUEUE_PREFIX="sockudo_queue:"
REDIS_CLUSTER_NODES="redis://node1:6379,redis://node2:6379"
```

--------------------------------

### Configure SQS Queue with JSON

Source: https://sockudo.io/guide/configuration/queue

Example of configuring an SQS queue using a JSON configuration file. This covers essential settings like region, queue URL prefix, visibility timeout, and concurrency.

```json
{
  "queue": {
    "driver": "sqs",
    "sqs": {
      "region": "eu-west-1",
      "queue_url_prefix": "https://sqs.eu-west-1.amazonaws.com/YOUR_ACCOUNT_ID/",
      "visibility_timeout": 60,
      "concurrency": 3,
      "fifo": false,
      "max_messages": 10,
      "wait_time_seconds": 5
    }
  }
}
```

--------------------------------

### Redis Cache Environment Variables

Source: https://sockudo.io/guide/configuration/cache

This example shows how to configure Redis cache settings using environment variables. It covers the cache driver, Redis prefix, and URL override, along with a fallback Redis URL.

```bash
CACHE_DRIVER=redis
CACHE_REDIS_PREFIX="myapp_cache:"
CACHE_REDIS_URL="redis://my-cache-redis:6379/1"
REDIS_URL="redis://redis:6379/0"  # Fallback if url_override not set
```

--------------------------------

### Get App Info (Health Check)

Source: https://sockudo.io/guide/getting-started

Performs a health check for a specific application registered with Sockudo.

```APIDOC
## GET /up/{appId}

### Description
Performs a health check for a specific application registered with Sockudo.

### Method
GET

### Endpoint
/up/{appId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the application.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **body** (object) - An object indicating the health status of the application.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Configuration Example: Security-Conscious Setup

Source: https://sockudo.io/guide/configuration/origin-validation

This JSON configuration provides a security-focused `allowed_origins` setup. It prioritizes HTTPS for production and admin interfaces while allowing any protocol for local development on a specific port.

```json
{
  "id": "secure-app",
  "allowed_origins": [
    "https://app.example.com",    // HTTPS only for production
    "https://admin.example.com",  // HTTPS only for admin
    "localhost:3000"              // Any protocol for local dev
  ]
}
```

--------------------------------

### AWS Lambda Webhook Configuration

Source: https://sockudo.io/guide/configuration/webhooks

Example configuration for sending webhook events to an AWS Lambda function.

```APIDOC
## AWS Lambda Webhook Configuration

### Description
This configuration specifies webhook events to be sent to an AWS Lambda function. It includes the Lambda function name, region, invocation type, event types to trigger the webhook, and optional filtering based on channel prefix.

### Method
Not Applicable (Configuration)

### Endpoint
Not Applicable (Configuration)

### Parameters
#### Request Body
- **webhooks** (array) - Required - A list of webhook configurations.
  - **lambda** (object) - Required - Configuration for AWS Lambda integration.
    - **function_name** (string) - Required - The name of the AWS Lambda function.
    - **region** (string) - Required - The AWS region where the Lambda function is deployed.
    - **invocation_type** (string) - Optional - The invocation type for the Lambda function (e.g., 'Event', 'RequestResponse'). Defaults to 'Event'.
  - **event_types** (array of strings) - Required - The types of events that will trigger this webhook.
  - **filter** (object) - Optional - Criteria to filter which events trigger the webhook.
    - **channel_prefix** (string) - Optional - Only trigger webhooks for channels starting with this prefix.

### Request Example
```json
{
  "webhooks": [
    {
      "lambda": {
        "function_name": "sockudoPresenceHandler",
        "region": "us-east-1",
        "invocation_type": "Event"
      },
      "event_types": ["member_added", "member_removed"],
      "filter": {
        "channel_prefix": "presence-"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
Not Applicable (Configuration)

#### Response Example
Not Applicable (Configuration)
```

--------------------------------

### Example Sockudo App Configuration (JSON)

Source: https://sockudo.io/guide/configuration/app-manager

This JSON snippet demonstrates a typical configuration for a Sockudo application, including settings for app ID, keys, various limits (connections, events per second, payload size, etc.), authentication, allowed origins, and webhooks.

```json
{
  "app_manager": {
    "driver": "memory",
    "array": {
      "apps": [
        {
          "id": "demo-app",
          "key": "demo-key",
          "secret": "demo-secret-shhh",
          "max_connections": "1000",
          "enable_client_messages": true,
          "enabled": true,
          "max_backend_events_per_second": null,
          "max_client_events_per_second": "10000",
          "max_read_requests_per_second": null,
          "max_presence_members_per_channel": 50,
          "max_presence_member_size_in_kb": 2,
          "max_channel_name_length": 200,
          "max_event_channels_at_once": 100,
          "max_event_name_length": 200,
          "max_event_payload_in_kb": 100,
          "max_event_batch_size": 10,
          "enable_user_authentication": true,
          "enable_watchlist_events": false,
          "allowed_origins": [
            "https://myapp.com",
            "https://admin.myapp.com",
            "localhost:3000"
          ],
          "webhooks": [
            {
              "url": "https://myapplication.com/webhooks/sockudo",
              "event_types": ["channel_occupied", "channel_vacated"]
            }
          ]
        },
        {
          "id": "another-app",
          "key": "another-key",
          "secret": "another-secret-super-safe",
          "max_connections": "500",
          "enable_client_messages": false,
          "enabled": true,
          "max_client_events_per_second": "1000"
        }
      ]
    },
    "cache": {
      "enabled": true,
      "ttl": 600
    }
  }
}
```

--------------------------------

### Send Event to Channel

Source: https://sockudo.io/guide/getting-started

Broadcasts an event to specified channels within an application. Requires proper authentication in production environments.

```APIDOC
## POST /apps/{appId}/events

### Description
Broadcasts an event to specified channels within an application. Requires proper authentication in production environments.

### Method
POST

### Endpoint
/apps/{appId}/events

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the application.

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the event to broadcast.
- **channels** (array of strings) - Required - A list of channel names to send the event to.
- **data** (object) - Optional - The payload of the event.

### Request Example
```json
{
  "name": "test-event",
  "channels": ["test-channel"],
  "data": {"message": "Hello World"}
}
```

### Response
#### Success Response (200)
- **body** (object) - An object confirming the event was sent.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Example Sockudo Adapter Configuration (JSON)

Source: https://sockudo.io/guide/configuration

Illustrates the JSON configuration for Sockudo's adapter, which handles communication and scaling across instances. It shows settings for different drivers like local, Redis, and NATS.

```json
{
  "adapter": {
    "driver": "local",
    "redis": {
      "requests_timeout": 5000,
      "prefix": "sockudo_adapter:",
      "cluster_mode": false,
      "redis_pub_options": {},
      "redis_sub_options": {}
    },
    "cluster": {
      "nodes": [],
      "prefix": "sockudo_cluster:",
      "request_timeout_ms": 5000,
      "use_connection_manager": true
    },
    "nats": {
      "servers": ["nats://nats:4222"],
      "prefix": "sockudo_nats:",
      "request_timeout_ms": 5000,
      "connection_timeout_ms": 5000
    }
  }
}

```

--------------------------------

### Webhook Filtering by Channel Type

Source: https://sockudo.io/guide/webhooks

Configuration example for filtering webhooks based on channel type. This setup directs 'presence' events to the specified URL.

```json
{
  "url": "https://yourapi.com/webhooks/presence",
  "event_types": ["member_added", "member_removed"],
  "filter": {
    "channel_type": "presence"
  }
}
```

--------------------------------

### Prometheus Alert Example for Sockudo Errors

Source: https://sockudo.io/guide/troubleshooting

A Prometheus alert rule configuration to detect a high error rate in Sockudo, with a specified duration and annotation for summary.

```yaml
# Prometheus alert example
- alert: SockudoHighErrorRate
  expr: rate(sockudo_errors_total[5m]) > 10
  for: 2m
  annotations:
    summary: "High error rate detected"
```

--------------------------------

### Configure App Manager with Environment Variables

Source: https://sockudo.io/guide/configuration/app-manager

This Bash script demonstrates how to configure the Sockudo App Manager using environment variables. It covers settings for the driver, default app credentials, and database connection parameters for MySQL, PostgreSQL, and DynamoDB.

```bash
# App Manager Driver
APP_MANAGER_DRIVER=memory

# Default App Settings (used when no apps are configured)
SOCKUDO_DEFAULT_APP_ID=demo-app
SOCKUDO_DEFAULT_APP_KEY=demo-key
SOCKUDO_DEFAULT_APP_SECRET=demo-secret
SOCKUDO_ENABLE_CLIENT_MESSAGES=true

# Database Settings (for database-backed app managers)
DATABASE_MYSQL_HOST=mysql
DATABASE_MYSQL_USER=sockudo
DATABASE_MYSQL_PASSWORD=your_password
DATABASE_MYSQL_DATABASE=sockudo

# PostgreSQL
DATABASE_POSTGRES_HOST=postgres
DATABASE_POSTGRES_USER=sockudo
DATABASE_POSTGRES_PASSWORD=your_password
DATABASE_POSTGRES_DATABASE=sockudo

# DynamoDB
AWS_REGION=us-east-1
```

--------------------------------

### Troubleshooting Sockudo.io Server Startup and SSL

Source: https://sockudo.io/guide/configuration/server-options

This Bash snippet provides commands to check if Sockudo.io is listening on its port and to verify SSL certificate validity. Useful for diagnosing server startup and SSL configuration issues.

```bash
# Check if Sockudo is listening
netstat -tuln | grep 6001

# Verify SSL certificate validity
openssl x509 -in cert.pem -text -noout
```

--------------------------------

### Webhook Filtering by Channel Prefix

Source: https://sockudo.io/guide/webhooks

Example JSON for filtering webhooks based on a channel prefix. This configuration sends events from channels starting with 'chat-' to the designated webhook URL.

```json
{
  "url": "https://yourapi.com/webhooks/chat",
  "event_types": ["channel_occupied", "channel_vacated"],
  "filter": {
    "channel_prefix": "chat-"
  }
}
```

--------------------------------

### Sockudo SSL Configuration with Client Certificate Authentication

Source: https://sockudo.io/guide/configuration/ssl

This example shows how to configure Sockudo for SSL/TLS with client certificate authentication (mTLS) by providing a CA certificate path.

```json
{
  "ssl": {
    "enabled": true,
    "cert_path": "/etc/ssl/certs/sockudo.crt",
    "key_path": "/etc/ssl/private/sockudo.key",
    "ca_path": "/etc/ssl/certs/ca-bundle.crt"
  }
}
```

--------------------------------

### Configure FIFO SQS Queue with JSON

Source: https://sockudo.io/guide/configuration/queue

Example of configuring a FIFO SQS queue using JSON. This highlights the `fifo` and `message_group_id` parameters required for FIFO queues.

```json
{
  "queue": {
    "driver": "sqs",
    "sqs": {
      "region": "us-east-1",
      "queue_url_prefix": "https://sqs.us-east-1.amazonaws.com/123456789012/",
      "fifo": true,
      "message_group_id": "sockudo-group",
      "visibility_timeout": 30,
      "concurrency": 5
    }
  }
}
```

--------------------------------

### Monitor Redis Configuration and Operations

Source: https://sockudo.io/guide/troubleshooting

These commands are used to inspect and monitor Redis. `CONFIG GET '*'` retrieves all configuration parameters, while `MONITOR` streams real-time commands being executed on the Redis server.

```bash
# Check Redis configuration
redis-cli CONFIG GET '*'

# Monitor Redis operations
redis-cli MONITOR
```

--------------------------------

### Configuration Example: Development Environment

Source: https://sockudo.io/guide/configuration/origin-validation

This JSON configuration shows typical `allowed_origins` for a development setup. It includes localhost entries with specific ports, allowing connections via both HTTP and HTTPS.

```json
{
  "id": "dev-app", 
  "allowed_origins": [
    "localhost:3000",             // Matches both protocols
    "localhost:3001",             // Matches both protocols
    "127.0.0.1:8080"              // Matches both protocols
  ]
}
```

--------------------------------

### Production Dockerfile for Sockudo (Dockerfile)

Source: https://sockudo.io/guide/deployment

An optimized Dockerfile for Sockudo production deployments using a multi-stage build. It first builds the release binary in a Rust environment and then copies it to a minimal Debian slim image for a smaller final image size. Includes runtime dependencies, user creation, port exposure, and health checks.

```dockerfile
# Multi-stage build for optimized production image
FROM rust:1.75-slim AS builder

# Install build dependencies
RUN apt-get update && apt-get install -y \
    pkg-config \
    libssl-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /usr/src/sockudo

# Copy source code
COPY . .

# Build release binary
RUN cargo build --release

# Runtime stage
FROM debian:bullseye-slim

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN groupadd --system sockudo && \
    useradd --system --no-log-init -g sockudo sockudo

# Create directories
RUN mkdir -p /app/config /app/ssl /app/logs && \
    chown -R sockudo:sockudo /app

WORKDIR /app

# Copy binary from builder stage
COPY --from=builder /usr/src/sockudo/target/release/sockudo .
COPY --from=builder /usr/src/sockudo/config/config.json ./config/

# Set ownership and permissions
RUN chown sockudo:sockudo ./sockudo && \
    chmod +x ./sockudo

# Switch to non-root user
USER sockudo

# Expose ports
EXPOSE 6001 9601

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD curl -f http://localhost:6001/usage || exit 1

# Default command
CMD ["./sockudo", "--config=./config/config.json"]
```

--------------------------------

### Backup Database and Configuration using Bash

Source: https://sockudo.io/guide/deployment

This script automates the backup of MySQL databases and Redis, as well as application configurations and SSL certificates. It creates timestamped archives and cleans up old backups. Dependencies include `mysqldump`, `gzip`, `redis-cli`, `find`, `tar`, and standard shell utilities.

```bash
#!/bin/bash
# backup-database.sh

BACKUP_DIR="/backup/sockudo"
DATE=$(date +%Y%m%d_%H%M%S)
MYSQL_HOST="mysql.internal"
MYSQL_USER="backup_user"
MYSQL_PASSWORD="backup_password"
DATABASE="sockudo"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# MySQL backup
mysqldump -h "$MYSQL_HOST" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" \
  --single-transaction --routines --triggers "$DATABASE" | \
  gzip > "$BACKUP_DIR/sockudo_${DATE}.sql.gz"

# Redis backup (if using Redis for app manager)
redis-cli --rdb "$BACKUP_DIR/redis_${DATE}.rdb"

# Cleanup old backups (keep 30 days)
find "$BACKUP_DIR" -type f -mtime +30 -delete

echo "Backup completed: $BACKUP_DIR/sockudo_${DATE}.sql.gz"

```

```bash
#!/bin/bash
# backup-config.sh

BACKUP_DIR="/backup/sockudo-config"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Backup configuration
tar -czf "$BACKUP_DIR/config_${DATE}.tar.gz" \
  /opt/sockudo/config/ \
  /etc/systemd/system/sockudo.service \
  /etc/nginx/sites-available/sockudo

# Backup SSL certificates
tar -czf "$BACKUP_DIR/ssl_${DATE}.tar.gz" \
  /etc/ssl/certs/sockudo.* \
  /etc/ssl/private/sockudo.*

echo "Configuration backup completed"

```

--------------------------------

### Local Webhook Testing with ngrok

Source: https://sockudo.io/guide/webhooks

Bash commands to set up local webhook testing using ngrok. It involves starting a local webhook server (e.g., Node.js) and then exposing it to the internet via ngrok. The ngrok URL can then be configured in your webhook settings.

```bash
# Start your local webhook server
node webhook-server.js  # Running on port 3000

# In another terminal, expose it via ngrok
ngrok http 3000

# Use the ngrok URL in your webhook configuration

```

--------------------------------

### Configure Primary Cache Driver (JSON)

Source: https://sockudo.io/guide/configuration/cache

Specifies the backend driver for the primary caching system. This example sets the driver to 'redis' and includes Redis-specific configuration like a key prefix.

```json
{
  "cache": {
    "driver": "redis",
    "redis": {
      "prefix": "sockudo_cache:",
      "cluster_mode": false
    }
  }
}
```

--------------------------------

### Configure Redis Cluster Queue with JSON

Source: https://sockudo.io/guide/configuration/queue

Example of configuring a Redis Cluster queue using a JSON configuration file. This includes setting the driver, nodes, concurrency, prefix, and request timeout.

```json
{
  "queue": {
    "driver": "redis-cluster",
    "redis_cluster": {
      "nodes": [
        "redis://redis-cluster-node-1:7000",
        "redis://redis-cluster-node-2:7000",
        "redis://redis-cluster-node-3:7000"
      ],
      "concurrency": 8,
      "prefix": "production_queue:",
      "request_timeout_ms": 10000
    }
  }
}
```

--------------------------------

### Check Instance Communication with Adapter

Source: https://sockudo.io/guide/troubleshooting

This snippet illustrates how to verify that individual Sockudo instances can communicate with the adapter. It provides example commands for testing connectivity to a Redis adapter and a NATS adapter from within a Sockudo instance.

```bash
# Check if instances can reach adapter
# From each Sockudo instance:
redis-cli -h adapter-host ping  # For Redis adapter
nats-pub -s nats://nats-host:4222 test "message"  # For NATS adapter
```

--------------------------------

### Environment Variables for Rate Limiter Configuration

Source: https://sockudo.io/guide/configuration/rate-limiter

This example shows how to configure Sockudo's rate limiter using environment variables. It covers enabling the feature, setting the driver, and configuring specific rate limits for API and WebSocket requests. These variables provide an alternative to direct JSON configuration.

```bash
RATE_LIMITER_ENABLED=true
RATE_LIMITER_DRIVER=redis
RATE_LIMITER_API_MAX_REQUESTS=100
RATE_LIMITER_API_WINDOW_SECONDS=60
RATE_LIMITER_WEBSOCKET_MAX_REQUESTS=20
RATE_LIMITER_WEBSOCKET_WINDOW_SECONDS=60
```

--------------------------------

### Channel Information Caching Example in JSON

Source: https://sockudo.io/guide/configuration/cache

This JSON configuration sets a cache TTL for channel limits. A TTL of 3600 seconds (1 hour) is specified, indicating how long channel metadata should be cached.

```json
{
  "channel_limits": {
    "cache_ttl": 3600
  }
}
```
Tokens:
Raw