mic-datastore 0.1.0__py3-none-any.whl

mic/cache/__init__.py

@@ -0,0 +1,37 @@
+"""Cache — abstraction key-value avec TTL pour patterns transverses.
+
+Trois implémentations :
+- ``InMemoryCache`` : dict en mémoire, no-op TTL hors process. Pour
+  tests + dev mono-process.
+- ``RedisCache`` (extra ``[redis]``) : Redis via ``redis-py``, TTL
+  en secondes côté Redis. Pour prod multi-replicas.
+- ``CacheBackend`` : ABC commun.
+
+Cas d'usage primaires :
+- **Idempotency-Key** : déduplication des requêtes POST retentées
+  par le client (cf. ``mic.client``).
+- **Rate limiting** : compteur sliding window (à venir v1.2).
+- **Distributed lock** : SET NX EX (à venir v1.2).
+- **Cache-aside** : memoization de queries lentes côté domain
+  service (consumer-side, pas dans la lib).
+"""
+
+from mic.cache.backends import (
+    CacheBackend,
+    CacheError,
+    InMemoryCache,
+    RedisCache,
+)
+
+# RevokeBlacklist — révocation de JWT court-TTL adossée à un CacheBackend.
+# Réside ici (tier data/cache) et non dans mic.auth : c'est un besoin
+# *stateful*, pas de la cryptographie de jeton (cf. ADR-0001, split mic-datastore).
+from mic.cache.revoke_blacklist import RevokeBlacklist
+
+__all__ = [
+    "CacheBackend",
+    "CacheError",
+    "InMemoryCache",
+    "RedisCache",
+    "RevokeBlacklist",
+]

mic/cache/backends.py

