/centrifugo

name: centrifugo
description: "Centrifugo real-time messaging server expert for WebSocket PUB/SUB, channel management, JWT authentication, event proxying, and horizontal scaling with Redis/NATS. Use when: centrifugo, centrifugal, real-time messaging, websocket pubsub, channel subscriptions, real-time notifications, live updates, presence, history recovery, server-sent events integration, real-time transport layer. Do not use for: general WebSocket programming without Centrifugo, Socket.IO, Pusher SDK, or other real-time frameworks."

Centrifugo Real-Time Messaging Integration

Centrifugo is a self-hosted, language-agnostic real-time messaging server. It handles persistent connections (WebSocket, SSE, HTTP-streaming, WebTransport, GRPC) and broadcasts messages via a channel-based PUB/SUB model. The application backend publishes to channels via Server API; Centrifugo delivers to online subscribers instantly.

Core Architecture

Backend App ──(HTTP/GRPC Server API)──> Centrifugo Cluster ──(WebSocket/SSE)──> Clients
                                              │
                                        Redis/NATS Broker
                                        (for multi-node)

**Key principle**: All user-generated data flows through the application backend first (validate, persist, then publish to Centrifugo). Centrifugo is the transport layer, not the source of truth.

Procedures

Step 1: Determine Integration Pattern

Identify the real-time feature being built and select the appropriate pattern:

1. **Unidirectional publish** (most common): Backend publishes to channels after processing user requests. Clients subscribe and receive updates passively. 2. **Bidirectional with proxy**: Clients send data over the real-time connection; Centrifugo proxies events (connect, subscribe, publish, RPC) to the backend for validation. 3. **Server-side subscriptions**: Backend controls which channels a user subscribes to (useful for personalized feeds, notifications).

Step 2: Configure Centrifugo Server

Generate a minimal configuration:

centrifugo genconfig  # Creates config.json

Or use Docker:

docker run -p 8000:8000 centrifugo/centrifugo:v6 centrifugo

Essential configuration structure (JSON, YAML, or TOML supported):

{
  "client": {
    "token": {
      "hmac_secret_key": "<SECRET>"
    },
    "allowed_origins": ["http://localhost:3000"]
  },
  "http_api": {
    "key": "<API_KEY>"
  },
  "channel": {
    "without_namespace": {
      "allow_subscribe_for_client": true
    }
  }
}

Read `references/configuration.md` for the full configuration reference including TLS, admin UI, environment variables, and advanced options.

Step 3: Set Up Authentication

Centrifugo authenticates clients via JWT or connect proxy.

**JWT approach** (recommended for most cases):

• Backend generates a JWT with `sub` (user ID) and `exp` claims, signed with the configured HMAC/RSA/ECDSA key.
• Client passes the token when connecting.
• Supports token refresh for long-lived connections.

# Backend: generate connection JWT (Python example)
import jwt, time
token = jwt.encode(
    {"sub": "user123", "exp": int(time.time()) + 3600},
    "<HMAC_SECRET>", algorithm="HS256"
)

// Client: connect with token
const client = new Centrifuge("ws://localhost:8000/connection/websocket", {
  token: "<JWT_TOKEN>",
});
client.connect();

**Connect proxy approach** (alternative):

• Centrifugo forwards connection requests to the backend endpoint for authentication.
• No JWT needed; backend responds with user identity.

Read `references/authentication.md` for JWT claims, token refresh, proxy auth, and channel-level authorization tokens.

Step 4: Design Channel Structure

Channels are ephemeral strings that serve as message pathways. Use namespaces to apply different behaviors.

**Naming conventions**:

• `chat:room-123` — namespace `chat`, channel for room 123
• `notifications:user#42` — user-limited channel (only user 42 can subscribe)
• `$private:secret` — private channel prefix (requires subscription token)

**Namespace configuration**:

{
  "channel": {
    "namespaces": [
      {
        "name": "chat",
        "presence": true,
        "history_size": 50,
        "history_ttl": "300s",
        "force_recovery": true,
        "join_leave": true
      },
      {
        "name": "notifications",
        "allow_user_limited_channels": true
      }
    ]
  }
}

Read `references/channels.md` for all channel options, namespace rules, and special channel prefixes.

Step 5: Publish from Backend (Server API)

Use HTTP or GRPC to publish messages from the application backend.

**HTTP API** — POST to `/api/<method>` with `X-API-Key` header:

# Publish to a channel
curl -X POST -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
  -d '{"channel": "chat:room-1", "data": {"text": "hello"}}' \
  http://localhost:8000/api/publish

# Broadcast to multiple channels
curl -X POST -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
  -d '{"channels": ["user:1", "user:2"], "data": {"text": "hello"}}' \
  http://localhost:8000/api/broadcast

**Available API methods**: `publish`, `broadcast`, `subscribe`, `unsubscribe`, `disconnect`, `refresh`, `presence`, `presence_stats`, `history`, `history_remove`, `channels`, `info`, `batch`.

Read `references/server-api.md` for all method signatures, request/response schemas, and HTTP API library links.

Step 6: Connect Clients with SDK

Official SDKs: `centrifuge-js` (browser/Node/React Native), `centrifuge-go`, `centrifuge-dart` (Flutter), `centrifuge-swift` (iOS), `centrifuge-java` (Android), `centrifuge-python`.

**JavaScript client pattern**:

import { Centrifuge } from "centrifuge";

const client = new Centrifuge("ws://localhost:8000/connection/websocket", {
  token: "<JWT>",
});

// Connection state handlers
client.on("connecting", ctx => console.