centrifugo

What this skill does

# 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:

```bash
centrifugo genconfig  # Creates config.json
```

Or use Docker:

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

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

```json
{
  "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.

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

```javascript
// 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**:

```json
{
  "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:

```bash
# 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**:

```javascript
import { Centrifuge } from "centrifuge";

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

// Connection state handlers
client.on("connecting", ctx => console.log("connecting", ctx));
client.on("connected", ctx => console.log("connected", ctx));
client.on("disconnected", ctx => console.log("disconnected", ctx));

// Subscribe to channel
const sub = client.newSubscription("chat:room-1");
sub.on("publication", ctx => {
  console.log("received:", ctx.data);
});
sub.on("subscribing", ctx => console.log("subscribing", ctx));
sub.on("subscribed", ctx => console.log("subscribed", ctx));
sub.subscribe();

client.connect();
```

**Client states**: `disconnected` -> `connecting` -> `connected` (auto-reconnect with exponential backoff).

**Subscription states**: `unsubscribed` -> `subscribing` -> `subscribed` (auto-resubscribe on reconnect).

Read `references/client-sdk.md` for all SDK patterns, token refresh, presence/history from client, RPC calls, and Protobuf mode.

### Step 7: Configure Event Proxy (Optional)

Proxy client events to the backend for validation and custom logic.

**Supported proxy events**:

- `connect` — authenticate connections without JWT
- `refresh` — extend client sessions
- `subscribe` — validate channel access
- `publish` — validate publications from clients
- `rpc` — handle custom client-to-server calls
- `sub_refresh` — extend subscription sessions

```json
{
  "client": {
    "proxy": {
      "connect": {
        "enabled": true,
        "endpoint": "http://backend:3000/centrifugo/connect"
      },
      "rpc": {
        "enabled": true,
        "endpoint": "http://backend:3000/centrifugo/rpc"
      }
    }
  },
  "channel": {
    "namespaces": [
      {
        "name": "chat",
        "proxy": {
          "subscribe": {
            "enabled": true,
            "endpoint": "http://backend:3000/centrifugo/subscribe"
          },
          "publish": {
            "enabled": true,
            "endpoint": "http://backend:3000/centrifugo/publish"
          }
        }
      }
    ]
  }
}
```

Read `references/proxy.md` for proxy request/response schemas, GRPC proxy, header forwarding, and timeout configuration.

### Step 8: Scale Horizontally (Production)

**Memory engine** (default): Single node only. Fast, no dependencies. Suitable for development and small deployments.

**Redis engine**: Multi-node clusters. Messages published on any node reach all subscribers.

```json
{
  "engine": {
    "type": "redis",
    "redis": {
      "address": "redis://localhost:6379"
    }
  }
}
```

Supports Redis Sentinel, Redis Cluster, consistent sharding across multiple Redis instances, and Redis-compatible storages (Valkey, DragonflyDB, KeyDB, AWS ElastiCa