feat(#143): add Redis Sentinel support for async implementations (#166)

* feat(#143): add Redis Sentinel support for async configure_client()

Replace AsyncRedis.from_url() with RedisConnectionFactory.get_async_redis_connection()
in AsyncRedisSaver, AsyncShallowRedisSaver, and AsyncRedisStore. This enables
redis+sentinel:// URLs for automatic master discovery via Redis Sentinel.

Sync implementations already used RedisConnectionFactory and worked with Sentinel.
Updated docstrings across all 6 classes to document Sentinel URL support.

* test(#143): add Sentinel integration tests and Docker Compose infrastructure

Add tests/sentinel/docker-compose.yml with Redis master (port 6399) and Sentinel
(port 26399). Add 12 integration tests covering all saver/store types via Sentinel,
cross-connection data verification, and configure_client factory delegation.

Add --run-sentinel-tests CLI flag and `make test-sentinel` target. Sentinel tests
run separately from the main suite to avoid Docker resource contention.

* chore: migrate test infrastructure to redis:8 and fix test fixtures

- Default test image from redis/redis-stack-server:latest to redis:8
- Fix test_key_registry_integration.py to use shared Docker Compose container
  instead of standalone RedisContainer (which timed out on startup)
- Update error message assertions for RedisConnectionFactory's message format
- Fix pyproject.toml warning filter for removed LangGraphDeprecatedSinceV10 class

Author: bsbodden

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install format lint test test-all clean redis-start redis-stop check-types check
+.PHONY: install format lint test test-all test-sentinel clean redis-start redis-stop check-types check
 
 install:
 	poetry install --all-extras
@@ -24,6 +24,9 @@ test:
 test-all:
 	poetry run test-verbose --run-api-tests
 
+test-sentinel:
+	poetry run python -m pytest tests/test_sentinel_integration.py -vv -s --run-sentinel-tests
+
 test-coverage:
 	poetry run test-coverage
 

langgraph/checkpoint/redis/__init__.py

@@ -54,7 +54,11 @@
 
 
 class RedisSaver(BaseRedisSaver[Union[Redis, RedisCluster], SearchIndex]):
-    """Standard Redis implementation for checkpoint saving."""
+    """Standard Redis implementation for checkpoint saving.
+
+    Supports standard Redis URLs (redis://), SSL (rediss://), and
+    Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+    """
 
     _redis: Union[Redis, RedisCluster]  # Support both standalone and cluster clients
     # Whether to assume the Redis server is a cluster; None triggers auto-detection
@@ -94,7 +98,11 @@ def configure_client(
         redis_client: Optional[Union[Redis, RedisCluster]] = None,
         connection_args: Optional[Dict[str, Any]] = None,
     ) -> None:
-        """Configure the Redis client."""
+        """Configure the Redis client.
+
+        Supports standard Redis URLs (redis://), SSL (rediss://), and
+        Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+        """
         from redis.exceptions import ResponseError
 
         from langgraph.checkpoint.redis.version import __full_lib_name__

langgraph/checkpoint/redis/aio.py

@@ -5,7 +5,6 @@
 import asyncio
 import json
 import logging
-import os
 from collections import defaultdict
 from contextlib import asynccontextmanager
 from types import TracebackType
@@ -39,6 +38,7 @@
 from redisvl.index import AsyncSearchIndex
 from redisvl.query import FilterQuery
 from redisvl.query.filter import Num, Tag
+from redisvl.redis.connection import RedisConnectionFactory
 from ulid import ULID
 
 from langgraph.checkpoint.redis.base import (
@@ -64,7 +64,11 @@
 class AsyncRedisSaver(
     BaseRedisSaver[Union[AsyncRedis, AsyncRedisCluster], AsyncSearchIndex]
 ):
-    """Async Redis implementation for checkpoint saver."""
+    """Async Redis implementation for checkpoint saver.
+
+    Supports standard Redis URLs (redis://), SSL (rediss://), and
+    Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+    """
 
     _redis_url: str
     checkpoints_index: AsyncSearchIndex
@@ -111,15 +115,17 @@ def configure_client(
         redis_client: Optional[Union[AsyncRedis, AsyncRedisCluster]] = None,
         connection_args: Optional[Dict[str, Any]] = None,
     ) -> None:
-        """Configure the Redis client."""
+        """Configure the Redis client.
+
+        Supports standard Redis URLs (redis://), SSL (rediss://), and
+        Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+        """
         self._owns_its_client = redis_client is None
 
         if redis_client is None:
-            if not redis_url:
-                redis_url = os.environ.get("REDIS_URL")
-                if not redis_url:
-                    raise ValueError("REDIS_URL env var not set")
-            self._redis = AsyncRedis.from_url(redis_url, **(connection_args or {}))
+            self._redis = RedisConnectionFactory.get_async_redis_connection(
+                redis_url, **(connection_args or {})
+            )
         else:
             self._redis = redis_client
 

langgraph/checkpoint/redis/ashallow.py

@@ -4,7 +4,6 @@
 
 import asyncio
 import json
-import os
 import time
 from contextlib import asynccontextmanager
 from datetime import datetime
@@ -26,6 +25,7 @@
 from redisvl.index import AsyncSearchIndex
 from redisvl.query import FilterQuery
 from redisvl.query.filter import Num, Tag
+from redisvl.redis.connection import RedisConnectionFactory
 from ulid import ULID
 
 from langgraph.checkpoint.redis.base import (
@@ -44,7 +44,11 @@
 
 
 class AsyncShallowRedisSaver(BaseRedisSaver[AsyncRedis, AsyncSearchIndex]):
-    """Async Redis implementation that only stores the most recent checkpoint."""
+    """Async Redis implementation that only stores the most recent checkpoint.
+
+    Supports standard Redis URLs (redis://), SSL (rediss://), and
+    Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+    """
 
     _redis_url: str
     checkpoints_index: AsyncSearchIndex
@@ -674,15 +678,17 @@ def configure_client(
         redis_client: Optional[AsyncRedis] = None,
         connection_args: Optional[dict[str, Any]] = None,
     ) -> None:
-        """Configure the Redis client."""
+        """Configure the Redis client.
+
+        Supports standard Redis URLs (redis://), SSL (rediss://), and
+        Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+        """
         self._owns_its_client = redis_client is None
 
         if redis_client is None:
-            if not redis_url:
-                redis_url = os.environ.get("REDIS_URL")
-                if not redis_url:
-                    raise ValueError("REDIS_URL env var not set")
-            self._redis = AsyncRedis.from_url(redis_url, **(connection_args or {}))
+            self._redis = RedisConnectionFactory.get_async_redis_connection(
+                redis_url, **(connection_args or {})
+            )
         else:
             self._redis = redis_client
 

langgraph/checkpoint/redis/shallow.py

@@ -46,7 +46,11 @@
 
 
 class ShallowRedisSaver(BaseRedisSaver[Redis, SearchIndex]):
-    """Redis implementation that only stores the most recent checkpoint."""
+    """Redis implementation that only stores the most recent checkpoint.
+
+    Supports standard Redis URLs (redis://), SSL (rediss://), and
+    Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+    """
 
     # Default cache size limits
     DEFAULT_KEY_CACHE_MAX_SIZE = 1000

langgraph/store/redis/__init__.py

@@ -73,6 +73,9 @@ class RedisStore(BaseStore, BaseRedisStore[Redis, SearchIndex]):
 
     Provides synchronous operations for storing and retrieving data with optional
     vector similarity search support.
+
+    Supports standard Redis URLs (redis://), SSL (rediss://), and
+    Sentinel URLs (redis+sentinel://host:26379/service_name/db).
     """
 
     # Enable TTL support

langgraph/store/redis/aio.py

@@ -2,7 +2,6 @@
 
 import asyncio
 import json
-import os
 from contextlib import asynccontextmanager
 from datetime import datetime, timedelta, timezone
 from types import TracebackType
@@ -26,6 +25,7 @@
 from redis.commands.search.query import Query
 from redisvl.index import AsyncSearchIndex
 from redisvl.query import FilterQuery, VectorQuery
+from redisvl.redis.connection import RedisConnectionFactory
 from redisvl.utils.token_escaper import TokenEscaper
 from ulid import ULID
 
@@ -54,7 +54,11 @@
 class AsyncRedisStore(
     BaseRedisStore[AsyncRedis, AsyncSearchIndex], AsyncBatchedBaseStore
 ):
-    """Async Redis store with optional vector search."""
+    """Async Redis store with optional vector search.
+
+    Supports standard Redis URLs (redis://), SSL (rediss://), and
+    Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+    """
 
     store_index: AsyncSearchIndex
     vector_index: AsyncSearchIndex
@@ -193,16 +197,17 @@ def configure_client(
         redis_client: Optional[AsyncRedis] = None,
         connection_args: Optional[dict[str, Any]] = None,
     ) -> None:
-        """Configure the Redis client."""
+        """Configure the Redis client.
+
+        Supports standard Redis URLs (redis://), SSL (rediss://), and
+        Sentinel URLs (redis+sentinel://host:26379/service_name/db).
+        """
         self._owns_its_client = redis_client is None
 
-        # Use direct AsyncRedis.from_url to avoid the deprecated get_async_redis_connection
         if redis_client is None:
-            if not redis_url:
-                redis_url = os.environ.get("REDIS_URL")
-                if not redis_url:
-                    raise ValueError("REDIS_URL env var not set")
-            self._redis = AsyncRedis.from_url(redis_url, **(connection_args or {}))
+            self._redis = RedisConnectionFactory.get_async_redis_connection(
+                redis_url, **(connection_args or {})
+            )
         else:
             self._redis = redis_client
 

pyproject.toml

@@ -62,10 +62,10 @@ filterwarnings = [
     "ignore::DeprecationWarning:testcontainers.core.waiting_utils",
     "ignore::DeprecationWarning:testcontainers.redis",
     # Ignore trustcall library's deprecated import (used by langmem)
-    "ignore:Importing Send from langgraph.constants is deprecated.*:langgraph.errors.LangGraphDeprecatedSinceV10:trustcall._base",
+    "ignore:Importing Send from langgraph.constants is deprecated.*:DeprecationWarning:trustcall._base",
     # Ignore PyTorch internal deprecation triggered by sentence-transformers during model loading
     "ignore::DeprecationWarning:torch.jit._script",
-    # Ignore redisvl internal deprecation in SemanticCache (our code already uses AsyncRedis.from_url directly)
+    # Ignore redisvl internal deprecation warning for get_async_redis_connection
     "ignore:get_async_redis_connection will become async:DeprecationWarning:redisvl.redis.connection",
 ]
 

tests/conftest.py

@@ -30,8 +30,8 @@ def redis_container(request):
 
     # Set the Compose project name so containers do not clash across workers
     os.environ["COMPOSE_PROJECT_NAME"] = f"redis_test_{worker_id}"
-    os.environ.setdefault("REDIS_VERSION", "latest")
-    os.environ.setdefault("REDIS_IMAGE", "redis/redis-stack-server:latest")
+    os.environ.setdefault("REDIS_VERSION", "8")
+    os.environ.setdefault("REDIS_IMAGE", "redis:8")
 
     compose = DockerCompose(
         context="tests",
@@ -110,29 +110,124 @@ async def clear_redis(redis_url: str) -> None:
         pass
 
 
+@pytest.fixture(scope="session")
+def sentinel_container(request):
+    """Start Redis master + Sentinel via Docker Compose for sentinel tests."""
+    if not request.config.getoption("--run-sentinel-tests"):
+        pytest.skip("Sentinel tests require --run-sentinel-tests flag")
+
+    compose = DockerCompose(
+        context="tests/sentinel",
+        compose_file_name="docker-compose.yml",
+        pull=True,
+    )
+    try:
+        compose.start()
+    except Exception as exc:
+        pytest.fail(f"Failed to start Sentinel containers: {exc}")
+
+    yield compose
+
+    try:
+        compose.stop()
+    except Exception:
+        pass
+
+
+@pytest.fixture(scope="session")
+def sentinel_master_url(sentinel_container):
+    """Direct connection URL to the Sentinel-monitored Redis master."""
+    # The master is exposed on fixed port 6399
+    host = "localhost"
+    port = 6399
+
+    deadline = time.time() + 15
+    while True:
+        try:
+            with socket.create_connection((host, port), timeout=1):
+                break
+        except OSError:
+            if time.time() > deadline:
+                pytest.skip("Redis master for Sentinel tests failed to become ready.")
+            time.sleep(0.5)
+
+    return f"redis://{host}:{port}"
+
+
+@pytest.fixture(scope="session")
+def sentinel_info(sentinel_container):
+    """Return sentinel host/port after waiting for readiness.
+
+    Returns a tuple of (sentinel_host, sentinel_port, master_host, master_port)
+    where master_host/port are the host-reachable mapped ports.
+    """
+    sentinel_host = "localhost"
+    sentinel_port = 26399
+    # The master is port-mapped to localhost:6399
+    master_host = "127.0.0.1"
+    master_port = 6399
+
+    # Poll sentinel until it has discovered the master
+    from redis import Redis as SyncRedis
+
+    deadline = time.time() + 30
+    while True:
+        try:
+            client = SyncRedis(host=sentinel_host, port=sentinel_port)
+            result = client.execute_command(
+                "SENTINEL", "get-master-addr-by-name", "mymaster"
+            )
+            client.close()
+            if result is not None:
+                break
+        except Exception:
+            pass
+        if time.time() > deadline:
+            pytest.skip("Redis Sentinel failed to discover master.")
+        time.sleep(0.5)
+
+    return sentinel_host, sentinel_port, master_host, master_port
+
+
 def pytest_addoption(parser: pytest.Parser) -> None:
     parser.addoption(
         "--run-api-tests",
         action="store_true",
         default=False,
         help="Run tests that require API keys",
     )
+    parser.addoption(
+        "--run-sentinel-tests",
+        action="store_true",
+        default=False,
+        help="Run tests that require Redis Sentinel (extra containers)",
+    )
 
 
 def pytest_configure(config: pytest.Config) -> None:
     config.addinivalue_line(
         "markers", "requires_api_keys: mark test as requiring API keys"
     )
+    config.addinivalue_line(
+        "markers", "sentinel: mark test as requiring Redis Sentinel"
+    )
 
 
 def pytest_collection_modifyitems(
     config: pytest.Config, items: list[pytest.Item]
 ) -> None:
-    if config.getoption("--run-api-tests"):
-        return
-    skip_api = pytest.mark.skip(
-        reason="Skipping test because API keys are not provided. Use --run-api-tests to run these tests."
-    )
-    for item in items:
-        if item.get_closest_marker("requires_api_keys"):
-            item.add_marker(skip_api)
+    if not config.getoption("--run-api-tests"):
+        skip_api = pytest.mark.skip(
+            reason="Skipping test because API keys are not provided. Use --run-api-tests to run these tests."
+        )
+        for item in items:
+            if item.get_closest_marker("requires_api_keys"):
+                item.add_marker(skip_api)
+
+    if not config.getoption("--run-sentinel-tests"):
+        skip_sentinel = pytest.mark.skip(
+            reason="Skipping sentinel test. Use --run-sentinel-tests to run."
+        )
+        for item in items:
+            if item.get_closest_marker("sentinel"):
+                item.add_marker(skip_sentinel)

tests/docker-compose.yml

@@ -1,7 +1,7 @@
 version: "3.9"
 services:
   redis:
-    image: "${REDIS_IMAGE}"
+    image: "${REDIS_IMAGE:-redis:8}"
     ports:
       - target: 6379
         published: 0