rillkit 0.1.1__tar.gz → 0.3.0__tar.gz

{rillkit-0.1.1 → rillkit-0.3.0}/.gitignore

@@ -9,4 +9,5 @@ dist/
 node_modules/
 docs/.vitepress/cache/
 docs/.vitepress/dist/
+.docs-build/
 .DS_Store

{rillkit-0.1.1 → rillkit-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: rillkit
-Version: 0.1.1
+Version: 0.3.0
 Summary: Simple publish and consume for Redis Streams: consumer groups, retries, DLQ, ack policies and middleware.
-Project-URL: Homepage, https://nimzymaina.github.io/rillkit/
-Project-URL: Documentation, https://nimzymaina.github.io/rillkit/
-Project-URL: Repository, https://github.com/NimzyMaina/rillkit
-Project-URL: Issues, https://github.com/NimzyMaina/rillkit/issues
+Project-URL: Homepage, https://nimzymaina.github.io/RillKit/
+Project-URL: Documentation, https://nimzymaina.github.io/RillKit/
+Project-URL: Repository, https://github.com/NimzyMaina/RillKit
+Project-URL: Issues, https://github.com/NimzyMaina/RillKit/issues
 Author: Nimrod Maina
 License: MIT
 License-File: LICENSE
@@ -25,25 +25,29 @@ Requires-Python: >=3.9
 Requires-Dist: redis>=5.0
 Provides-Extra: pydantic
 Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Provides-Extra: valkey
+Requires-Dist: valkey<6.3,>=6.1.1; extra == 'valkey'
 Description-Content-Type: text/markdown
 
 # RillKit
 
-Simple publish and consume for Redis Streams. Consumer groups, retries with backoff, a dead-letter
-queue, ack policies, middleware and lifecycle hooks, without the boilerplate.
+Simple publish and consume for Redis and Valkey streams, standalone or cluster. Consumer groups,
+retries with backoff, a dead-letter queue, ack policies, middleware and lifecycle hooks, without the
+boilerplate.
 
-**Docs:** https://nimzymaina.github.io/rillkit/
+**Docs:** https://nimzymaina.github.io/RillKit/
 
 ```bash
 pip install rillkit             # plain dict bodies
 pip install "rillkit[pydantic]" # optional typed bodies
+pip install "rillkit[valkey]"   # optional valkey-py client
 ```
 
 ```python
 from rillkit import Broker, Stream
 
 orders = Stream("orders", group="workers")
-broker = Broker.from_env()  # REDIS_URL, or REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_SSL
+broker = Broker.from_env()  # RILLKIT_URL, or RILLKIT_HOST/PORT/...; REDIS_* still work
 
 
 @broker.subscribe(orders, max_retries=3)
@@ -68,14 +72,25 @@ if __name__ == "__main__":
 - `on_startup`, `after_startup`, `on_shutdown`, `after_shutdown` hooks and graceful SIGTERM shutdown
 - Worker heartbeats: `broker.active_workers(stream)` includes idle workers
 - Stack `@broker.publisher(...)` under `@broker.subscribe(...)` to publish a handler's return value
-- The wire format is a single `data` field holding JSON, so plain redis-py producers interoperate
+- The wire format is a single `data` field holding JSON, so plain redis-py or valkey-py producers interoperate
+- Redis or Valkey (`RILLKIT_BACKEND=valkey`), standalone or Cluster (`RILLKIT_MODE=cluster`)
+- Key builders map stream names to keys: the original names on one server, hash-tagged keys on a
+  cluster so a stream and its DLQ share a slot and the move to the DLQ stays a transaction, plus
+  prefixes and tenant ids (`HashTagKeys(prefix="billing", tenant="t-42")`)
 
 ## Development
 
 ```bash
 uv sync --group dev
-REDIS_URL=redis://localhost:6379/15 uv run pytest   # needs a Redis
+REDIS_URL=redis://localhost:6379/15 uv run pytest   # needs a Redis; only db 15 is flushed
+RILLKIT_TEST_BACKEND=valkey REDIS_URL=redis://localhost:6380/15 uv run pytest   # valkey-py
+
+scripts/test-cluster.sh valkey 7101                 # a six-node cluster in Docker
+RILLKIT_TEST_BACKEND=valkey RILLKIT_TEST_MODE=cluster \
+  RILLKIT_TEST_CLUSTER_NODES=127.0.0.1:7101 uv run pytest
+
 npm install && npm run docs:dev                     # docs
+npm run docs:build:versions                         # latest plus a snapshot per release tag
 ```
 
 MIT licensed.

{rillkit-0.1.1 → rillkit-0.3.0}/README.md

@@ -1,20 +1,22 @@
 # RillKit
 
-Simple publish and consume for Redis Streams. Consumer groups, retries with backoff, a dead-letter
-queue, ack policies, middleware and lifecycle hooks, without the boilerplate.
+Simple publish and consume for Redis and Valkey streams, standalone or cluster. Consumer groups,
+retries with backoff, a dead-letter queue, ack policies, middleware and lifecycle hooks, without the
+boilerplate.
 
-**Docs:** https://nimzymaina.github.io/rillkit/
+**Docs:** https://nimzymaina.github.io/RillKit/
 
 ```bash
 pip install rillkit             # plain dict bodies
 pip install "rillkit[pydantic]" # optional typed bodies
+pip install "rillkit[valkey]"   # optional valkey-py client
 ```
 
 ```python
 from rillkit import Broker, Stream
 
 orders = Stream("orders", group="workers")
-broker = Broker.from_env()  # REDIS_URL, or REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_SSL
+broker = Broker.from_env()  # RILLKIT_URL, or RILLKIT_HOST/PORT/...; REDIS_* still work
 
 
 @broker.subscribe(orders, max_retries=3)
@@ -39,14 +41,25 @@ if __name__ == "__main__":
 - `on_startup`, `after_startup`, `on_shutdown`, `after_shutdown` hooks and graceful SIGTERM shutdown
 - Worker heartbeats: `broker.active_workers(stream)` includes idle workers
 - Stack `@broker.publisher(...)` under `@broker.subscribe(...)` to publish a handler's return value
-- The wire format is a single `data` field holding JSON, so plain redis-py producers interoperate
+- The wire format is a single `data` field holding JSON, so plain redis-py or valkey-py producers interoperate
+- Redis or Valkey (`RILLKIT_BACKEND=valkey`), standalone or Cluster (`RILLKIT_MODE=cluster`)
+- Key builders map stream names to keys: the original names on one server, hash-tagged keys on a
+  cluster so a stream and its DLQ share a slot and the move to the DLQ stays a transaction, plus
+  prefixes and tenant ids (`HashTagKeys(prefix="billing", tenant="t-42")`)
 
 ## Development
 
 ```bash
 uv sync --group dev
-REDIS_URL=redis://localhost:6379/15 uv run pytest   # needs a Redis
+REDIS_URL=redis://localhost:6379/15 uv run pytest   # needs a Redis; only db 15 is flushed
+RILLKIT_TEST_BACKEND=valkey REDIS_URL=redis://localhost:6380/15 uv run pytest   # valkey-py
+
+scripts/test-cluster.sh valkey 7101                 # a six-node cluster in Docker
+RILLKIT_TEST_BACKEND=valkey RILLKIT_TEST_MODE=cluster \
+  RILLKIT_TEST_CLUSTER_NODES=127.0.0.1:7101 uv run pytest
+
 npm install && npm run docs:dev                     # docs
+npm run docs:build:versions                         # latest plus a snapshot per release tag
 ```
 
 MIT licensed.

{rillkit-0.1.1 → rillkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rillkit"
-version = "0.1.1"
+version = "0.3.0"
 description = "Simple publish and consume for Redis Streams: consumer groups, retries, DLQ, ack policies and middleware."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -28,15 +28,25 @@ dependencies = ["redis>=5.0"]
 
 [project.optional-dependencies]
 pydantic = ["pydantic>=2.0"]
+valkey = ["valkey>=6.1.1,<6.3"]
 
 [project.urls]
-Homepage = "https://nimzymaina.github.io/rillkit/"
-Documentation = "https://nimzymaina.github.io/rillkit/"
-Repository = "https://github.com/NimzyMaina/rillkit"
-Issues = "https://github.com/NimzyMaina/rillkit/issues"
+Homepage = "https://nimzymaina.github.io/RillKit/"
+Documentation = "https://nimzymaina.github.io/RillKit/"
+Repository = "https://github.com/NimzyMaina/RillKit"
+Issues = "https://github.com/NimzyMaina/RillKit/issues"
 
 [dependency-groups]
-dev = ["pytest>=8", "pytest-timeout>=2", "pydantic>=2", "ruff>=0.6", "mypy>=1.10", "build", "twine"]
+dev = [
+    "pytest>=8",
+    "pytest-timeout>=2",
+    "pydantic>=2",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "build",
+    "twine",
+    "valkey>=6.1.1,<6.3",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/rillkit"]
@@ -47,6 +57,10 @@ include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 timeout = 60
+markers = [
+    "standalone_only: needs a standalone server (skipped when RILLKIT_TEST_MODE=cluster)",
+    "cluster_only: needs a cluster (RILLKIT_TEST_MODE=cluster)",
+]
 
 [tool.ruff]
 line-length = 100

{rillkit-0.1.1 → rillkit-0.3.0}/src/rillkit/__init__.py

@@ -1,25 +1,28 @@
-"""rillkit: simple publish and consume for Redis Streams."""
+"""rillkit: simple publish and consume for Redis and Valkey streams."""
 
 from .ack import AckPolicy
 from .broker import Broker, Publisher
 from .codec import Codec, JsonCodec
 from .exceptions import (
     AckMessage,
+    ConfigurationError,
     DecodeError,
     NackMessage,
     PublishError,
     RejectMessage,
     RillkitError,
 )
+from .keys import HashTagKeys, KeyBuilder, PlainKeys
 from .message import Message
 from .middleware import BaseMiddleware, Idempotent, PublishCommand
 from .settings import Settings
 from .stream import Stream
 
-__version__ = "0.1.1"
+__version__ = "0.3.0"
 
 __all__ = [
-    "AckMessage", "AckPolicy", "BaseMiddleware", "Broker", "Codec", "DecodeError", "Idempotent",
-    "JsonCodec", "Message", "NackMessage", "PublishCommand", "PublishError", "Publisher",
-    "RejectMessage", "RillkitError", "Settings", "Stream",
+    "AckMessage", "AckPolicy", "BaseMiddleware", "Broker", "Codec", "ConfigurationError",
+    "DecodeError", "HashTagKeys", "Idempotent", "JsonCodec", "KeyBuilder", "Message",
+    "NackMessage", "PlainKeys", "PublishCommand", "PublishError", "Publisher", "RejectMessage",
+    "RillkitError", "Settings", "Stream",
 ]

{rillkit-0.1.1 → rillkit-0.3.0}/src/rillkit/broker.py

@@ -2,15 +2,16 @@ import logging
 import signal
 import sys
 import threading
+import time
 from collections.abc import Sequence
 from functools import partial
 from typing import Any, Callable, Optional
 
-import redis
-
 from .ack import AckPolicy
-from .consumer import HEARTBEAT_PREFIX, Subscriber, _text
+from .clients import CLIENT_ERRORS, Client, is_cluster, run_together
+from .consumer import Subscriber, _text
 from .exceptions import PublishError
+from .keys import HashTagKeys, KeyBuilder, PlainKeys
 from .middleware import BaseMiddleware, PublishCommand
 from .settings import Settings
 from .stream import Stream, StreamLike, as_stream
@@ -40,7 +41,7 @@ class Publisher:
 
 
 class Broker:
-    """Owns the Redis client, the subscribers and the lifecycle hooks.
+    """Owns the client, the subscribers and the lifecycle hooks.
 
         broker = Broker.from_env()
 
@@ -49,19 +50,32 @@ class Broker:
 
         broker.publish("orders", {"id": 1})
         broker.run()
+
+    ``client`` can be any redis-py or valkey-py client, standalone or cluster. It is used as is;
+    ``stop()`` closes it. ``keys`` picks the physical key layout; by default it comes from
+    ``settings.key_layout``, else plain keys on a standalone client and hash-tagged keys on a
+    cluster client.
     """
 
     def __init__(
         self,
         url: Optional[str] = None,
         *,
-        client: Optional["redis.Redis"] = None,
+        client: Optional[Client] = None,
         settings: Optional[Settings] = None,
         middlewares: Sequence[BaseMiddleware] = (),
+        keys: Optional[KeyBuilder] = None,
     ) -> None:
         if client is None:
-            client = (settings or Settings(url=url)).client()
+            settings = settings or Settings(url=url)
+            client = settings.client()
         self.client = client
+        if keys is None:
+            if settings is not None and settings.key_layout is not None:
+                keys = settings.key_builder()
+            else:
+                keys = HashTagKeys() if is_cluster(client) else PlainKeys()
+        self.keys: KeyBuilder = keys
         self.middlewares: list[BaseMiddleware] = []
         for mw in middlewares:
             self.use(mw)
@@ -149,9 +163,10 @@ class Broker:
         try:
             payload = cmd.stream.codec.encode(cmd.body)
             entry_id = self.client.xadd(
-                cmd.stream.name, {"data": payload}, maxlen=cmd.maxlen, approximate=cmd.approximate
+                self.keys.stream(cmd.stream), {"data": payload}, maxlen=cmd.maxlen,
+                approximate=cmd.approximate,
             )
-        except (redis.RedisError, TypeError, ValueError) as e:
+        except CLIENT_ERRORS + (TypeError, ValueError) as e:
             raise PublishError(f"could not publish to {cmd.stream.name}: {e}") from e
         return _text(entry_id)
 
@@ -249,23 +264,33 @@ class Broker:
 
     def active_workers(self, stream: StreamLike, group: Optional[str] = None) -> list[str]:
         """Consumer names with a live heartbeat. Unlike XINFO CONSUMERS this includes idle workers
-        that have not received a message yet."""
+        that have not received a message yet.
+
+        Reads the consumer registry (``broker.keys.consumers``), one sorted set per stream and
+        group, so it needs no ``SCAN`` and works for ACL users that may not list keys. Expiry is
+        judged by the workers' and caller's clocks, which should agree within the heartbeat TTL.
+        Workers older than 0.3, which write no registry entry, are not listed."""
         s = as_stream(stream)
-        prefix = f"{HEARTBEAT_PREFIX}{s.name}:{group or s.group}:"
-        return sorted(_text(k)[len(prefix):] for k in self.client.scan_iter(match=f"{prefix}*"))
+        key = self.keys.consumers(s, str(group or s.group))
+        members: Any = self.client.zrangebyscore(key, int(time.time() * 1000), "+inf")
+        return sorted(_text(m) for m in members)
 
     def replay_dlq(self, stream: StreamLike, count: int = 100) -> int:
-        """Move up to ``count`` entries from the DLQ back onto the stream. Returns how many."""
+        """Move up to ``count`` entries from the DLQ back onto the stream. Returns how many.
+
+        Each move is one transaction when the stream and DLQ keys share a slot (always outside a
+        cluster). Otherwise the entry is added to the stream first and then deleted from the DLQ,
+        so a failure in between can replay it twice but never drops it."""
         s = as_stream(stream)
+        stream_key, dlq_key = self.keys.stream(s), self.keys.dlq(s)
         moved = 0
-        rows: Any = self.client.xrange(s.dlq_name, count=count)
+        rows: Any = self.client.xrange(dlq_key, count=count)
         for entry_id, raw in rows:
             fields: dict[Any, Any] = {
                 _text(k): _text(v) for k, v in raw.items() if not _text(k).startswith("x-")
             }
-            pipe = self.client.pipeline()
-            pipe.xadd(s.name, fields)
-            pipe.xdel(s.dlq_name, entry_id)
-            pipe.execute()
+            run_together(
+                self.client, [("xadd", (stream_key, fields)), ("xdel", (dlq_key, entry_id))]
+            )
             moved += 1
         return moved

rillkit-0.3.0/src/rillkit/clients.py

@@ -0,0 +1,294 @@
+"""Building Redis or Valkey clients, and the small differences between the two libraries.
+
+rillkit talks to whichever client it is given through the commands both libraries share. This
+module holds the parts that are not shared: the client classes, the options each constructor
+accepts, the exception classes, and how to reach a single node of a cluster.
+"""
+
+import importlib
+import inspect
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional
+from urllib.parse import parse_qsl, unquote, urlparse
+
+import redis
+from redis.crc import key_slot
+
+from .exceptions import ConfigurationError
+
+if TYPE_CHECKING:
+    from .settings import Settings
+
+BACKENDS = ("redis", "valkey")
+MODES = ("standalone", "cluster")
+
+# Options that pick the server or the credentials. They have their own Settings fields, so they are
+# refused in client_kwargs instead of quietly fighting with those fields.
+RESERVED_OPTIONS = {
+    "host": "host", "port": "port", "db": "db", "url": "url", "startup_nodes": "cluster_nodes",
+    "username": "username", "password": "password", "ssl": "ssl",
+}
+
+# A client instance. Typed loosely because it is one of four classes from two libraries.
+Client = Any
+
+
+@dataclass(frozen=True)
+class Backend:
+    """The classes and option lists of one client library."""
+
+    name: str
+    standalone: type
+    cluster: type
+    cluster_node: type
+    standalone_options: frozenset[str]
+    cluster_options: frozenset[str]
+
+
+def _constructor_options(cls: type) -> set[str]:
+    params = inspect.signature(cls.__init__).parameters.values()  # type: ignore[misc]
+    return {p.name for p in params if p.kind not in (p.VAR_KEYWORD, p.VAR_POSITIONAL)} - {"self"}
+
+
+def _load(name: str) -> Backend:
+    try:
+        module = importlib.import_module(name)
+        cluster_module = importlib.import_module(f"{name}.cluster")
+    except ImportError as e:
+        raise ConfigurationError(
+            f'backend "{name}" needs the {name} package: pip install "rillkit[{name}]"'
+        ) from e
+    standalone = module.Redis if name == "redis" else module.Valkey
+    cluster = module.RedisCluster if name == "redis" else module.ValkeyCluster
+    # Cluster clients forward only the keys in this list to each node and silently drop the rest,
+    # so it is the real list of what works, on top of the cluster constructor's own arguments.
+    list_name = "REDIS_ALLOWED_KEYS" if name == "redis" else "VALKEY_ALLOWED_KEYS"
+    forwarded: Iterable[str] = getattr(cluster_module, list_name, ())
+    disabled = set(getattr(cluster_module, "KWARGS_DISABLED_KEYS", ()))
+    cluster_options = (_constructor_options(cluster) | (set(forwarded) - disabled)) - {"db"}
+    return Backend(
+        name=name,
+        standalone=standalone,
+        cluster=cluster,
+        cluster_node=cluster_module.ClusterNode,
+        standalone_options=frozenset(_constructor_options(standalone) - set(RESERVED_OPTIONS)),
+        cluster_options=frozenset(cluster_options - set(RESERVED_OPTIONS)),
+    )
+
+
+_backends: dict[str, Backend] = {}
+
+
+def backend(name: str) -> Backend:
+    """The client library for ``name`` ("redis" or "valkey"), imported on first use."""
+    if name not in BACKENDS:
+        raise ConfigurationError(f"unknown backend {name!r}, expected one of {BACKENDS}")
+    if name not in _backends:
+        _backends[name] = _load(name)
+    return _backends[name]
+
+
+# exceptions
+
+
+def _exception_classes(*names: str) -> tuple[type[Exception], ...]:
+    """The named exception classes from redis-py, plus valkey-py's when it is installed."""
+    found: list[type[Exception]] = []
+    modules = [redis.exceptions]
+    try:
+        modules.append(importlib.import_module("valkey.exceptions"))
+    except ImportError:
+        pass
+    for module in modules:
+        for name in names:
+            cls = getattr(module, name, None)
+            if cls is not None and cls not in found:
+                found.append(cls)
+    return tuple(found)
+
+
+# Any error raised by either client, including cluster errors, which do not derive from the
+# library's base error class.
+CLIENT_ERRORS = _exception_classes(
+    "RedisError", "RedisClusterException", "ValkeyError", "ValkeyClusterException"
+)
+# The server answered with an error (BUSYGROUP, NOGROUP, WRONGTYPE, MOVED, ...).
+RESPONSE_ERRORS = _exception_classes("ResponseError")
+# The server could not be reached or did not answer in time.
+CONNECTION_ERRORS = _exception_classes("ConnectionError", "TimeoutError")
+# The cluster topology changed under a command, so it may succeed once the slots are reloaded.
+CLUSTER_REDIRECT_ERRORS = _exception_classes(
+    "MovedError", "AskError", "TryAgainError", "ClusterDownError"
+)
+
+
+# building clients
+
+
+def _url_credentials(url: str) -> bool:
+    """Whether the url carries a username or password, in the userinfo or the query string."""
+    parsed = urlparse(url)
+    query = {k.lower() for k, _ in parse_qsl(parsed.query, True)}
+    return bool(parsed.username or parsed.password or query & {"username", "password"})
+
+
+def _url_db(url: str) -> int:
+    path = urlparse(url).path.strip("/")
+    if not path:
+        return 0
+    try:
+        return int(unquote(path))
+    except ValueError as e:
+        raise ConfigurationError("the database in the url path must be a number") from e
+
+
+def _check_options(options: Mapping[str, Any], allowed: Iterable[str], where: str) -> None:
+    allowed = set(allowed)
+    for key in options:
+        if key in RESERVED_OPTIONS:
+            raise ConfigurationError(
+                f"client_kwargs[{key!r}] is not allowed: set Settings.{RESERVED_OPTIONS[key]}"
+            )
+        if key not in allowed:
+            raise ConfigurationError(f"client_kwargs[{key!r}] is not an option of {where}")
+
+
+def parse_node(node: Any) -> tuple[str, int]:
+    """``"host:port"``, ``("host", port)`` or ``"host"`` (port 6379) as a (host, port) pair."""
+    if isinstance(node, str):
+        host, sep, port = node.strip().rpartition(":")
+        if not sep:
+            host, port = port, "6379"
+        host = host.strip("[]")  # [::1]:7000
+    elif isinstance(node, Sequence) and len(node) == 2:
+        host, port = node
+    else:
+        raise ConfigurationError(f"cluster node {node!r} is not 'host:port' or (host, port)")
+    try:
+        return str(host), int(port)
+    except ValueError as e:
+        raise ConfigurationError(f"cluster node {node!r} has an invalid port") from e
+
+
+def create_client(settings: "Settings") -> Client:
+    """Build the client ``settings`` describe. Raises ``ConfigurationError`` for bad settings."""
+    lib = backend(settings.backend)
+    options: dict[str, Any] = {"socket_timeout": settings.socket_timeout}
+    options.update(settings.client_kwargs)
+    url = settings.url
+    if url is None or not _url_credentials(url):
+        # Credentials embedded in the url win; the separate fields fill in when it has none.
+        if settings.username is not None:
+            options["username"] = settings.username
+        if settings.password is not None:
+            options["password"] = settings.password
+    if settings.mode == "cluster":
+        return _cluster_client(lib, settings, options)
+    return _standalone_client(lib, settings, options)
+
+
+def _standalone_client(lib: Backend, settings: "Settings", options: dict[str, Any]) -> Client:
+    _check_options(settings.client_kwargs, lib.standalone_options, lib.standalone.__name__)
+    if settings.cluster_nodes:
+        raise ConfigurationError("cluster_nodes is set but mode is 'standalone'")
+    cls: Any = lib.standalone
+    if settings.url:
+        client = cls.from_url(settings.url, **options)
+    else:
+        client = cls(
+            host=settings.host, port=settings.port, db=settings.db, ssl=settings.ssl, **options
+        )
+    pool = client.connection_pool
+    try:
+        # Build (without connecting) one connection now, so an option the connection class does
+        # not accept fails here rather than on the first command.
+        pool.connection_class(**pool.connection_kwargs)
+    except TypeError as e:
+        client.close()
+        raise ConfigurationError(f"invalid client option: {e}") from e
+    return client
+
+
+def _cluster_client(lib: Backend, settings: "Settings", options: dict[str, Any]) -> Client:
+    _check_options(settings.client_kwargs, lib.cluster_options, lib.cluster.__name__)
+    if settings.db != 0 or (settings.url and _url_db(settings.url) != 0):
+        raise ConfigurationError("cluster mode only has database 0")
+    node_cls: Any = lib.cluster_node
+    cls: Any = lib.cluster
+    nodes = [node_cls(*parse_node(n)) for n in settings.cluster_nodes]
+    if settings.url:
+        # The url is one seed node plus credentials and TLS; cluster_nodes adds more seeds.
+        return cls.from_url(settings.url, startup_nodes=nodes or None, **options)
+    if not nodes:
+        nodes = [node_cls(settings.host, settings.port)]
+    return cls(startup_nodes=nodes, ssl=settings.ssl, **options)
+
+
+# working with clients of either library and mode
+
+
+def is_cluster(client: Client) -> bool:
+    return hasattr(client, "nodes_manager") and hasattr(client, "get_node_from_key")
+
+
+def _node_client(node: Any) -> Client:
+    conn = getattr(node, "redis_connection", None) or getattr(node, "valkey_connection", None)
+    if conn is None:
+        raise ConfigurationError(f"cluster node {node!r} has no client")
+    return conn
+
+
+def socket_timeout(client: Client) -> Optional[float]:
+    """The read timeout a connection from this client will use, or None for no timeout."""
+    try:
+        if is_cluster(client):
+            client = _node_client(client.get_primaries()[0])
+        pool = client.connection_pool
+        conn = pool.connection_class(**pool.connection_kwargs)  # built, never connected
+    except Exception:
+        return None
+    return getattr(conn, "socket_timeout", None) or getattr(conn, "_socket_timeout", None)
+
+
+def same_slot(*keys: str) -> bool:
+    return len({key_slot(k.encode()) for k in keys}) == 1
+
+
+Command = tuple[str, tuple[Any, ...]]
+
+
+def run_together(client: Client, commands: Sequence[Command]) -> list[Any]:
+    """Run ``commands`` (method name, args) atomically where the keys allow it, else in order.
+
+    The first argument of every command is its key. Standalone clients use MULTI/EXEC. On a
+    cluster, keys in one hash slot also use MULTI/EXEC, sent to the node that owns the slot.
+    Keys in different slots cannot be in one transaction, so the commands run one after another
+    and a failure leaves the earlier ones applied: callers order them so that is safe to retry.
+    """
+    if not is_cluster(client):
+        pipe = client.pipeline(transaction=True)
+        for name, args in commands:
+            getattr(pipe, name)(*args)
+        return list(pipe.execute())
+    keys = [args[0] for _, args in commands]
+    if not same_slot(*keys):
+        return [getattr(client, name)(*args) for name, args in commands]
+    return _node_transaction(client, keys[0], commands)
+
+
+def _node_transaction(client: Client, key: str, commands: Sequence[Command]) -> list[Any]:
+    # Not every cluster client supports transactional pipelines (valkey-py 6.1 refuses them), so
+    # run MULTI/EXEC on the owning node directly. If the slot moved, the queued commands fail
+    # with MOVED, EXEC applies nothing, and one retry after reloading the slot map follows it.
+    for attempt in (1, 2):
+        pipe = _node_client(client.get_node_from_key(key)).pipeline(transaction=True)
+        for name, args in commands:
+            getattr(pipe, name)(*args)
+        try:
+            return list(pipe.execute())
+        except CLUSTER_REDIRECT_ERRORS + CONNECTION_ERRORS:
+            if attempt == 2:
+                raise
+            client.nodes_manager.initialize()
+    raise AssertionError("unreachable")