Skip to content

Subscription types: Map subscriptions and Shared Poll subscriptions#1125

Draft
FZambia wants to merge 41 commits intomasterfrom
subscription_types
Draft

Subscription types: Map subscriptions and Shared Poll subscriptions#1125
FZambia wants to merge 41 commits intomasterfrom
subscription_types

Conversation

@FZambia
Copy link
Copy Markdown
Member

@FZambia FZambia commented Apr 3, 2026

Summary

This PR extends Centrifugo with support for the two new subscription types introduced in the centrifuge library centrifugal/centrifuge#565Map subscriptions and Shared Poll subscriptions — and adds a PostgreSQL MapBroker as a first-class engine option.

Map subscriptions

Integrates centrifuge's map subscription model into Centrifugo's configuration, proxy, and API layers.

  • Namespace-level subscription_type — each namespace declares its type: stream (default), map, map_clients, map_users, or shared_poll. Only matching subscription types are allowed per namespace.
  • map config block on namespace — controls mode (ephemeral/durable/persistent), key_ttl, ordered, stream_size, stream_ttl, external_state, publish/remove permissions, and proxy settings.
  • Map presence channelsmap_clients_presence_channel_prefix and map_users_presence_channel_prefix on stream namespaces allow tracking connection/user presence via MapBroker in a derived channel.
  • Server API — new endpoints: MapPublish, MapRemove, MapReadState, MapReadStream, MapStats, MapClear (HTTP + gRPC).
  • Proxy protocol — new MapPublish, MapRemove proxy types (HTTP + gRPC) for delegating map writes to the application backend.
  • Track signature verification — shared poll track requests are authorized via a signature string; Centrifugo verifies it server-side with key rotation support.

Shared Poll subscriptions

  • shared_poll config block on namespace — proxy_name, refresh_interval, refresh_batch_size, max_keys_per_connection, mode (versionless/versioned), publish_enabled (fast-track), and tuning options.
  • Proxy protocol — new SharedPollRefresh proxy type (HTTP + gRPC) that Centrifugo calls on each poll cycle with the aggregated key set. The backend returns current data per key.
  • SharedPollPublish API — server API endpoint for fast-track publication to shared poll channels.
  • PubSub package — lightweight internal/pubsub abstraction (Redis or NATS) used for shared poll cross-node notifications.

PostgreSQL MapBroker

postgres option for map_broker.type that implements the full MapBroker interface backed by PostgreSQL.

  • Outbox-based delivery — writes go into a transactional outbox table; a delivery worker fans out to subscribers with configurable poll interval and batch size. Optional LISTEN/NOTIFY for low-latency wakeup.
  • Sharded parallelism — channels are distributed across configurable shards for parallel delivery workers.
  • Automatic schema managementEnsureSchema() creates tables, indexes, and functions on startup. Supports forward migrations via integer versioning. Can be disabled with skip_schema_init.
  • JSONB or BYTEAbinary_data flag switches between JSONB (queryable) and BYTEA (binary/protobuf payloads) column types.
  • TTL and cleanup — background workers handle key expiry and stream/meta/idempotency cleanup.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant