Xshathra
Log inGet started

Centrifugo in Xshathra

Xshathra Realtime is Centrifugo behind your app hostname under /realtime. You do not configure Centrifugo directly in day-to-day integration: you use project keys from the console, Xshathra's token and publish APIs, and the paths documented in API reference and Client integration. This page summarizes how Centrifugo behaves so you can map official docs to Xshathra.

Core concepts

  • Client — opens a WebSocket to /realtime/connection/websocket, sends a connect command with a connection JWT (not usually as a query string on the URL). Libraries such as centrifuge-js handle framing.
  • Channel — a named pub/sub stream. Names are often namespace:rest where the first segment is a Centrifugo namespace defined in server config (see below).
  • Publish — server-side HTTP call to push a JSON data payload to subscribers on a channel. In Xshathra you call POST …/api/realtime/publish with your project server_api_key; the app proxies to Centrifugo with deployment credentials.

JWT usage (connection vs subscription)

Centrifugo validates HS256 JWTs signed with the engine token_hmac_secret_key. Xshathra signs those JWTs in POST /api/realtime/token and POST /api/realtime/subscription-token so your product never holds the engine secret.

  • Connection token — identifies the user (sub claim); may include optional channels, info, and Xshathra projectId claim. Mint via /api/realtime/token.
  • Subscription token — authorizes joining one channel. Use when namespaces are configured for private subscribe rules. Mint via /api/realtime/subscription-token.

Official detail: Centrifugo authentication, channel token auth.

Namespaces and channel names

The bundled config defines namespaces such as public. Valid channels look like public:room_1. A channel like chat:proj_x:room_y requires a matching chat namespace (and rules) in centrifugo/config.json before Centrifugo will accept it.

Official detail: Channels and namespaces.

Wire protocol and WebSocket

Clients use the Centrifuge protocol over WebSocket (often subprotocol centrifuge-json). Your reverse proxy must forwardUpgrade and Connection for /realtime/ so WSS works in production.

Official detail: Client API.

Server HTTP API (publish and more)

Centrifugo exposes HTTP APIs such as /api/publish. Xshathra wraps publish at POST /api/realtime/publish using your server_api_key. Other engine methods (presence, history, etc.) are available on the engine URL for operators; product code typically only needs token + publish + client SDK.

Official detail: Server API.

Where Xshathra configures Centrifugo

In this repo, centrifugo/config.json is mounted into the engine container; secrets come from environment (for example CENTRIFUGO_TOKEN_HMAC_SECRET_KEY and CENTRIFUGO_API_KEY). The Next.js app must use the same token secret for signing client JWTs as Centrifugo uses for verification — see deployment env docs in the README.

Related on this site