@@ -0,0 +1,237 @@
+"""Backends de cache : ABC + InMemory + Redis.
+
+Convention :
+- API simple : ``get(key)``, ``set(key, value, ttl_seconds)``,
+  ``delete(key)``, ``set_if_absent(key, value, ttl_seconds)``.
+- Valeurs sont des **bytes** (sérialisation JSON / pickle laissée au
+  consumer — pas d'opinion ici).
+- ``ttl_seconds`` est obligatoire sur ``set`` pour empêcher les
+  fuites mémoire silencieuses (Redis : EXPIRE après SET ; InMemory :
+  expiration paresseuse à la lecture).
+- Les erreurs réseau / Redis bubblent en ``CacheError`` (et non un
+  ``redis.RedisError`` qui ferait fuiter le SDK).
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+
+class CacheError(Exception):
+    """Erreur cache (réseau, sérialisation, backend down)."""
+
+
+class CacheBackend(ABC):
+    """Contract minimal d'un backend de cache."""
+
+    @abstractmethod
+    def get(self, key: str) -> bytes | None:
+        """Retourne la valeur (bytes) ou None si absente / expirée."""
+
+    @abstractmethod
+    def set(self, key: str, value: bytes, *, ttl_seconds: int) -> None:
+        """Set avec TTL obligatoire (≥1)."""
+
+    @abstractmethod
+    def set_if_absent(self, key: str, value: bytes, *, ttl_seconds: int) -> bool:
+        """SET NX : retourne True si insertion, False si la key existait."""
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Supprime. No-op si la key n'existe pas."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Vide le cache (utile en tests, dangereux en prod)."""
+
+
+# ---------------------------------------------------------------------------
+# InMemoryCache : dict + expiration paresseuse
+# ---------------------------------------------------------------------------
+
+
+class InMemoryCache(CacheBackend):
+    """Dict en mémoire avec expiration paresseuse à la lecture.
+
+    Pour tests + dev mono-process. NE PAS utiliser en prod multi-replicas
+    — chaque replica aurait son propre dict.
+
+    ``time_fn`` injectable (default ``time.monotonic``) pour pouvoir
+    avancer l'horloge dans les tests sans ``time.sleep``.
+    """
+
+    def __init__(self, *, time_fn: Callable[[], float] = time.monotonic) -> None:
+        self._store: dict[str, tuple[bytes, float]] = {}
+        self._time_fn = time_fn
+
+    def _is_expired(self, expiry: float) -> bool:
+        return self._time_fn() >= expiry
+
+    def get(self, key: str) -> bytes | None:
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        value, expiry = entry
+        if self._is_expired(expiry):
+            del self._store[key]
+            return None
+        return value
+
+    def set(self, key: str, value: bytes, *, ttl_seconds: int) -> None:
+        if ttl_seconds < 1:
+            raise CacheError(f"ttl_seconds must be >= 1, got {ttl_seconds}")
+        self._store[key] = (value, self._time_fn() + ttl_seconds)
+
+    def set_if_absent(self, key: str, value: bytes, *, ttl_seconds: int) -> bool:
+        if ttl_seconds < 1:
+            raise CacheError(f"ttl_seconds must be >= 1, got {ttl_seconds}")
+        # Lire (avec expiration paresseuse) avant de check
+        if self.get(key) is not None:
+            return False
+        self._store[key] = (value, self._time_fn() + ttl_seconds)
+        return True
+
+    def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        self._store.clear()
+
+
+# ---------------------------------------------------------------------------
+# RedisCache : redis-py (extra [redis])
+# ---------------------------------------------------------------------------
+
+
+class RedisCache(CacheBackend):
+    """Cache Redis via ``redis-py``.
+
+    Requiert l'extra ``[redis]``. ``client`` peut être injecté
+    (utile pour les tests qui mockent) ou construit depuis ``url``.
+
+    Toutes les méthodes catchent les erreurs Redis (réseau, timeout)
+    et les re-raisent en ``CacheError`` — le consumer ne voit pas le
+    SDK sous-jacent.
+
+    ## Mode Redis Cluster (opt-in)
+
+    Par défaut (``cluster=False``), le client est un Redis **standalone**
+    (``redis.Redis`` — single-node ou derrière Sentinel). Passer
+    ``cluster=True`` construit un ``redis.cluster.RedisCluster`` à la
+    place : le client découvre la topologie multi-node depuis l'``url``
+    de bootstrap et route automatiquement chaque key vers son shard via
+    les redirections MOVED/ASK.
+
+    Le ``RedisCache`` reste mono-key sur toutes ses opérations
+    (``get`` / ``set`` / ``set_if_absent`` / ``delete``), donc il n'y a
+    **jamais** de risque ``CROSSSLOT`` — aucune commande ne touche plus
+    d'une key à la fois. La seule opération sensible au cluster est
+    ``clear()`` (FLUSHDB), géré ci-dessous.
+
+    Cette option est l'escape-hatch "minimal switch" pour un cache
+    cache-aside simple. Pour les patterns multi-shards avancés (hash
+    tags, fan-out par node, bootstrap multi-node explicite), préférer
+    :class:`mic.cache.cluster.RedisClusterCache`, qui expose
+    ``startup_nodes`` + ``hash_tagged()``.
+
+    >>> RedisCache(url="redis://node-1:6379", cluster=True)  # doctest: +SKIP
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        client: Any = None,
+        decode_responses: bool = False,
+        cluster: bool = False,
+    ) -> None:
+        #: Mémorisé pour router ``clear()`` (FLUSHDB) correctement : en
+        #: cluster le flush n'est pas un broadcast, il faut viser tous
+        #: les masters. Un client injecté est traité comme cluster ssi
+        #: ``cluster=True`` a été passé explicitement.
+        self._cluster = cluster
+        if client is not None:
+            self._client = client
+        else:
+            if not url:
+                raise CacheError("RedisCache: must pass either ``url`` or ``client``")
+            try:
+                import redis  # noqa: PLC0415 — optional dep guard
+            except ImportError as exc:
+                raise CacheError(
+                    "redis-py not installed. " "Install with: pip install 'mic-struct[redis]'"
+                ) from exc
+            if cluster:
+                # ``import redis`` ne charge pas le sous-module ``redis.cluster`` :
+                # on l'importe explicitement (couvert par le même dep guard).
+                from redis.cluster import RedisCluster  # noqa: PLC0415
+
+                self._client = RedisCluster.from_url(url, decode_responses=decode_responses)
+            else:
+                self._client = redis.Redis.from_url(url, decode_responses=decode_responses)
+
+    @property
+    def native(self) -> Any:
+        """Le ``redis.Redis`` natif — escape-hatch pour les commandes
+        Redis non couvertes par l'API ``CacheBackend`` (PUB/SUB, scripts
+        Lua, pipelines, INFO, …). Aligné avec le pattern ``.native`` de
+        :mod:`mic.datastorage` (DocumentDataStorage / GraphDataStorage).
+        """
+        return self._client
+
+    def _wrap_errors(self, op: str, fn: Callable[[], Any]) -> Any:
+        try:
+            return fn()
+        except Exception as exc:
+            raise CacheError(f"Redis {op} failed: {exc}") from exc
+
+    def get(self, key: str) -> bytes | None:
+        result = self._wrap_errors("GET", lambda: self._client.get(key))
+        if result is None:
+            return None
+        if isinstance(result, str):
+            return result.encode()
+        return bytes(result)
+
+    def set(self, key: str, value: bytes, *, ttl_seconds: int) -> None:
+        if ttl_seconds < 1:
+            raise CacheError(f"ttl_seconds must be >= 1, got {ttl_seconds}")
+        self._wrap_errors(
+            "SET",
+            lambda: self._client.set(key, value, ex=ttl_seconds),
+        )
+
+    def set_if_absent(self, key: str, value: bytes, *, ttl_seconds: int) -> bool:
+        if ttl_seconds < 1:
+            raise CacheError(f"ttl_seconds must be >= 1, got {ttl_seconds}")
+        # SET NX EX = atomic
+        result = self._wrap_errors(
+            "SET NX EX",
+            lambda: self._client.set(key, value, ex=ttl_seconds, nx=True),
+        )
+        return bool(result)
+
+    def delete(self, key: str) -> None:
+        self._wrap_errors("DEL", lambda: self._client.delete(key))
+
+    def clear(self) -> None:
+        """Vide le cache (FLUSHDB). Dangereux en prod, utile en tests.
+
+        En mode cluster, ``FLUSHDB`` n'est **pas** un broadcast : par
+        défaut redis-py ne le route que vers le master "par défaut", ce
+        qui laisserait les autres shards intacts. On vise donc
+        explicitement ``RedisCluster.ALL_NODES`` pour flusher tous les
+        masters. En standalone, l'appel reste un simple ``FLUSHDB``.
+        """
+        if self._cluster:
+            from redis.cluster import RedisCluster  # noqa: PLC0415 — optional dep guard
+
+            self._wrap_errors(
+                "FLUSHDB ALL_NODES",
+                lambda: self._client.flushdb(target_nodes=RedisCluster.ALL_NODES),
+            )
+        else:
+            self._wrap_errors("FLUSHDB", self._client.flushdb)

mic/cache/cluster/__init__.py

@@ -0,0 +1,35 @@
+"""Redis Cluster / Valkey Cluster wrapper — sharding self-hosté multi-shards.
+
+Cf. ADR-0010 (docs/decisions/) — à 3M concurrent users, le
+cache distribué doit tenir >100k ops/s, ce qu'un Redis single-node
+ne fait pas. La solution canon est **Valkey Cluster** (fork BSD de
+Redis, gouvernance Linux Foundation neutre) ou Redis Cluster OSS.
+
+Briques publiques :
+
+- :class:`RedisClusterCache` — implémente :class:`mic.cache.CacheBackend`
+  par-dessus ``redis.cluster.RedisCluster``. Compatible avec Valkey
+  (wire-protocol identique).
+- :class:`ConsistentHashRing` — primitive de consistent hashing pour
+  les use-cases hors-Redis (ex: sharding application-level vers N
+  instances de service, fan-out vers M backends).
+
+Pour les opérations multi-keys atomiques (MGET, pipeline), utiliser
+les **hash tags** Redis : ``{tag}:key1`` et ``{tag}:key2`` tomberont
+sur le même slot (et donc le même shard), permettant un MGET en
+1 round-trip. Le wrapper expose ``RedisClusterCache.with_hash_tag(tag)``
+pour ce pattern.
+
+L'extra ``mic-struct[redis]`` (qui installe ``redis>=5.2``) suffit —
+``RedisCluster`` est natif depuis redis-py 4.x.
+"""
+
+from __future__ import annotations
+
+from mic.cache.cluster.consistent_hash import ConsistentHashRing
+from mic.cache.cluster.redis_cluster import RedisClusterCache
+
+__all__ = [
+    "ConsistentHashRing",
+    "RedisClusterCache",
+]

mic/cache/cluster/consistent_hash.py

@@ -0,0 +1,116 @@
+"""Consistent hashing ring — primitive pour le sharding non-Redis.
+
+Pour Redis Cluster / Valkey Cluster, **ne pas utiliser** : Redis fait
+son propre sharding via ses 16 384 hash slots. Cette brique sert :
+
+- au sharding application-level (fan-out vers N replicas d'un service
+  qui n'expose pas de cluster natif) ;
+- au routing déterministe vers M backends (ex: dispatcher de jobs
+  vers M workers où chaque worker possède un sous-ensemble) ;
+- au sharding Postgres si on n'utilise pas Citus (chaque shard
+  reçoit les rows dont ``hash(user_id)`` tombe dans son range).
+
+Algorithme : ring de virtuels nodes (``virtual_nodes`` par node
+physique, default 150) avec hash MD5. Donne une distribution
+quasi-uniforme et minimise la redistribution lors d'un add/remove
+node (~ 1/N keys re-mappées au lieu de toutes en hash naïf).
+
+L'API est délibérément **read-only** post-construction. Pour modifier
+le ring (add/remove node), construire un nouveau ring — c'est plus
+simple à raisonner concurremment.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from bisect import bisect_right
+from collections.abc import Iterable
+
+#: Nombre de virtuels nodes par node physique. 150 est le sweet spot
+#: documenté Cassandra/DynamoDB : la variance de distribution chute
+#: à <5 % au-delà, gain marginal au prix d'une mémoire ring plus
+#: grosse.
+DEFAULT_VIRTUAL_NODES = 150
+
+
+def _hash(key: str) -> int:
+    """Hash MD5 → entier 64-bit unsigned.
+
+    MD5 est cryptographiquement cassé pour les signatures, mais reste
+    un excellent hash uniforme pour le routing — c'est l'usage canon
+    Cassandra/Riak/etc. SHA-1 / SHA-256 sont plus lents pour aucun
+    bénéfice ici.
+    """
+    return int.from_bytes(hashlib.md5(key.encode(), usedforsecurity=False).digest()[:8])
+
+
+class ConsistentHashRing:
+    """Ring de consistent hashing pour le routing déterministe.
+
+    Construction :
+
+    >>> ring = ConsistentHashRing(nodes=("worker-1", "worker-2", "worker-3"))
+    >>> ring.node_for("user:42")
+    'worker-2'
+
+    Le ring est immutable : pour ajouter / retirer un node, construire
+    un nouveau ring. Les ré-affectations seront limitées à
+    ``~1/(N+1)`` des keys (vs **toutes** les keys avec un hash naïf
+    ``hash(key) % N``).
+
+    Args:
+        nodes: itérable des identifiants de nodes (chaînes uniques).
+        virtual_nodes: virtuels nodes par node physique (default 150).
+
+    Raises:
+        ValueError: si ``nodes`` est vide ou contient des doublons,
+            ou si ``virtual_nodes`` < 1.
+    """
+
+    def __init__(
+        self,
+        *,
+        nodes: Iterable[str],
+        virtual_nodes: int = DEFAULT_VIRTUAL_NODES,
+    ) -> None:
+        node_tuple = tuple(nodes)
+        if not node_tuple:
+            raise ValueError("ConsistentHashRing(nodes=...) must contain at least one node")
+        if len(set(node_tuple)) != len(node_tuple):
+            raise ValueError("ConsistentHashRing(nodes=...) must not contain duplicates")
+        if virtual_nodes < 1:
+            raise ValueError("virtual_nodes must be >= 1")
+
+        self._nodes = node_tuple
+        self._virtual_nodes = virtual_nodes
+
+        # Construit le ring : pour chaque node physique, on insère
+        # ``virtual_nodes`` points sur le ring. La key est triée par
+        # hash pour permettre un bisect O(log V·N) au routing.
+        ring: list[tuple[int, str]] = []
+        for node in node_tuple:
+            for vnode_index in range(virtual_nodes):
+                hash_value = _hash(f"{node}#{vnode_index}")
+                ring.append((hash_value, node))
+        ring.sort()
+        self._hashes: tuple[int, ...] = tuple(h for h, _ in ring)
+        self._owners: tuple[str, ...] = tuple(n for _, n in ring)
+
+    @property
+    def nodes(self) -> tuple[str, ...]:
+        """Liste des nodes physiques (ordre d'insertion préservé)."""
+        return self._nodes
+
+    def node_for(self, key: str) -> str:
+        """Retourne le node responsable de cette key.
+
+        Algorithme : on hash la key, on cherche le premier point du
+        ring ≥ ce hash (wrap-around vers le début si on dépasse).
+        """
+        key_hash = _hash(key)
+        # bisect_right : index du premier élément > key_hash. Si
+        # key_hash dépasse le dernier point du ring, on wrap au début.
+        index = bisect_right(self._hashes, key_hash)
+        if index == len(self._hashes):
+            index = 0
+        return self._owners[index]

