How centrifugal/centrifugo works
Purpose and entry points
Centrifugo is a Go real-time PUB/SUB server: application backends publish or manage subscriptions through HTTP/gRPC APIs; connected clients receive channel traffic over WebSocket, HTTP streaming, SSE, gRPC, or experimental WebTransport. Process startup is main.go, with CLI command wiring in internal/app/cmd.go and server lifecycle assembly in internal/app/run.go.
Bootstrap, configuration, and server composition
The serve command loads, migrates, and validates configuration, then constructs shared dependencies and listeners. internal/app/engine.go owns the central real-time engine integration; internal/app/mux.go composes HTTP routes/transports; internal/app/grpc.go configures gRPC; internal/config/config.go and internal/config/validate.go define the configuration boundary. TLS, origins, logging, telemetry, brokers, and optional services are configured before serving.
Client connection and transport boundary
Client traffic enters transport-specific adapters which normalize it into common connection/session behavior. Bidirectional WebSocket is implemented under internal/websocket/; unidirectional HTTP-streaming, SSE, gRPC, and WebTransport adapters are respectively internal/unihttpstream/transport.go, internal/unisse/transport.go, internal/unigrpc/transport.go, and internal/wt/transport.go. internal/client/client.go and internal/client/handler.go implement client protocol handling, subscriptions, commands, and message delivery.
Authentication and request policy
HTTP/client requests pass middleware for protocol enforcement, observability, connection limiting, CORS, and auth. Core paths include internal/middleware/auth.go, internal/middleware/auththrottle.go, and internal/middleware/otel.go. JWT validation supports signing keys/JWKS through internal/jwtverify/token_verifier_jwt.go and internal/jwks/manager.go; proxy/origin integration is represented by internal/app/proxy.go and internal/origin/origin.go. This boundary separates untrusted client credentials and backend authorization decisions from the messaging engine.
Backend API and proxy operations
Backends call generated HTTP and gRPC APIs to publish, inspect connections, refresh credentials/subscriptions, and issue RPC-related operations. Public API dispatch is in internal/api/api.go, internal/api/handler.go, and internal/api/grpc.go; wire contracts are generated from internal/apiproto/api.proto. internal/proxy/ implements outbound calls to an application backend for connect, subscribe, publish, refresh, and RPC hooks, with HTTP and gRPC variants.
Distribution, persistence, and ingestion
The engine scales publications, presence, history, and cross-node control via pluggable brokers. Redis/NATS options are under internal/redisnatsbroker/broker.go, internal/natsbroker/broker.go, and internal/pubsub/; PostgreSQL-backed map and stream brokers are internal/pgmapbroker/pgmapbroker.go and internal/pgstreambroker/pgstreambroker.go. External event ingestion supports Kafka, PostgreSQL, Redis Streams, NATS JetStream, AWS SQS, Google Pub/Sub, and Azure Service Bus in internal/consuming/. PostgreSQL outbox workers in internal/pgoutbox/ support transactional-outbox/CDC delivery.
Operations and observability
The service exposes health and runtime operations through internal/health/health.go and embedded admin handling in internal/admin/handlers.go. Metrics are centralized in internal/metrics/metrics.go, with optional Graphite export at internal/metrics/graphite/graphite.go; OpenTelemetry provider setup is internal/telemetry/provider.go. Deployment targets include a container image (Dockerfile), local dependency composition (docker-compose.yml), and release packaging (.goreleaser.yml).
Main entry points: run.go Server assembly · engine.go Real-time engine · auth.go Request policy · client.go Client sessions
Components 20
Bootstrap
- Process entry
main.go - CLI serve command
internal/app/cmd.go - Server assembly · Builds dependencies and starts listeners.
internal/app/run.go - Configuration boundary
internal/config/config.go - Real-time engine · Coordinates publications, subscriptions, presence, and history.
internal/app/engine.go
Client access
- HTTP transport mux
internal/app/mux.go - Request policy · Applies auth, throttling, CORS, limits, and observability.
internal/middleware/auth.go - JWT and JWKS validation
internal/jwtverify/token_verifier_jwt.go - WebSocket adapter
- Streaming adapters · Normalizes unidirectional client transports.
internal/unihttpstream/transport.go - Client sessions · Handles commands, subscriptions, and delivery.
internal/client/client.go
Backend integration
- Backend API dispatch · Serves publish, connection, refresh, and RPC operations.
internal/api/api.go - API contracts
internal/apiproto/api.proto - Application hooks · Calls backend connect, subscribe, publish, refresh, and RPC hooks.
Distribution & ingestion
- Broker layer · Distributes publications and cross-node control.
- Broker implementations
internal/redisnatsbroker/broker.go - External event consumers · Ingests Kafka, streams, queues, and cloud pub/sub events.
- PostgreSQL outbox
Operations
- Health and admin
internal/health/health.go - Metrics and telemetry
internal/telemetry/provider.go
Connections 24
- Process entry → CLI serve command: initializes
- CLI serve command → Configuration boundary: loads and validates
- CLI serve command → Server assembly: runs
- Configuration boundary → Server assembly: configures
- Server assembly → Real-time engine: constructs
- Server assembly → HTTP transport mux: serves
- Server assembly → Backend API dispatch: exposes
- Server assembly → Health and admin: exposes
- Server assembly → Metrics and telemetry: initializes
- HTTP transport mux → Request policy: applies
- Request policy → JWT and JWKS validation: validates credentials with
- Request policy → WebSocket adapter: protects
- Request policy → Streaming adapters: protects
- WebSocket adapter → Client sessions: creates sessions
- Streaming adapters → Client sessions: normalizes into
- Client sessions → Real-time engine: subscribes and delivers via
- Backend API dispatch → API contracts: implements
- Backend API dispatch → Real-time engine: publishes and manages
- Client sessions → Application hooks: invokes hooks
- Real-time engine → Broker layer: distributes through
- Broker implementations → Broker layer: implements
- External event consumers → Real-time engine: ingests events into
- PostgreSQL outbox → External event consumers: feeds transactional events
- Real-time engine → Metrics and telemetry: reports signals