rushsocket docs

// installationInstallation

Quick Install (Recommended)

One command — downloads the latest pre-built binary, installs it, sets up config, and enables the systemd service:

To install a specific version:

Pre-built binaries are available for x86_64 and aarch64 Linux. No Rust toolchain required.

Build from Source

For unsupported architectures or custom builds:

Systemd (Linux)

The install script automatically sets up systemd with Type=notify for reliable readiness signaling. To manage the service:

Uninstall

To uninstall (stops service, removes binary and service file):

To also remove the config directory (/etc/rushsocket):

The install script will:

• Download the correct binary for your architecture (or build from source)
• Install it to /usr/local/bin/rushsocket
• Create a default config at /etc/rushsocket/config.toml (preserves existing)
• Register and enable the systemd service

// configurationConfiguration

Running rushsocket without flags uses built-in defaults (app key: rushsocket-key, secret: rushsocket-secret). Use --config to load a custom config file.

Full Configuration Reference

Configuration Option Reference

Server Options

Connection Lifecycle

Memory & Cache

Per-App Options

// cliCLI Usage

Examples:

// apiHTTP REST API

rushsocket exposes a Pusher-compatible HTTP REST API on the main port (6001 by default). All endpoints use HMAC-SHA256 authentication, identical to the Pusher HTTP API.

Authentication

All requests must include query parameters: auth_key, auth_timestamp, auth_version, auth_signature, and body_md5 (for POST requests with a body). The signature is computed as:

POST requests with a body_md5 query parameter are verified — if the MD5 hash of the request body does not match, the request is rejected with 400 Bad Request.

Trigger an Event

Any existing Pusher server SDK works out of the box — just point it at your rushsocket host.

// webhooksWebhooks

rushsocket sends Pusher-compatible webhook notifications to your server when events occur. Configure a webhook_url per app to receive them.

Delivery

• Events are batched by the webhook_batch_ms interval (default: 1000ms) and sent as a single POST request
• Each request is signed with HMAC-SHA256 using the app's secret
• Failed deliveries are retried up to 3 times with exponential backoff (2s, 4s, 8s)
• Webhook delivery is non-blocking — it never slows down the WebSocket hot path

Headers

Payload Format

Event Types

Channel Existence Events

{
  "name": "channel_occupied",
  "channel": "my-channel"
}

{
  "name": "channel_vacated",
  "channel": "my-channel"
}

In Redis cluster mode, these are deduplicated globally — channel_occupied fires only once across all nodes (via Redis SETNX), and channel_vacated fires only when no node has any subscribers (verified with a real-time cross-node query).

Cache Channel Events

{
  "name": "cache_miss",
  "channel": "cache-my-channel"
}

Presence Events

{
  "name": "member_added",
  "channel": "presence-room",
  "user_id": "user-42"
}

{
  "name": "member_removed",
  "channel": "presence-room",
  "user_id": "user-42"
}

In Redis cluster mode, presence state is stored globally in Redis Hashes. A user is considered "removed" only when they have no sockets on any node.

Client Events

{
  "name": "client_event",
  "channel": "private-chat",
  "event": "client-typing",
  "data": "...",
  "socket_id": "1.1",
  "user_id": "user-42"
}

The user_id field is only present for presence channels. The socket_id identifies the sending connection.

Subscription Count Events

{
  "name": "subscription_count",
  "channel": "my-channel",
  "subscription_count": 5
}

Subscription count webhooks are disabled by default. Enable per-app with:

Per the Pusher specification, this event is not sent for presence channels.

Signature Verification

To verify webhooks on your server:

// healthHealth & Readiness

Health and readiness endpoints are available on the main port (6001).

GET /

Liveness check. Always returns 200 OK.

GET /ready

Readiness check for load balancers and orchestration (e.g., Kubernetes readiness probes).

• Local adapter: Always returns 200 OK immediately.
• Redis adapter: Returns 503 Not ready until Redis subscriptions are established and peer discovery is complete. Returns 503 again if the node is shutting down or if the Redis connection drops (readiness drops on disconnect and recovers after resubscribe + re-discovery).

GET /accept-traffic

Returns 200 OK unless the server is in graceful shutdown, in which case it returns 503. Useful for draining traffic before termination.

// statsStats

The stats server runs on a separate port (9100 by default, configurable via metrics_port). Only available when metrics_enabled = true.

GET /health

Returns {"status": "ok"}.

GET /stats

Returns rich JSON metrics including:

• Server info — version, uptime, adapter mode
• Connections — current, total, total disconnections
• Channels — active channels per app
• Messages — WebSocket messages sent/received, HTTP calls
• Network — bytes in/out (WebSocket and HTTP, broken down and totaled)
• Process — PID, RSS memory, virtual memory, peak memory, CPU user/system/total ms, thread count, open FDs, context switches
• System — CPU cores, load average (1m/5m/15m), total/available memory, system uptime
• Per-app breakdown — all metrics segmented by app ID

Stats are computed every 2 seconds in a background task. Process and system metrics are read via spawn_blocking to avoid blocking the async runtime.

// scalingRedis Scaling

For multi-node deployments, rushsocket uses Redis for cross-node coordination: pub/sub for event broadcasting, Hashes for global presence state, and key-value pairs for stats aggregation.

Setup

1. Set up Redis (version 6+ recommended).

2. Update your config:

3. Restart all rushsocket nodes. Events triggered on any node are automatically broadcast to all connected clients across the cluster. The cache driver automatically uses Redis when the adapter is set to "redis".

Redis Data Model

rushsocket stores the following keys in Redis (all prefixed with the configured prefix):

