Centrifugo Documentation

The project uses a custom fork of the Gorilla WebSocket library, specifically adapted for Centrifuge's requirements. Key differences from the original Gorilla implementation include:

• Optimized Upgrades: Reduced allocations (from 9 down to 3) during the upgrade process.
• HTTP/2 Support: Supports WebSocket over HTTP/2 (RFC 8441) on the server side.
• Subprotocol Handling: The selected subprotocol is not stored internally; instead, it is returned during the Upgrade or Dial operations.
• Client Changes: The Client no longer uses a custom Proxy.
• Concurrency: Concurrent use detection is handled on a best-effort basis.
• Handlers: It is not possible to set a custom CloseHandler.
• Linting: Includes various lint fixes for the Centrifuge environment.

To benchmark Centrifugo using the provided k6 script, you must first run a Centrifugo instance with a specific configuration that enables JWT authentication and client-side subscriptions. The script connects to Centrifugo using a JWT per user, subscribes to the test channel, waits for a period, and then exits.

Prerequisites:

• k6 installed on your system.
• A running Centrifugo instance configured with the settings below.
• Ensure your system is tuned to handle high connection volumes.

Steps:

1. Start Centrifugo with the required configuration.
2. Execute the benchmark script using k6.

k6 run benchmark.js

If you are not relying on EnsureSchema() for automatic upgrades, follow this manual path:

1. Fresh install: Apply the initial schema using internal/pgmapbroker/internal/sql/schema_all.sql.
2. Check current version: Run the following query to verify the current schema version:

   SELECT schema_version FROM cf_map_schema_version WHERE id = 1;

3. Apply migrations: Execute migration files located in internal/pgmapbroker/internal/sql/migrations/ in sequential order.

Note: Keeping EnsureSchema() enabled is safe; it acts as a no-op if the database version already matches the code version.

Use the create_cluster.sh script to spin up a local Redis cluster consisting of N nodes with M replicas each. This is intended for development and benchmarking purposes. The script will continue running the cluster nodes until it is interrupted.

All cluster data is persisted to a local directory named cluster_data. By default, the Redis nodes are configured to run without RDB or AOF enabled (--save "" --appendonly no).

To add a new migration to the MapBroker schema, follow this developer workflow:

1. Increment the schemaVersion in internal/pgmapbroker/pgmapbroker.go.
2. Create a new SQL migration file at internal/pgmapbroker/internal/sql/migrations/NNN.sql (where NNN is the sequence number). The SQL must be idempotent and target both the standard and binary prefixes.
3. Add an entry to the schemaMigrations map in the code to embed the new file.
4. Update the schema.sql template so that fresh installs receive the latest schema state.
5. Run make pg-schemas to regenerate necessary files.

Invariant: A fresh install via DDL must produce an identical schema to an upgrade performed via sequential migrations.

This benchmark script uses k6 to test Centrifugo's unidirectional WebSocket endpoint. It is configured to establish 5,000 connections over a 1-minute duration, wait for 4 minutes, and then stop.

k6 run benchmark.js

This setup creates a local Redis Sentinel-based environment consisting of 1 Sentinel and 3 Redis nodes (1 master and 2 replicas).

Note: This configuration is for local testing only. In production, you must use at least 3 Sentinels to ensure high availability.

bash start.sh

To test how your application handles a Redis master failure, you can manually trigger a failover using the Sentinel CLI.

1. Connect to the Sentinel instance using redis-cli on port 26379.
2. Execute the sentinel failover command targeting your master name (default is mymaster).

To set up and start a Clickhouse cluster consisting of 2 shards and 2 replicas using docker-compose, follow these steps:

1. Generate the necessary configuration files using make config.
2. Start the cluster using docker compose up.

The EnsureSchema() function automatically manages the PostgreSQL schema for MapBroker. It handles the creation of both JSONB and BYTEA schema variants in a single call.

Automatic Handling:

• New tables (CREATE TABLE IF NOT EXISTS)
• New indexes (CREATE INDEX IF NOT EXISTS)
• Function body changes (CREATE OR REPLACE FUNCTION)
• New function parameters with DEFAULT values

Manual Migrations Required For:

• Adding new columns (ALTER TABLE ADD COLUMN IF NOT EXISTS)
• Changing column types (ALTER TABLE ALTER COLUMN TYPE)
• Changing function signatures (requires DROP FUNCTION + CREATE)
• Dropping columns (requires a two-phase approach: stop using the column in code first, then drop it via migration)