Skip to content

feat(redis): add Redis Sentinel support#2895

Open
PAzter1101 wants to merge 4 commits into
ag2ai:mainfrom
PAzter1101:feat/redis-sentinel-support
Open

feat(redis): add Redis Sentinel support#2895
PAzter1101 wants to merge 4 commits into
ag2ai:mainfrom
PAzter1101:feat/redis-sentinel-support

Conversation

@PAzter1101

Copy link
Copy Markdown

Summary

Adds connection-level Redis Sentinel support to RedisBroker, addressing #1812.

broker = RedisBroker(
    sentinels=[("sentinel-1", 26379), ("sentinel-2", 26379)],
    sentinel_master_name="mymaster",
)

What changed

  • New broker params (RedisConnectionParams): sentinels, sentinel_master_name, sentinel_kwargs. Extracted in RedisBroker.__init__; a missing sentinel_master_name raises SetupError. Excluded from cluster params.
  • RedisConnectionState gains an optional SentinelConfig. When set, connect() builds the client via redis.asyncio.sentinel.Sentinel(...).master_for(...) instead of a plain ConnectionPool. The resulting SentinelConnectionPool re-discovers the current master on every reconnect, so publishers and stream (XREADGROUP) consumers fail over for free — both already go through connection.client.
  • Stream subscriber busy-loop fix: the stream _consume loop had no backoff in its except (unlike the base channel/list loop), so it would hot-loop on a persistent ConnectionError (e.g. during a master failover). Extracted the existing 5s backoff into a shared CONSUME_ERROR_BACKOFF_SECONDS and applied it in both loops.
  • Tests: unit tests that need no running Sentinel — assert the broker builds the right SentinelConfig, that direct mode is unaffected, validation, and that connect() actually yields a SentinelConnectionPool. New redis_sentinel pytest marker.

mypy --strict, ruff check, ruff format --check and the new unit tests pass locally.

Scope / follow-ups

This is the connection-level MVP outlined in #1812 (publishers + simple commands + streams). Intentionally not in this PR, to keep it focused:

  • Pub/Sub (channel) resubscribe after failover. A channel subscriber holds a long-lived pubsub() subscription; rebuilding and resubscribing it on failover is a separate change and is left as a follow-up. (Stream consumers recover because each xreadgroup re-acquires a connection from the Sentinel pool.)
  • Integration tests against a real Sentinel (a compose service + CI job mirroring the existing redis-cluster setup). The tests here are unit-level.

Refs #1812.

@PAzter1101 PAzter1101 requested a review from Lancetnik as a code owner May 31, 2026 17:17
@CLAassistant

CLAassistant commented May 31, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@github-actions github-actions Bot added dependencies Pull requests that update a dependency file Redis Issues related to `faststream.redis` module and Redis features labels May 31, 2026
@pbonneaudiabolocom

Copy link
Copy Markdown

Hi,

Thanks for the hard work.

Seeing the PR for redis cluster, I wonder if it would not be "better" to create a RedisSentinelBroker than to add parameters to the generic RedisBroker.

It would prevent these param to be available in redisCluster as well, and it would somehow keep the same logic where you just switch from one broker to the other one when changing technology.

What do you think ?

Add connection-level Redis Sentinel support to RedisBroker:

- New broker params: sentinels, sentinel_master_name, sentinel_kwargs.
- RedisConnectionState builds the client via Sentinel.master_for() when
  configured, so the SentinelConnectionPool re-discovers the current master
  on reconnect. Publishers and stream consumers fail over for free, since
  both go through connection.client.
- Stream subscriber now backs off on fetch errors like the base channel/list
  loop (shared CONSUME_ERROR_BACKOFF_SECONDS), avoiding a busy-loop during a
  master failover.
- Unit tests (no running Sentinel needed) and a redis_sentinel marker.

Refs ag2ai#1812
RedisRouter (FastAPI integration) now accepts sentinels / sentinel_master_name /
sentinel_kwargs and forwards them to the underlying RedisBroker, so FastAPI +
FastStream applications get Sentinel support too (previously only the standalone
RedisBroker did). Adds unit tests asserting the router forwards config to broker.
…Broker

Per review feedback on ag2ai#2895, Sentinel support now lives in its own
RedisSentinelBroker / RedisSentinelRouter instead of extra parameters on the
generic RedisBroker — mirroring RedisClusterBroker (ag2ai#2854), so each topology is
a distinct broker class and Sentinel params no longer leak into RedisBroker /
RedisClusterBroker.

- RedisSentinelConnectionState builds the client via Sentinel.master_for();
  the generic RedisBroker / RedisRouter keep their original API.
- RedisSentinelParams holds sentinels / sentinel_master_name / sentinel_kwargs.
- RedisSentinelRouter adds FastAPI Sentinel support (which RedisClusterBroker
  does not provide).
- Docs: docs/en/redis/sentinel.md + navigation entry.

Refs ag2ai#1812
@PAzter1101 PAzter1101 force-pushed the feat/redis-sentinel-support branch from cca8a33 to 1a7226b Compare June 3, 2026 12:33
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Jun 3, 2026
@PAzter1101

Copy link
Copy Markdown
Author

Thanks for the suggestion — agreed. I've reworked it into a dedicated RedisSentinelBroker (plus RedisSentinelRouter for the FastAPI integration), mirroring RedisClusterBroker from #2854. The Sentinel params now live only on the Sentinel classes and no longer leak into RedisBroker/RedisClusterBroker. The earlier "params on RedisBroker" commits are kept in the history for context.

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

Labels

dependencies Pull requests that update a dependency file documentation Improvements or additions to documentation Redis Issues related to `faststream.redis` module and Redis features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants