DOCSEARCHbyAlgolia
Submit Docs

Centrifugo Documentation

website·Indexed Apr 14, 2026

https://centrifugal.dev/docs/

Official documentation for Centrifugo, a real-time messaging server built on the Go-based Centrifuge library. The index covers versions 3 through 6, including installation guides, configuration parameters, client API references, and framework integrations for Laravel, Symfony, and Django. Content details transport protocols, scaling strategies with Redis or Tarantool, authentication via JWT, and Pro features like ClickHouse analytics. Includes migration guides, design overviews, and troubleshooting FAQs for building scalable bidirectional communication systems.

Tokens
388.6K
Snippets
137
Records
2.3K
Agent score
50%

What's inside Centrifugo

  1. Overview of Connections API for session management

    The Connections API in Centrifugo PRO allows administrators to retrieve details about all active sessions without enabling the presence feature on channels. This is useful for managing active user sessions (e.g., in messenger apps) and troubleshooting system state. Key capabilities include:

    • Retrieving active connections filtered by User ID or CEL expression.
    • Accessing metadata attached to connections (set via JWT meta claim or connect proxy response) which remains hidden from the client.
    • Identifying connection details such as transport, protocol, and app name to facilitate disconnecting specific sessions via the Disconnect Server API.

  2. Overview of user and channel tracing in Centrifugo Pro

    Centrifugo Pro provides a tracing feature that allows administrators to attach to specific channels or user IDs to monitor real-time connection and message flow. This capability is essential for debugging issues, investigating application behavior, and verifying that the system operates as expected. You can initiate traces via the Centrifugo Admin UI or programmatically using the Admin API.

  3. Overview of Unidirectional Client Protocol

    The Unidirectional client protocol allows clients to receive real-time updates from Centrifugo without maintaining a persistent bidirectional connection. This approach leverages native browser APIs (like EventSource or HTTP streaming) to minimize client-side dependencies while retaining Centrifugo features such as subscription multiplexing and efficient publication. All unidirectional transports (WebSocket, HTTP streaming, SSE, gRPC) share the same underlying protocol structure. Clients must implement basic parsing logic to handle incoming message types: connect, publication, join, leave, and disconnect.

  4. Overview of Centrifugo Push Notification API

    Centrifugo PRO enables sending mobile and web push notifications to offline or background users via Firebase Cloud Messaging (FCM), Huawei Messaging Service (HMS), and Apple Push Notification service (APNs). The API manages device tokens, topic subscriptions, and supports timezone-aware delivery, localization, templating, and per-device rate limiting. It acts as a high-performance proxy, handling token storage, error recovery, and efficient broadcasting to single devices or groups subscribed to topics.

  5. Overview of Built-in Async Consumers

    Centrifugo supports built-in asynchronous consumers to publish messages from external brokers (like Kafka, Redis, PostgreSQL) into channels. This allows for reliable execution of API commands (publish, broadcast, etc.) upon changes in a primary application database, handling temporary network issues via queuing techniques. While you can implement custom consumers using any queue system, Centrifugo provides native support for specific brokers to simplify integration.

  6. Overview of Connections API

    The Connections API is a Centrifugo PRO feature that allows retrieving details of all active sessions without enabling the presence feature on channels. It supports filtering by User ID or CEL expression. This API is useful for managing active user sessions (e.g., in messenger apps to view and disconnect specific sessions) and for debugging system state. Any JSON payload attached to a connection (via JWT meta claim or connect proxy result) is visible in the API response but hidden from the client.

  7. Overview of Centrifugo Server API

    The Centrifugo Server API allows your application backend to interact with the server programmatically. It supports two transport types: HTTP API and gRPC API, both sharing the same request/response schema. Key capabilities include publishing messages to channels, broadcasting, subscribing, retrieving cluster information, disconnecting users, and extracting channel presence or history data.

  8. Overview of Channel Publication Filtering

    Channel publication filtering allows server-side evaluation of tags in subscription requests to control message delivery. This feature significantly reduces bandwidth usage and minimizes client-side processing overhead by filtering out irrelevant messages at the server level before they reach the client.

    Key characteristics:

    • Purpose: Bandwidth and performance optimization only. It is NOT a security feature and should not be used for access control or data protection.
    • Mechanism: Uses tags (a map[string]string) attached to each publication. Subscribers specify filters to receive only publications matching their criteria.
    • Scope: Works only with client-side subscriptions.
    • Compatibility: Currently supported only by centrifuge-js.
    • Mutual Exclusivity: Cannot be used together with Delta Compression in the same channel.
    • Recovery: Works seamlessly with automatic recovery mechanisms; only matching publications are returned during stream recovery or cache recovery.
    • Performance: Designed to be zero-allocation during broadcast. CPU overhead is negligible, but each subscription incurs memory overhead to store the filter structure.

  9. Overview of Proxy Subscription Streams

    Proxy subscription streams are an experimental feature in Centrifugo that enable scalable, on-demand client-to-backend communication. Instead of the backend continuously pushing messages to channels, Centrifugo establishes a gRPC stream between itself and the application backend only when a user subscribes to a channel. This allows the backend to generate individual streams that exist only while the client is subscribed, effectively acting as a WebSocket-to-gRPC (or SSE/WebTransport-to-gRPC) proxy. This pattern is useful for integrating with third-party streaming providers (e.g., Loki logs, Twitter API, MQTT) or implementing custom filtering logic that requires resource deallocation when the stream is no longer needed.

  10. Overview of User and Channel Tracing in Centrifugo Pro

    Centrifugo Pro (v5) includes a tracing feature that allows developers to attach to specific channels or users to observe real-time events. This capability is essential for debugging connection issues, verifying application behavior, and understanding message flow. You can attach to trace streams in two ways: via the Centrifugo Admin UI panel or programmatically using the admin API with a valid admin token.

  11. Overview of Centrifugo User Status API

    The Centrifugo User Status API (PRO feature) enables server-side management of client presence beyond simple channel subscriptions. It tracks specific user activity (e.g., clicks, mouse movement) rather than just connection state. This allows applications to distinguish between a user who is merely connected but idle versus one actively using the application. The feature stores the last active time in Redis and supports batch queries for multiple users.

  12. Overview of Connections API

    The Connections API in Centrifugo PRO allows administrators to retrieve detailed information about active client sessions without needing to enable the presence feature on channels. This is useful for managing user sessions (e.g., in messenger apps) and debugging system state.

    Key capabilities:

    • Retrieve all active sessions filtered by User ID or CEL expression.
    • Access metadata attached to connections (set via JWT meta claim or connect proxy response), which remains hidden from the client.
    • Use the retrieved connection IDs to disconnect specific sessions via the Disconnect API.