mic/cache/cluster/redis_cluster.py

@@ -0,0 +1,191 @@
+"""``RedisClusterCache`` — ``CacheBackend`` au-dessus de Redis Cluster / Valkey.
+
+Le ``redis-py`` (≥ 5.2) embarque nativement ``RedisCluster`` — pas
+besoin de ``redis-py-cluster``. La même classe pilote indifféremment
+**Redis Cluster OSS** et **Valkey Cluster** (le wire-protocol est
+identique).
+
+Restrictions cluster (par rapport à un Redis single-node) :
+
+- **Pas de transactions multi-key** sauf si toutes les keys sont sur
+  le même slot. Utiliser les **hash tags** ``{tag}:key`` pour forcer
+  des keys liées (ex: ``{user:42}:profile`` et ``{user:42}:counters``)
+  sur le même slot.
+- **Pas de SELECT db** (Redis Cluster n'a qu'une DB 0). Le namespace
+  doit passer par un préfixe de key (``svc:env:bucket:key``).
+- **Pas de FLUSHALL trivial** : le wrapper itère sur tous les nodes
+  pour faire FLUSHDB par node (utilisé en tests uniquement).
+
+Pour les patterns multi-shards (lecture en éventail vers tous les
+shards), redis-py expose ``cluster_nodes()`` et permet d'instancier
+un client par node — pas dans le scope de cette brique, à ajouter
+si un consumer en a besoin.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from mic.cache.backends import CacheBackend, CacheError
+
+
+class RedisClusterCache(CacheBackend):
+    """Cache distribué multi-shards via Redis Cluster / Valkey Cluster.
+
+    Implémente :class:`mic.cache.CacheBackend` — les consumers qui
+    utilisent déjà ``RedisCache`` peuvent migrer en changeant
+    uniquement la construction du backend (pas d'appel-site à
+    modifier).
+
+    Construction :
+
+    >>> from mic.cache.cluster import RedisClusterCache  # doctest: +SKIP
+    >>> cache = RedisClusterCache(  # doctest: +SKIP
+    ...     startup_nodes=[
+    ...         ("redis-node-1.svc.cluster.local", 6379),
+    ...         ("redis-node-2.svc.cluster.local", 6379),
+    ...         ("redis-node-3.svc.cluster.local", 6379),
+    ...     ],
+    ... )
+    >>> cache.set("key", b"value", ttl_seconds=60)  # doctest: +SKIP
+
+    L'argument ``startup_nodes`` peut contenir 1 seul node — le client
+    découvre le reste de la topologie via ``CLUSTER NODES``. Donner
+    plusieurs nodes améliore la résilience au bootstrap (si un node
+    est down).
+    """
+
+    def __init__(
+        self,
+        *,
+        startup_nodes: Iterable[tuple[str, int]] | None = None,
+        client: Any = None,
+        decode_responses: bool = False,
+        require_full_coverage: bool = True,
+    ) -> None:
+        """Construit le cache.
+
+        Args:
+            startup_nodes: liste de tuples ``(host, port)`` pour le
+                bootstrap. Le client découvre le reste via
+                ``CLUSTER NODES``.
+            client: ``RedisCluster`` pré-construit (utile pour les
+                tests qui mockent). Si fourni, ``startup_nodes`` est
+                ignoré.
+            decode_responses: si True, les valeurs lues sont décodées
+                en str. Default False (bytes), aligné avec
+                :class:`RedisCache`.
+            require_full_coverage: si True (default), le client refuse
+                de booter si un slot du cluster est non-couvert.
+                Mettre à False uniquement pour des opérations de
+                maintenance (rebalance en cours).
+
+        Raises:
+            CacheError: si ``redis-py`` n'est pas installé, ou si
+                ni ``startup_nodes`` ni ``client`` n'est fourni.
+        """
+        if client is not None:
+            self._client = client
+            return
+
+        if not startup_nodes:
+            raise CacheError("RedisClusterCache: must pass either ``startup_nodes`` or ``client``")
+
+        try:
+            from redis.cluster import (  # noqa: PLC0415 — optional dep guard
+                ClusterNode,
+                RedisCluster,
+            )
+        except ImportError as exc:
+            raise CacheError(
+                "redis-py not installed. Install with: pip install 'mic-struct[redis]'"
+            ) from exc
+
+        nodes = [ClusterNode(host=host, port=port) for host, port in startup_nodes]  # type: ignore[no-untyped-call]
+        self._client = RedisCluster(
+            startup_nodes=nodes,
+            decode_responses=decode_responses,
+            require_full_coverage=require_full_coverage,
+        )
+
+    @property
+    def native(self) -> Any:
+        """Le ``redis.cluster.RedisCluster`` natif — escape-hatch pour les
+        opérations spécifiques cluster (CLUSTER NODES, KEYSLOT, fan-out
+        manuel par node, …). Aligné avec ``.native`` de :mod:`mic.datastorage`.
+        """
+        return self._client
+
+    @staticmethod
+    def _wrap_errors(op: str, fn: Callable[[], Any]) -> Any:
+        try:
+            return fn()
+        except Exception as exc:
+            raise CacheError(f"RedisCluster {op} failed: {exc}") from exc
+
+    def get(self, key: str) -> bytes | None:
+        result = self._wrap_errors("GET", lambda: self._client.get(key))
+        if result is None:
+            return None
+        if isinstance(result, str):
+            return result.encode()
+        return bytes(result)
+
+    def set(self, key: str, value: bytes, *, ttl_seconds: int) -> None:
+        if ttl_seconds < 1:
+            raise CacheError(f"ttl_seconds must be >= 1, got {ttl_seconds}")
+        self._wrap_errors(
+            "SET",
+            lambda: self._client.set(key, value, ex=ttl_seconds),
+        )
+
+    def set_if_absent(self, key: str, value: bytes, *, ttl_seconds: int) -> bool:
+        if ttl_seconds < 1:
+            raise CacheError(f"ttl_seconds must be >= 1, got {ttl_seconds}")
+        result = self._wrap_errors(
+            "SET NX EX",
+            lambda: self._client.set(key, value, ex=ttl_seconds, nx=True),
+        )
+        return bool(result)
+
+    def delete(self, key: str) -> None:
+        self._wrap_errors("DEL", lambda: self._client.delete(key))
+
+    def clear(self) -> None:
+        """Vide TOUS les shards. **Tests uniquement** — JAMAIS en prod.
+
+        FLUSHDB n'est pas un broadcast Redis Cluster, il faut le
+        router à chaque master node. ``redis-py`` le fait via
+        ``flushdb(target_nodes=ALL_NODES)``.
+        """
+        from redis.cluster import RedisCluster  # noqa: PLC0415
+
+        self._wrap_errors(
+            "FLUSHDB ALL_NODES",
+            lambda: self._client.flushdb(target_nodes=RedisCluster.ALL_NODES),
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers spécifiques cluster
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def hash_tagged(tag: str, key: str) -> str:
+        """Forge une key qui force le slot via hash tag Redis.
+
+        Pattern Redis Cluster : si une key contient ``{tag}``, le slot
+        est calculé sur ``tag`` uniquement — toutes les keys partageant
+        le même tag tombent sur le même slot, donc le même shard.
+        Permet les opérations multi-key (MGET, MSET, pipeline,
+        transactions) qui sinon échouent en cluster.
+
+        >>> RedisClusterCache.hash_tagged("user:42", "profile")
+        '{user:42}:profile'
+
+        Convention : utiliser ``hash_tagged(tenant_id, ...)``
+        pour grouper toutes les keys d'un tenant — permet de migrer
+        un tenant entier vers un shard dédié au moment d'un
+        rebalance.
+        """
+        return f"{{{tag}}}:{key}"