Add Redis Keyspace Notifications Support for Redis Cluster

[dmaier-redislabs]

Add Redis Keyspace Notifications Support for Redis Cluster

Summary

This PR adds comprehensive support for Redis keyspace notifications in redis-py, including a cluster-aware implementation that automatically subscribes to all primary nodes and handles topology changes.

Please also take a look at the specs/keyspace-notifications/SPEC.md file because it contains detailed instructions for the AI model that was leveraged for code generation purposes.

Features

Core Components

• EventType - Constants for common Redis keyspace notification event types (SET, DEL, EXPIRE, etc.) with IDE autocomplete support. Uses plain strings so new Redis events work without library updates.

• NotifyKeyspaceEvents - Enum for configuring Redis notify-keyspace-events setting with common presets (ALL, KEYSPACE_ALL, KEYEVENT_ALL) and individual flags.

• KeyNotification - Dataclass for parsed notifications with key, event_type, database, channel, and is_keyspace fields. Includes from_message() class method for parsing pub/sub messages.

• KeyspaceChannel - Channel builder for keyspace notifications (__keyspace@<db>__:<key>). Auto-detects patterns for subscribe vs psubscribe.

• KeyeventChannel - Channel builder for keyevent notifications (__keyevent@<db>__:<event>). Includes all_events() factory method.

• ClusterKeyspaceNotifications - Cluster-aware notification manager that:

  • Subscribes to ALL primary nodes (keyspace notifications are node-local in Redis Cluster)
  • Automatically configures notify-keyspace-events on all nodes (default: "KEA")
  • Handles topology changes and slot migrations
  • Supports handler callbacks for automatic notification processing
  • Provides run_in_thread() for background processing
  • Includes subscribe_keyspace() and subscribe_keyevent() convenience methods

Usage Examples

        def handler(msg):
            print(f"Handling: {msg}")

        cluster = RedisCluster.from_url("redis://localhost:16379")

        notifications = ClusterKeyspaceNotifications(cluster)
        notifications.subscribe(KeyspaceChannel("test:*"), handler=handler)

        # Start background thread that polls for messages and triggers handlers
        thread = notifications.run_in_thread(sleep_time=0.1, daemon=True)

        cluster.set("test:key", "value")
        cluster.set("test:key2", "value2")
        cluster.delete("test:key2")
        
        # Wait for handlers to be called
        time.sleep(1.0)

---

Note

Medium Risk
Adds a new public API layer that manages PubSub subscriptions across Redis Cluster primaries and implements reconnection/topology refresh logic, which could affect resource usage and edge-case behavior. Mostly additive, but changes introduce new background polling/threading patterns and extra per-node connections in cluster mode.

Overview
Adds first-class Redis keyspace notification support to redis-py, including channel builders (KeyspaceChannel, KeyeventChannel), a parsed message model (KeyNotification), and event constants (EventType).

Introduces sync managers (KeyspaceNotifications, ClusterKeyspaceNotifications) and async equivalents (AsyncKeyspaceNotifications, AsyncClusterKeyspaceNotifications) that automatically choose subscribe vs psubscribe, support optional per-channel handlers, and provide background processing (run_in_thread / async run) plus context-manager cleanup.

For cluster mode, the new managers subscribe to all primary nodes (since keyspace notifications are node-local) and include refresh logic to handle node changes and broken connections. Tests add mocked coverage for both sync/async behavior and a new r_with_keyspace_notifications fixture that temporarily sets notify-keyspace-events=KEA during integration tests.

^{Written by Cursor Bugbot for commit 6b6002f. This will update automatically on new commits. Configure here.}

[jit-ci]

Hi, I’m Jit, a friendly security platform designed to help developers build secure applications from day zero with an MVS (Minimal viable security) mindset.

In case there are security findings, they will be communicated to you as a comment inside the PR.

Hope you’ll enjoy using Jit.

Questions? Comments? Want to learn more? Get in touch with us.

[Copilot]

Pull request overview

Adds a new keyspace notifications abstraction to redis-py, including parsing helpers and a cluster-aware subscription manager intended to work across Redis Cluster primary nodes.

Changes:

• Introduces redis/keyspace_notifications.py with EventType, NotifyKeyspaceEvents, channel builders, KeyNotification parsing, and ClusterKeyspaceNotifications (+ worker thread).
• Exports the new API surface from redis/__init__.py.
• Adds unit/integration tests and a generation/requirements spec document.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 14 comments.

File	Description
redis/keyspace_notifications.py	New module implementing notification parsing, channel helpers, and a cluster-aware subscription manager with topology refresh + background worker.
redis/__init__.py	Re-exports the new keyspace notification classes/helpers at the package top-level.
tests/test_keyspace_notifications.py	Adds parsing/unit tests plus mocked cluster behavior tests and cluster usability tests.
specs/keyspace-notifications/SPEC.md	Adds a spec describing Redis keyspace notifications behavior and testing expectations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 10 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}