Cluster Features

Global Presence (Redis Hashes)

Presence members are stored in Redis Hashes, not local memory. When a user joins a presence channel, their info is written to Redis via HSET. When they leave (no sockets on any node), they're removed via HDEL. Queries like get_presence_members and get_presence_user_count read directly from Redis with HGETALL and HLEN — no cross-node broadcasting needed.

Node Stats Heartbeats

Every 5 seconds, each node writes its local stats (per-app connection counts and channel socket counts) to a Redis key with a 15-second TTL. Stats queries (get_connection_count, get_channels, get_channel_socket_count) read fresh local data plus cached remote data via MGET — no cross-node broadcasting needed. If a node crashes, its stats expire in 15 seconds.

Distributed Occupancy (SETNX/DEL)

channel_occupied and channel_vacated webhooks are deduplicated across the cluster. The first node to see a subscriber uses SETNX to claim the occupancy flag. The last node to see all subscribers leave verifies with a real-time cross-node query before deleting the flag and firing channel_vacated.

Redis Adapter Behavior

• Peer discovery: On startup (and after each reconnect), each node publishes an announce heartbeat and sends a discovery request to all peers. Peers respond, populating the node's peer registry. The /ready endpoint returns 503 until this completes.
• Heartbeats: Each node publishes a heartbeat every 30 seconds to keep connections alive and maintain the peer registry. Peers not seen for 60 seconds are pruned.
• Reconnect handling: If the Redis subscriber connection drops, the node marks itself not-ready, reconnects, resubscribes, and re-discovers peers before accepting traffic again. A generation counter prevents stale discovery tasks from incorrectly restoring readiness.
• Connection splitting: Broadcast traffic (channel messages, heartbeats) and control traffic (cross-node requests/responses) use separate Redis connections to prevent head-of-line blocking.
• Per-node quotas: Connection limits and presence member limits are enforced per-node, not cluster-wide. This is consistent with the Pusher protocol and avoids cross-node coordination on the hot path.
• Subscriber timeout: If no message is received on the subscriber for 90 seconds (including heartbeats), the connection is assumed dead and a reconnect is forced.

// securityTLS / SSL

rushsocket has built-in TLS support via rustls — no external reverse proxy needed.

1. Obtain certificates (e.g., via Let's Encrypt / certbot).

2. Update your config:

3. Update your client to use wss:// and forceTLS: true.

For certificate renewal, restart rushsocket after renewing to reload the new certificates.

// cloudflareCloudflare Proxy

You can use Cloudflare as a reverse proxy to handle TLS termination and DDoS protection — no need to configure TLS certificates on rushsocket itself.

Setup

1. Point your domain to your server in Cloudflare DNS with the proxy enabled (orange cloud).

2. Configure rushsocket to listen on a Cloudflare-compatible port. Cloudflare only proxies WebSocket traffic on specific ports:

Ports that support HTTPS/WSS (recommended)

Ports that support HTTP/WS only

For WSS (secure WebSocket), use one of the HTTPS ports. The recommended setup:

3. Set Cloudflare SSL/TLS mode to "Flexible" (Cloudflare encrypts client-to-edge, sends plain HTTP/WS to your origin) or "Full" if you also enable TLS on rushsocket.

4. Update your client:

Cloudflare has a WebSocket idle timeout of 100 seconds. rushsocket's default server_ping_interval of 60 seconds keeps the connection alive well within this limit.

// channelsChannel Types

rushsocket supports all Pusher channel types out of the box:

// architectureArchitecture

Connection Lifecycle

1. Client connects via WebSocket at /app/{key}
2. Server validates the app key, checks connection limits (atomic CAS) and memory threshold (cached, non-blocking)
3. On success, sends pusher:connection_established with a unique socket_id
4. Server sends periodic pings; client must respond with pongs within the configured timeout
5. Slow consumers (clients whose outbound buffer is full) are automatically force-closed

Adapter Model

rushsocket uses an adapter pattern to abstract single-node vs. multi-node operation:

• Local adapter: All state is in-memory using lock-free DashMap structures. Suitable for single-node deployments.
• Redis adapter: Wraps the local adapter and adds Redis for cross-node coordination. Channel messages are broadcast via pub/sub. Presence state is stored in Redis Hashes. Stats are exchanged via periodic heartbeat keys with TTL. A request/response protocol handles cluster-wide queries that can't be served from Redis alone (e.g., listing socket IDs in a channel, aggregating metrics).

Key Design Decisions

• Atomic admission control: Connection limits use AtomicUsize with CAS loops — no TOCTOU races between checking the limit and inserting the socket.
• Atomic presence limits: Presence member limits are checked and enforced while holding the DashMap entry guard, preventing over-admission races.
• Zero-copy fan-out: Channel messages are serialized once into bytes::Bytes (reference-counted), then shared across all recipients without per-socket copies.
• Non-blocking memory checks: Memory usage is sampled every 2 seconds by a background task and cached in an AtomicU64. The WebSocket handshake reads a single atomic — no /proc I/O on the hot path.
• Non-blocking webhooks: Webhook events are queued via an unbounded mpsc channel. The WebSocket handler never waits for HTTP delivery.
• Generation-guarded readiness: Redis reconnects bump an atomic generation counter. Stale peer discovery tasks from previous connections cannot flip the readiness flag.
• Lock safety: Per-connection state uses parking_lot::Mutex which never poisons. A panicked thread cannot cascade into server-wide lock failures.
• Body integrity: POST requests with a body_md5 query parameter are verified against the actual request body, catching tampering or corruption in transit.