From e17587773c656ec7479ea500a442081b2f8b2120 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 11:38:26 +0100 Subject: [PATCH 1/9] fix(index): read cluster FT.INFO on RESP3 and initialise fresh async cluster clients The cluster branch of SearchIndex._info() and AsyncSearchIndex._info() sends a raw FT.INFO to one node, so redis-py's search parser never sees the reply. On RESP3, the redis-py 8 default, that reply is a map, and make_dict() raised KeyError: 1. Accept either shape. The async cluster client discovers its nodes on its first command, so on a fresh client get_random_node() raised IndexError and get_default_node() returned None. That broke create(), and delete() then failed with "'NoneType' object has no attribute 'connection_kwargs'". Initialise the client in _get_client(), and in _info() for callers that bypass it. --- redisvl/index/index.py | 14 ++- tests/unit/test_cluster_index_info.py | 143 ++++++++++++++++++++++++++ tests/unit/test_error_handling.py | 1 + tests/unit/test_index_exists.py | 1 + 4 files changed, 157 insertions(+), 2 deletions(-) create mode 100644 tests/unit/test_cluster_index_info.py diff --git a/redisvl/index/index.py b/redisvl/index/index.py index 6a2451fcb..c6f69abb8 100644 --- a/redisvl/index/index.py +++ b/redisvl/index/index.py @@ -2370,7 +2370,8 @@ def _info(name: str, redis_client: SyncRedisClient) -> dict[str, Any]: values = redis_client.execute_command( "FT.INFO", name, target_nodes=node ) - info = make_dict(values) + # A raw reply is a flat list on RESP2 and a map on RESP3. + info = values if isinstance(values, dict) else make_dict(values) else: info = redis_client.ft(name).info() return convert_bytes(info) @@ -2639,17 +2640,26 @@ async def _get_client(self) -> AsyncRedisClient: self._lib_name, ) self._validated_client = True + if isinstance(self._redis_client, AsyncRedisCluster): + # The async cluster client discovers its nodes on first use, so + # get_default_node() and get_random_node() find nothing on a fresh + # client. This is a no-op once the client is initialised. + await self._redis_client.initialize() return self._redis_client @staticmethod async def _info(name: str, redis_client: AsyncRedisClient) -> dict[str, Any]: try: if isinstance(redis_client, AsyncRedisCluster): + # Callers such as from_existing() pass a client that has not + # been through _get_client(), so initialise it here too. + await redis_client.initialize() node = redis_client.get_random_node() values = await redis_client.execute_command( "FT.INFO", name, target_nodes=node ) - info = make_dict(values) + # A raw reply is a flat list on RESP2 and a map on RESP3. + info = values if isinstance(values, dict) else make_dict(values) else: info = await redis_client.ft(name).info() return convert_bytes(info) diff --git a/tests/unit/test_cluster_index_info.py b/tests/unit/test_cluster_index_info.py new file mode 100644 index 000000000..970b6aae3 --- /dev/null +++ b/tests/unit/test_cluster_index_info.py @@ -0,0 +1,143 @@ +""" +Unit tests for the Redis Cluster branch of SearchIndex._info() and +AsyncSearchIndex._info(). + +On a cluster, _info() sends a raw FT.INFO to one node, so redis-py's search +parser never sees the reply and its shape depends on the wire protocol: a flat +list on RESP2, a map on RESP3 (the redis-py 8 default). Both must produce the +same index information. + +The async cluster client also discovers its nodes lazily, on its first command, +so a freshly built client has no node to pick. The live cluster suite covers +both cases but only runs with --run-cluster-tests, which CI never passes. +""" + +from unittest.mock import create_autospec + +import pytest +from redis.asyncio.cluster import ClusterNode as AsyncClusterNode +from redis.asyncio.cluster import RedisCluster as AsyncRedisCluster +from redis.cluster import ClusterNode, RedisCluster + +from redisvl.index import AsyncSearchIndex, SearchIndex +from redisvl.redis.connection import convert_index_info_to_schema +from redisvl.schema import IndexSchema + +INDEX_NAME = "my_index" + +# The same index as FT.INFO returns it on each protocol, trimmed to the +# sections from_existing() reads. +RESP2_REPLY = [ + b"index_name", + INDEX_NAME.encode(), + b"index_definition", + [b"key_type", b"HASH", b"prefixes", [b"doc"]], + b"attributes", + [[b"identifier", b"title", b"attribute", b"title", b"type", b"TEXT"]], + b"num_docs", + b"0", +] +RESP3_REPLY = { + b"index_name": INDEX_NAME.encode(), + b"index_definition": {b"key_type": b"HASH", b"prefixes": [b"doc"]}, + b"attributes": [ + { + b"identifier": b"title", + b"attribute": b"title", + b"type": b"TEXT", + b"flags": [], + } + ], + b"num_docs": 0, +} +REPLIES = pytest.mark.parametrize( + "reply", [RESP2_REPLY, RESP3_REPLY], ids=["resp2", "resp3"] +) + + +def _schema(): + return IndexSchema.from_dict( + { + "index": {"name": INDEX_NAME, "prefix": "doc"}, + "fields": [{"name": "title", "type": "text"}], + } + ) + + +def _sync_cluster(reply): + client = create_autospec(RedisCluster, instance=True) + client.get_random_node.return_value = create_autospec(ClusterNode, instance=True) + client.execute_command.return_value = reply + return client + + +def _fresh_async_cluster(reply=None): + """An async cluster client that, like a real one, knows no nodes until + initialize() has run.""" + client = create_autospec(AsyncRedisCluster, instance=True) + node = create_autospec(AsyncClusterNode, instance=True) + initialized = False + + async def initialize(): + nonlocal initialized + initialized = True + return client + + def get_random_node(): + if not initialized: + raise IndexError("Cannot choose from an empty sequence") + return node + + client.initialize.side_effect = initialize + client.get_random_node.side_effect = get_random_node + client.get_default_node.side_effect = lambda: node if initialized else None + client.execute_command.return_value = reply + return client, node + + +class TestClusterInfoReplyShape: + @REPLIES + def test_sync_info_reads_either_protocol(self, reply): + info = SearchIndex._info(INDEX_NAME, _sync_cluster(reply)) + + assert info["index_name"] == INDEX_NAME + assert convert_index_info_to_schema(info) == convert_index_info_to_schema( + SearchIndex._info(INDEX_NAME, _sync_cluster(RESP2_REPLY)) + ) + + @REPLIES + @pytest.mark.asyncio + async def test_async_info_reads_either_protocol(self, reply): + client, _ = _fresh_async_cluster(reply) + reference, _ = _fresh_async_cluster(RESP2_REPLY) + + info = await AsyncSearchIndex._info(INDEX_NAME, client) + + assert info["index_name"] == INDEX_NAME + assert convert_index_info_to_schema(info) == convert_index_info_to_schema( + await AsyncSearchIndex._info(INDEX_NAME, reference) + ) + + +class TestFreshAsyncClusterClient: + @pytest.mark.asyncio + async def test_info_initialises_before_choosing_a_node(self): + client, node = _fresh_async_cluster(RESP2_REPLY) + + info = await AsyncSearchIndex._info(INDEX_NAME, client) + + assert info["index_name"] == INDEX_NAME + client.execute_command.assert_awaited_once_with( + "FT.INFO", INDEX_NAME, target_nodes=node + ) + + @pytest.mark.asyncio + async def test_delete_targets_a_node_not_none(self): + client, node = _fresh_async_cluster() + index = AsyncSearchIndex(schema=_schema(), redis_client=client) + + await index.delete(drop=False) + + client.execute_command.assert_awaited_once_with( + "FT.DROPINDEX", INDEX_NAME, target_nodes=[node] + ) diff --git a/tests/unit/test_error_handling.py b/tests/unit/test_error_handling.py index 09b768a05..a1dc3da56 100644 --- a/tests/unit/test_error_handling.py +++ b/tests/unit/test_error_handling.py @@ -414,6 +414,7 @@ async def test_async_drop_documents_cluster_validation(self, mock_validate): # Create a mock that properly inherits from RedisCluster for isinstance check mock_cluster_client = Mock() mock_cluster_client.__class__ = AsyncRedisCluster + mock_cluster_client.initialize = AsyncMock() mock_cluster_client.delete = AsyncMock(return_value=2) index = AsyncSearchIndex(schema=schema, redis_client=mock_cluster_client) diff --git a/tests/unit/test_index_exists.py b/tests/unit/test_index_exists.py index b7bf30192..5a5b3105a 100644 --- a/tests/unit/test_index_exists.py +++ b/tests/unit/test_index_exists.py @@ -171,6 +171,7 @@ async def test_async_ft_info_is_routed_to_a_node(self): node = Mock() client = MagicMock() client.__class__ = AsyncRedisCluster # isinstance drives the branch + client.initialize = AsyncMock() client.get_random_node.return_value = node client.execute_command = AsyncMock(return_value=["index_name", INDEX_NAME]) index = AsyncSearchIndex(schema=_schema(), redis_client=client) From d4779044614de51303eecf5fb5ef185062d065cf Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 11:43:24 +0100 Subject: [PATCH 2/9] test(index): drop a cluster info test the parametrised case already covers --- tests/unit/test_cluster_index_info.py | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/tests/unit/test_cluster_index_info.py b/tests/unit/test_cluster_index_info.py index 970b6aae3..d6d5b3796 100644 --- a/tests/unit/test_cluster_index_info.py +++ b/tests/unit/test_cluster_index_info.py @@ -120,17 +120,6 @@ async def test_async_info_reads_either_protocol(self, reply): class TestFreshAsyncClusterClient: - @pytest.mark.asyncio - async def test_info_initialises_before_choosing_a_node(self): - client, node = _fresh_async_cluster(RESP2_REPLY) - - info = await AsyncSearchIndex._info(INDEX_NAME, client) - - assert info["index_name"] == INDEX_NAME - client.execute_command.assert_awaited_once_with( - "FT.INFO", INDEX_NAME, target_nodes=node - ) - @pytest.mark.asyncio async def test_delete_targets_a_node_not_none(self): client, node = _fresh_async_cluster() From efb00ec76071b4b4d72a84b03af70c85865c289f Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 12:39:46 +0100 Subject: [PATCH 3/9] fix(index): read cluster FT.INFO and FT._LIST from the default node _info() sent FT.INFO to get_random_node(), which picks from every node in the cluster, replicas included. FT.CREATE goes to the default node, a primary, and Redis replicates asynchronously, so a replica can answer "no such index" straight after create(). The nightly cluster job hit this on redis-py 8.1.0, with FT.INFO landing on the replica at port 7005. Ask the default node instead, the node FT.CREATE, FT.DROPINDEX and FT.SEARCH already use. Async listall() had the same random-node read and now does the same; sync listall() already reached the default node through redis-py's keyless routing. --- redisvl/index/index.py | 17 +++++++---- tests/unit/test_cluster_index_info.py | 43 ++++++++++++++++++++++----- tests/unit/test_index_exists.py | 8 ++--- 3 files changed, 51 insertions(+), 17 deletions(-) diff --git a/redisvl/index/index.py b/redisvl/index/index.py index c6f69abb8..993f341d9 100644 --- a/redisvl/index/index.py +++ b/redisvl/index/index.py @@ -2366,7 +2366,9 @@ def _info(name: str, redis_client: SyncRedisClient) -> dict[str, Any]: """Run FT.INFO to fetch information about the index.""" try: if isinstance(redis_client, SyncRedisCluster): - node = redis_client.get_random_node() + # Ask the node FT.CREATE and FT.DROPINDEX go to. A replica + # learns of a new index only once replication catches up. + node = redis_client.get_default_node() values = redis_client.execute_command( "FT.INFO", name, target_nodes=node ) @@ -2642,8 +2644,8 @@ async def _get_client(self) -> AsyncRedisClient: self._validated_client = True if isinstance(self._redis_client, AsyncRedisCluster): # The async cluster client discovers its nodes on first use, so - # get_default_node() and get_random_node() find nothing on a fresh - # client. This is a no-op once the client is initialised. + # get_default_node() returns None on a fresh client. This is a + # no-op once the client is initialised. await self._redis_client.initialize() return self._redis_client @@ -2654,7 +2656,9 @@ async def _info(name: str, redis_client: AsyncRedisClient) -> dict[str, Any]: # Callers such as from_existing() pass a client that has not # been through _get_client(), so initialise it here too. await redis_client.initialize() - node = redis_client.get_random_node() + # Ask the node FT.CREATE and FT.DROPINDEX go to. A replica + # learns of a new index only once replication catches up. + node = redis_client.get_default_node() values = await redis_client.execute_command( "FT.INFO", name, target_nodes=node ) @@ -3705,8 +3709,9 @@ async def listall(self) -> list[str]: """ client = await self._get_client() if isinstance(client, AsyncRedisCluster): - target_nodes = client.get_random_node() - return convert_bytes(await target_nodes.execute_command("FT._LIST")) + # The default node, as in _info(): a replica may lag behind. + node = client.get_default_node() + return convert_bytes(await node.execute_command("FT._LIST")) else: return convert_bytes(await client.execute_command("FT._LIST")) diff --git a/tests/unit/test_cluster_index_info.py b/tests/unit/test_cluster_index_info.py index d6d5b3796..22879c732 100644 --- a/tests/unit/test_cluster_index_info.py +++ b/tests/unit/test_cluster_index_info.py @@ -7,9 +7,14 @@ list on RESP2, a map on RESP3 (the redis-py 8 default). Both must produce the same index information. +_info() must also ask the node that FT.CREATE went to, the default node: a +replica learns of a new index only once replication catches up, so a replica +can answer "no such index" straight after create(). The stand-in clients below +model that with a replica that never has the index. + The async cluster client also discovers its nodes lazily, on its first command, so a freshly built client has no node to pick. The live cluster suite covers -both cases but only runs with --run-cluster-tests, which CI never passes. +these cases but only runs with --run-cluster-tests, which CI never passes. """ from unittest.mock import create_autospec @@ -18,6 +23,7 @@ from redis.asyncio.cluster import ClusterNode as AsyncClusterNode from redis.asyncio.cluster import RedisCluster as AsyncRedisCluster from redis.cluster import ClusterNode, RedisCluster +from redis.exceptions import ResponseError from redisvl.index import AsyncSearchIndex, SearchIndex from redisvl.redis.connection import convert_index_info_to_schema @@ -64,10 +70,23 @@ def _schema(): ) +def _answer_from_primary(primary, reply): + """FT.INFO that only the primary can answer: the replica has not caught up.""" + + def execute_command(*args, target_nodes=None): + if target_nodes not in (primary, [primary]): + raise ResponseError(f"{INDEX_NAME}: no such index") + return reply + + return execute_command + + def _sync_cluster(reply): client = create_autospec(RedisCluster, instance=True) + primary = create_autospec(ClusterNode, instance=True) + client.get_default_node.return_value = primary client.get_random_node.return_value = create_autospec(ClusterNode, instance=True) - client.execute_command.return_value = reply + client.execute_command.side_effect = _answer_from_primary(primary, reply) return client @@ -75,7 +94,8 @@ def _fresh_async_cluster(reply=None): """An async cluster client that, like a real one, knows no nodes until initialize() has run.""" client = create_autospec(AsyncRedisCluster, instance=True) - node = create_autospec(AsyncClusterNode, instance=True) + primary = create_autospec(AsyncClusterNode, instance=True) + replica = create_autospec(AsyncClusterNode, instance=True) initialized = False async def initialize(): @@ -86,13 +106,15 @@ async def initialize(): def get_random_node(): if not initialized: raise IndexError("Cannot choose from an empty sequence") - return node + return replica client.initialize.side_effect = initialize client.get_random_node.side_effect = get_random_node - client.get_default_node.side_effect = lambda: node if initialized else None - client.execute_command.return_value = reply - return client, node + client.get_default_node.side_effect = lambda: primary if initialized else None + client.execute_command.side_effect = _answer_from_primary(primary, reply) + primary.execute_command.return_value = [INDEX_NAME.encode()] + replica.execute_command.return_value = [] + return client, primary class TestClusterInfoReplyShape: @@ -130,3 +152,10 @@ async def test_delete_targets_a_node_not_none(self): client.execute_command.assert_awaited_once_with( "FT.DROPINDEX", INDEX_NAME, target_nodes=[node] ) + + @pytest.mark.asyncio + async def test_listall_sees_a_new_index(self): + client, _ = _fresh_async_cluster() + index = AsyncSearchIndex(schema=_schema(), redis_client=client) + + assert await index.listall() == [INDEX_NAME] diff --git a/tests/unit/test_index_exists.py b/tests/unit/test_index_exists.py index 5a5b3105a..fae2b306f 100644 --- a/tests/unit/test_index_exists.py +++ b/tests/unit/test_index_exists.py @@ -147,8 +147,8 @@ async def test_async_index_name_resolving_elsewhere_returns_false(self): class TestExistsOnCluster: """On a cluster, exists() must go through _info()'s node-targeted path. - Index metadata is cluster-wide, so any single node can answer -- but the - command has to carry target_nodes to get there. These are the only cluster + The command has to carry target_nodes, and it must name the default node, + where FT.CREATE goes: a replica may not have the new index yet. These are the only cluster checks that run by default; the live cluster suite needs --run-cluster-tests. Sync and async _info() each have their own cluster branch, and exists() reaches both for the first time with this change. @@ -157,7 +157,7 @@ class TestExistsOnCluster: def test_ft_info_is_routed_to_a_node(self): node = Mock() client = MagicMock(spec=RedisCluster) - client.get_random_node.return_value = node + client.get_default_node.return_value = node client.execute_command.return_value = ["index_name", INDEX_NAME] index = SearchIndex(schema=_schema(), redis_client=client) @@ -172,7 +172,7 @@ async def test_async_ft_info_is_routed_to_a_node(self): client = MagicMock() client.__class__ = AsyncRedisCluster # isinstance drives the branch client.initialize = AsyncMock() - client.get_random_node.return_value = node + client.get_default_node.return_value = node client.execute_command = AsyncMock(return_value=["index_name", INDEX_NAME]) index = AsyncSearchIndex(schema=_schema(), redis_client=client) From c688b1d0a822181af4a5794d17bc5f8996142345 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 12:47:46 +0100 Subject: [PATCH 4/9] fix(index): send sync cluster listall() to the default node The previous commit said sync listall() already reached the default node through redis-py's keyless routing. That holds only on redis-py 6.x. On 7.x and 8.x, FT._LIST has no routing entry, so a keyless call on a cluster raises RedisClusterException ("No way to dispatch this command to Redis Cluster. Missing key"). Target the default node explicitly, as the async twin and _info() do. --- redisvl/index/index.py | 7 +++++++ tests/unit/test_cluster_index_info.py | 8 ++++++++ 2 files changed, 15 insertions(+) diff --git a/redisvl/index/index.py b/redisvl/index/index.py index 993f341d9..9128636c0 100644 --- a/redisvl/index/index.py +++ b/redisvl/index/index.py @@ -2336,6 +2336,13 @@ def listall(self) -> list[str]: Returns: List[str]: The list of indices in the database. """ + if isinstance(self._redis_client, SyncRedisCluster): + # redis-py 7+ cannot route a keyless FT._LIST on a cluster, and a + # replica may lag behind, so ask the default node, as in _info(). + node = self._redis_client.get_default_node() + return convert_bytes( + self._redis_client.execute_command("FT._LIST", target_nodes=node) + ) return convert_bytes(self._redis_client.execute_command("FT._LIST")) def exists(self) -> bool: diff --git a/tests/unit/test_cluster_index_info.py b/tests/unit/test_cluster_index_info.py index 22879c732..c8031e5c3 100644 --- a/tests/unit/test_cluster_index_info.py +++ b/tests/unit/test_cluster_index_info.py @@ -153,9 +153,17 @@ async def test_delete_targets_a_node_not_none(self): "FT.DROPINDEX", INDEX_NAME, target_nodes=[node] ) + +class TestListallOnCluster: @pytest.mark.asyncio async def test_listall_sees_a_new_index(self): client, _ = _fresh_async_cluster() index = AsyncSearchIndex(schema=_schema(), redis_client=client) assert await index.listall() == [INDEX_NAME] + + def test_sync_listall_sees_a_new_index(self): + client = _sync_cluster([INDEX_NAME.encode()]) + index = SearchIndex(schema=_schema(), redis_client=client) + + assert index.listall() == [INDEX_NAME] From 1a85721bb2114e59f7a69b90fd36a6c8a363b6ff Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 12:55:54 +0100 Subject: [PATCH 5/9] test(cluster): seed aclear multipage test with one amset The test seeded 600 keys with 600 concurrent aset() calls, each a single-key pipeline. On redis-py 8.x, whose async cluster defaults to 100 connections per node, that raised MaxConnectionsError on slow connects; the 8.1.0 pipeline retry then closed the shared client and tore down other coroutines' connections mid-handshake, failing with "'NoneType' object has no attribute 'writelines'" on Python 3.11. Seed with a single amset() instead. The comment that amset writes nothing on an async cluster was stale: #697 fixed that. --- .../integration/test_redis_cluster_support.py | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/tests/integration/test_redis_cluster_support.py b/tests/integration/test_redis_cluster_support.py index 76c0fcb00..57913b958 100644 --- a/tests/integration/test_redis_cluster_support.py +++ b/tests/integration/test_redis_cluster_support.py @@ -1,7 +1,5 @@ """Tests for Redis Cluster support in RedisVL.""" -import asyncio - import pytest from redis import Redis from redis.asyncio.cluster import RedisCluster as AsyncRedisCluster @@ -408,19 +406,18 @@ async def test_embeddings_cache_aclear_multipage_cluster( pipe.set(f"{noise_prefix}:{i}", "keep") await pipe.execute() - # Seeded with aset, not amset: amset silently writes nothing on an - # async cluster client (it awaits the pipeline returned by the queueing - # call, which drains the queue). That is a separate bug; this test is - # about aclear, so don't let it depend on the broken path. - await asyncio.gather( - *( - cache.aset( - content=f"content-{i}", - model_name="test", - embedding=[0.1, 0.2, 0.3], - ) + # Seed with one amset (one pipeline), not concurrent asets: hundreds of + # pipelines in flight exceed redis-py 8's default of 100 connections + # per node, and its pipeline retry then closes the shared client. + await cache.amset( + [ + { + "content": f"content-{i}", + "model_name": "test", + "embedding": [0.1, 0.2, 0.3], + } for i in range(CLEAR_CACHE_KEYS) - ) + ] ) assert await _acount_keys(cluster_client, f"{name}:*") == CLEAR_CACHE_KEYS From 7dfb30d038e9ced63ad8a90a288d0bd6489ecd7b Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 11:52:08 +0100 Subject: [PATCH 6/9] ci: run the Redis Cluster tests nightly Add a cluster-tests job to the test workflow that runs every requires_cluster test on the nightly schedule and on manual dispatch, across redis-py 6.x, 7.x and 8.x. None of these tests has run in CI before. The cluster nodes announce host.docker.internal, which Linux Docker Engine does not resolve. Map it to the host gateway inside each node, and to loopback on the runner, so the nodes can gossip and the client can follow MOVED redirects. The job runs serially because the cluster publishes fixed ports. Co-Authored-By: Claude --- .github/workflows/test.yml | 77 ++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 +- tests/cluster-compose.yml | 20 ++++++++++ 3 files changed, 98 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c95f7a7e7..2d4543861 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -142,6 +142,83 @@ jobs: run: | make test + cluster-tests: + name: Cluster Tests - redis-py ${{ matrix.redis-py-version }} + # Nightly and on demand only, to keep the cluster's setup time off PRs. + # Every other job runs `make test`, which skips `requires_cluster` tests. + if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' + runs-on: ubuntu-latest + env: + HF_HOME: ${{ github.workspace }}/hf_cache + REDIS_PY_VERSION: ${{ matrix.redis-py-version }} + # Required: without it `uv run` re-syncs the venv to uv.lock and reverts + # the redis-py pin set below. + UV_NO_SYNC: "1" + strategy: + fail-fast: false + matrix: + # Cluster replies differ by redis-py version (8.x defaults to RESP3), + # so cover each major the `test` job does. The Redis image is pinned + # in tests/cluster-compose.yml. + redis-py-version: ["6.x", "7.x", "8.x"] + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Cache HuggingFace Models + uses: actions/cache@v4 + with: + path: hf_cache + key: ${{ runner.os }}-hf-cache + + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION }} + + - name: Install uv + uses: astral-sh/setup-uv@v10.0.0 + with: + version: ${{ env.UV_VERSION }} + enable-cache: true + python-version: ${{ env.PYTHON_VERSION }} # sets UV_PYTHON + cache-dependency-glob: | + pyproject.toml + uv.lock + + - name: Install dependencies + run: | + set -euo pipefail + + uv sync --all-extras --frozen + + # Keep in sync with the `test` job's install rules. + case "$REDIS_PY_VERSION" in + "6.x") spec="redis>=6,<7" ;; + "7.x") spec="redis>=7,<8" ;; + "8.x") spec="redis>=8.1,<9" ;; + *) + echo "::error title=Unhandled redis-py-version::Matrix value '${REDIS_PY_VERSION}' has no install rule -- add a case branch in .github/workflows/test.yml." + exit 1 + ;; + esac + + uv pip install "$spec" + uv run python -c 'import redis; print("redis-py:", redis.__version__)' + + - name: Resolve host.docker.internal on the runner + # The cluster nodes announce host.docker.internal (see + # tests/cluster-compose.yml), so MOVED redirects point the test client + # there. Linux runners do not resolve that name by default. + run: | + echo "127.0.0.1 host.docker.internal" | sudo tee -a /etc/hosts + + - name: Run cluster tests + # -n 0: the cluster publishes fixed ports 7001-7006, so per-worker + # clusters under xdist would collide. + run: | + uv run python -m pytest -n 0 --log-level=CRITICAL --run-cluster-tests -m requires_cluster tests/ + notebooks: name: Notebook Validation runs-on: ubuntu-latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73e9f2e9a..98d6a0b6f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -187,7 +187,7 @@ belonging to other workers and other pull requests' CI runs. See the module docstring in `tests/integration/test_langcache_semantic_cache_integration.py` for a worked example. -**Note:** Tests marked `requires_cluster` only run when you pass `--run-cluster-tests`. The cluster itself is provisioned for you by the `redis_cluster_container` fixture in `tests/conftest.py`, so Docker needs to be running. +**Note:** Tests marked `requires_cluster` only run when you pass `--run-cluster-tests`. The cluster itself is provisioned for you by the `redis_cluster_container` fixture in `tests/conftest.py`, so Docker needs to be running. The nodes announce themselves as `host.docker.internal`, so the host running the tests must resolve that name too: add `127.0.0.1 host.docker.internal` to `/etc/hosts` if it doesn't already. CI runs these tests nightly, in the `cluster-tests` job of `.github/workflows/test.yml`, not on pull requests. ## Documentation diff --git a/tests/cluster-compose.yml b/tests/cluster-compose.yml index ba7592366..62302cb18 100644 --- a/tests/cluster-compose.yml +++ b/tests/cluster-compose.yml @@ -1,3 +1,11 @@ +# Every node announces host.docker.internal, which is the address it gossips to +# its peers and hands to clients in MOVED redirects, so the name has to resolve +# both inside the containers and on the host running the tests. +# - Inside: Docker Desktop provides the name; Linux Docker Engine (GitHub's +# ubuntu runners) needs the `extra_hosts` mapping on each node below. +# - On the host: add `127.0.0.1 host.docker.internal` to the hosts file, as the +# `cluster-tests` job in .github/workflows/test.yml does. macOS does not +# resolve the name by default either. services: redis-node-1: image: "redis:8.4" @@ -12,6 +20,8 @@ services: - --cluster-announce-port 7001 - --cluster-announce-bus-port 17001 - --protected-mode no + extra_hosts: + - "host.docker.internal:host-gateway" ports: - "7001:7001" - "17001:17001" @@ -31,6 +41,8 @@ services: - --cluster-announce-port 7002 - --cluster-announce-bus-port 17002 - --protected-mode no + extra_hosts: + - "host.docker.internal:host-gateway" ports: - "7002:7002" - "17002:17002" @@ -50,6 +62,8 @@ services: - --cluster-announce-port 7003 - --cluster-announce-bus-port 17003 - --protected-mode no + extra_hosts: + - "host.docker.internal:host-gateway" ports: - "7003:7003" - "17003:17003" @@ -69,6 +83,8 @@ services: - --cluster-announce-port 7004 - --cluster-announce-bus-port 17004 - --protected-mode no + extra_hosts: + - "host.docker.internal:host-gateway" ports: - "7004:7004" - "17004:17004" @@ -88,6 +104,8 @@ services: - --cluster-announce-port 7005 - --cluster-announce-bus-port 17005 - --protected-mode no + extra_hosts: + - "host.docker.internal:host-gateway" ports: - "7005:7005" - "17005:17005" @@ -107,6 +125,8 @@ services: - --cluster-announce-port 7006 - --cluster-announce-bus-port 17006 - --protected-mode no + extra_hosts: + - "host.docker.internal:host-gateway" ports: - "7006:7006" - "17006:17006" From 5a27c94797fe18331ba41315c6e2ba48ed2901dc Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 12:10:15 +0100 Subject: [PATCH 7/9] fix(tests): let the nightly cluster job set up cleanly Two problems would have failed every leg of the new cluster job: - redis_cluster_container exported COMPOSE_PROJECT_NAME. Under -m requires_cluster, a cluster test runs before anything resolves redis_url, which then looked up the standalone redis service in the cluster's compose project and raised ContainerIsNotRunning. Every command in the fixture already passes -p, so stop exporting it. - redis-cluster-setup lacked the host.docker.internal mapping, but redis-cli --cluster create reconnects to the nodes at their announced address, so cluster creation could not finish on Linux. Also correct a workflow comment, and update AGENTS.md and the pre-PR review references, which said cluster tests never run in CI. Co-Authored-By: Claude --- .agents/skills/pre-pr-review/references/correctness.md | 2 +- .agents/skills/pre-pr-review/references/tests.md | 2 +- .github/workflows/test.yml | 3 ++- AGENTS.md | 2 +- tests/cluster-compose.yml | 6 +++++- tests/conftest.py | 7 ++++--- 6 files changed, 14 insertions(+), 8 deletions(-) diff --git a/.agents/skills/pre-pr-review/references/correctness.md b/.agents/skills/pre-pr-review/references/correctness.md index 3a77f1ca7..a40c5a6c4 100644 --- a/.agents/skills/pre-pr-review/references/correctness.md +++ b/.agents/skills/pre-pr-review/references/correctness.md @@ -16,7 +16,7 @@ Find changes that make the code behave wrongly for some input, state or environm - **Dependency floors.** Check every call into an optional dependency against the oldest version `pyproject.toml` allows. A new attribute or keyword that only exists in a later release crashes users on the floor version. This is the most common high-severity finding in this repository. - **Redis replies.** The code has to handle RESP2 and RESP3 reply shapes, and both hash and JSON storage. - **Result limits.** Default result counts (`num_results`, `LIMIT`, `MAXSEARCHRESULTS`) silently truncate. Check any read that is meant to return everything. -- **Cluster mode.** Multi-key operations, `SCAN` and pipelines behave differently on a cluster, and partial failures are possible. CI never runs cluster tests, so reason about these cases from the code. If you can't settle one that way, put it under "Not verified" in the Reviewer Brief. +- **Cluster mode.** Multi-key operations, `SCAN` and pipelines behave differently on a cluster, and partial failures are possible. Pull-request CI never runs cluster tests (they run only nightly), so reason about these cases from the code. If you can't settle one that way, put it under "Not verified" in the Reviewer Brief. - **Client ownership.** Who creates, owns and closes a Redis client, and what happens on reconnect, especially for async clients reused across event loops. ## Depth diff --git a/.agents/skills/pre-pr-review/references/tests.md b/.agents/skills/pre-pr-review/references/tests.md index 927be5c10..efdaf815b 100644 --- a/.agents/skills/pre-pr-review/references/tests.md +++ b/.agents/skills/pre-pr-review/references/tests.md @@ -6,7 +6,7 @@ Check that the tests prove the change works, cover the paths that matter, and ad - **Vacuous tests.** A regression test that passes without the fix. Revert the fix mentally, or actually, and check that the test fails for the right reason, not because of an unrelated error earlier in setup. A test that builds an object which fails before reaching the code under test proves nothing. - **Missing critical paths.** Error paths, boundary values (empty, one, exactly the limit, one past it), both the sync and async variants, and both hash and JSON storage, where the change touches them. -- **Areas CI can't reach.** `requires_cluster` tests are skipped in CI, and `requires_api_keys` tests only run with keys. If the change is in one of those areas, ask for a hermetic unit test, using mocks or a fake client, that pins the behaviour. Otherwise, make sure the Reviewer Brief lists it under "Not verified". +- **Areas CI can't reach.** `requires_cluster` tests are skipped in pull-request CI (they run only nightly), and `requires_api_keys` tests only run with keys. If the change is in one of those areas, ask for a hermetic unit test, using mocks or a fake client, that pins the behaviour. Otherwise, make sure the Reviewer Brief lists it under "Not verified". - **Weakened assertions.** Loosened expectations, added skips or broader `pytest.raises` that make a failing test pass rather than fixing the code. - **Bloat.** Parametrisation that multiplies cases without covering new behaviour; several tests asserting the same thing; tests of trivial getters or of library code. Also tests that pin incidental details such as exact log text or wire format, which make refactoring expensive. - **Placement.** Pure logic belongs in `tests/unit/`, and anything needing Redis in `tests/integration/`. Integration tests share a container, so check that new ones clean up their keys and indexes. diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 2d4543861..19a449fa9 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -145,7 +145,8 @@ jobs: cluster-tests: name: Cluster Tests - redis-py ${{ matrix.redis-py-version }} # Nightly and on demand only, to keep the cluster's setup time off PRs. - # Every other job runs `make test`, which skips `requires_cluster` tests. + # No other job passes `--run-cluster-tests`, so this is the only one that + # runs `requires_cluster` tests. if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' runs-on: ubuntu-latest env: diff --git a/AGENTS.md b/AGENTS.md index 0528bb8b5..1025910be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -158,4 +158,4 @@ Cursor Bugbot reviews every PR, and humans may comment too. Handle each point as ## Honesty rules - Never claim a check in the Reviewer Brief unless you ran it and saw its output. -- Say what you didn't check. Cluster tests and tests that need API keys don't run in CI, so name them when the change touches those paths. +- Say what you didn't check. Cluster tests don't run in pull-request CI (only nightly), and tests that need API keys don't run in CI, so name them when the change touches those paths. diff --git a/tests/cluster-compose.yml b/tests/cluster-compose.yml index 62302cb18..9ea9258a9 100644 --- a/tests/cluster-compose.yml +++ b/tests/cluster-compose.yml @@ -2,7 +2,7 @@ # its peers and hands to clients in MOVED redirects, so the name has to resolve # both inside the containers and on the host running the tests. # - Inside: Docker Desktop provides the name; Linux Docker Engine (GitHub's -# ubuntu runners) needs the `extra_hosts` mapping on each node below. +# ubuntu runners) needs the `extra_hosts` mapping on every container below. # - On the host: add `127.0.0.1 host.docker.internal` to the hosts file, as the # `cluster-tests` job in .github/workflows/test.yml does. macOS does not # resolve the name by default either. @@ -135,6 +135,10 @@ services: redis-cluster-setup: image: "redis:8.4" + # `redis-cli --cluster create` reconnects to every node at its announced + # address once the nodes have met, so this container needs the name too. + extra_hosts: + - "host.docker.internal:host-gateway" depends_on: - redis-node-1 - redis-node-2 diff --git a/tests/conftest.py b/tests/conftest.py index 2a002af17..279e7b10f 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -81,9 +81,10 @@ def redis_cluster_container(worker_id): compose_file = os.path.join( os.environ.get("GITHUB_WORKSPACE", pwd), "tests", "cluster-compose.yml" ) - os.environ["COMPOSE_PROJECT_NAME"] = ( - project_name # For docker compose to pick it up if needed - ) + # Every command below passes `-p project_name`. Don't export it as + # COMPOSE_PROJECT_NAME: `redis_container`'s testcontainers commands read + # that variable, so `redis_url` would then look for the standalone `redis` + # service in the cluster's project and fail. # Cluster tests use a pinned Redis 8 image for consistency. os.environ.setdefault("REDIS_IMAGE", "redis:8.4") From d5d2bef1c891edbc27e232367b299d4deeba67a8 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Thu, 12 Nov 2026 13:55:07 +0100 Subject: [PATCH 8/9] docs(concepts): describe index commands after a Redis Cluster failover Index commands go to redis-py's default node, which redis-py re-points only after a keyed command is redirected or a connection fails. Until then, writes fail with ReadOnlyError and reads come from the demoted node. Say so, and how to recover. --- docs/concepts/search-and-indexing.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/concepts/search-and-indexing.md b/docs/concepts/search-and-indexing.md index 5cab8733b..9c20308f7 100644 --- a/docs/concepts/search-and-indexing.md +++ b/docs/concepts/search-and-indexing.md @@ -97,6 +97,15 @@ This is a short indexing delay, not data loss. A later query sees the documents Applications that require strict search read-after-write behavior can start Redis with `--search-workers 0`. This is a Redis server setting, not a RedisVL option: it keeps indexing in the foreground but gives up the throughput benefits of multithreaded background indexing. +## Index Commands After a Cluster Failover + +On Redis Cluster, index commands carry no key, so RedisVL sends them to the client's default node: a primary that redis-py picks when it connects. That covers `create()`, `delete()`, `exists()`, `info()`, `listall()` and queries. redis-py learns that a failover has happened only when a keyed command is redirected with `MOVED`, or when a connection fails. Until then, a client that has sent only index commands since the failover keeps sending them to the demoted node, which is now a replica: + +- `create()` and `delete()` fail with `ReadOnlyError`. +- `exists()`, `info()`, `listall()` and queries are answered by the replica. Replication is asynchronous, so its copy can lag behind the new primary: a new index can be reported missing, or a dropped one still present. + +This lasts until the client sends any keyed command, such as `load()` or `fetch()`, or reconnects. Most applications send keyed commands constantly. A process that only manages indexes can recover from a `ReadOnlyError` by building a new client and retrying. + ## Bulk Delete and Update Redis has no server-side "delete/update by query", so mutating many documents traditionally means scanning for keys and issuing writes yourself. RedisVL wraps that pattern behind two filter-driven methods (available on both `SearchIndex` and `AsyncSearchIndex`). From aeb60083666f8cc29e86978384e455ebee9e7df7 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 12:55:54 +0100 Subject: [PATCH 9/9] test(cluster): seed aclear multipage test with one amset The test seeded 600 keys with 600 concurrent aset() calls, each a single-key pipeline. On redis-py 8.x, whose async cluster defaults to 100 connections per node, that raised MaxConnectionsError on slow connects; the 8.1.0 pipeline retry then closed the shared client and tore down other coroutines' connections mid-handshake, failing with "'NoneType' object has no attribute 'writelines'" on Python 3.11. Seed with a single amset() instead. The comment that amset writes nothing on an async cluster was stale: #697 fixed that. --- .../integration/test_redis_cluster_support.py | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/tests/integration/test_redis_cluster_support.py b/tests/integration/test_redis_cluster_support.py index 76c0fcb00..57913b958 100644 --- a/tests/integration/test_redis_cluster_support.py +++ b/tests/integration/test_redis_cluster_support.py @@ -1,7 +1,5 @@ """Tests for Redis Cluster support in RedisVL.""" -import asyncio - import pytest from redis import Redis from redis.asyncio.cluster import RedisCluster as AsyncRedisCluster @@ -408,19 +406,18 @@ async def test_embeddings_cache_aclear_multipage_cluster( pipe.set(f"{noise_prefix}:{i}", "keep") await pipe.execute() - # Seeded with aset, not amset: amset silently writes nothing on an - # async cluster client (it awaits the pipeline returned by the queueing - # call, which drains the queue). That is a separate bug; this test is - # about aclear, so don't let it depend on the broken path. - await asyncio.gather( - *( - cache.aset( - content=f"content-{i}", - model_name="test", - embedding=[0.1, 0.2, 0.3], - ) + # Seed with one amset (one pipeline), not concurrent asets: hundreds of + # pipelines in flight exceed redis-py 8's default of 100 connections + # per node, and its pipeline retry then closes the shared client. + await cache.amset( + [ + { + "content": f"content-{i}", + "model_name": "test", + "embedding": [0.1, 0.2, 0.3], + } for i in range(CLEAR_CACHE_KEYS) - ) + ] ) assert await _acount_keys(cluster_client, f"{name}:*") == CLEAR_CACHE_KEYS