mic-datastore 0.1.0__tar.gz

mic_datastore-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Build / packaging
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+
+# OS / Editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.bak
+
+# Reports / temp
+reports/
+.benchmarks/
+.mutmut-cache/
+.wily/

mic_datastore-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: mic-datastore
+Version: 0.1.0
+Summary: MIC — persistance & messaging (datastorage, cache, shard, locking, outbox, eventbus, queue, idempotency, response_cache, read_models, realtime).
+License-Expression: MIT
+Requires-Python: >=3.14
+Requires-Dist: mic-core
+Provides-Extra: document
+Requires-Dist: pymongo<5,>=4.10; extra == 'document'
+Provides-Extra: graph
+Requires-Dist: neo4j<6,>=5.27; extra == 'graph'
+Provides-Extra: kafka
+Requires-Dist: aiokafka<1,>=0.12; extra == 'kafka'
+Provides-Extra: messaging
+Requires-Dist: aiokafka<1,>=0.12; extra == 'messaging'
+Requires-Dist: nats-py<3,>=2.7; extra == 'messaging'
+Provides-Extra: mongo
+Requires-Dist: pymongo<5,>=4.10; extra == 'mongo'
+Provides-Extra: mysql
+Requires-Dist: alembic<2,>=1.13; extra == 'mysql'
+Requires-Dist: pymysql<2,>=1.1; extra == 'mysql'
+Requires-Dist: sqlmodel<0.1,>=0.0.38; extra == 'mysql'
+Provides-Extra: nats
+Requires-Dist: nats-py<3,>=2.7; extra == 'nats'
+Provides-Extra: neo4j
+Requires-Dist: neo4j<6,>=5.27; extra == 'neo4j'
+Provides-Extra: oracle
+Requires-Dist: alembic<2,>=1.13; extra == 'oracle'
+Requires-Dist: oracledb<3,>=2.5; extra == 'oracle'
+Requires-Dist: sqlmodel<0.1,>=0.0.38; extra == 'oracle'
+Provides-Extra: postgres
+Requires-Dist: alembic<2,>=1.13; extra == 'postgres'
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'postgres'
+Requires-Dist: sqlmodel<0.1,>=0.0.38; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis<7,>=5.2; extra == 'redis'
+Provides-Extra: sql
+Requires-Dist: alembic<2,>=1.13; extra == 'sql'
+Requires-Dist: sqlmodel<0.1,>=0.0.38; extra == 'sql'
+Provides-Extra: ws
+Requires-Dist: mic-core[auth]; extra == 'ws'
+Requires-Dist: redis<7,>=5.2; extra == 'ws'
+Description-Content-Type: text/markdown
+
+# mic-datastore
+
+Briques de **persistance & messaging** du framework MIC. Dépend de `mic-core`
+(DAG `platform → data → core` — jamais l'inverse).
+
+## Modules
+
+| Module | Rôle |
+| -- | -- |
+| `mic.datastorage` | Backends de données : `SqlDataStorage`, `DocumentDataStorage` (MongoDB), `GraphDataStorage` (Neo4j), variantes in-memory |
+| `mic.cache` | Cache (in-memory / Redis) + `RevokeBlacklist` (révocation JWT) |
+| `mic.shard` | Sélection de shard / session factory |
+| `mic.locking` | Verrous distribués (in-memory / Redis) |
+| `mic.outbox` | Pattern transactional outbox + dispatcher |
+| `mic.eventbus` | Pub/sub synchrone (in-memory / Redis Streams) |
+| `mic.queue` | Event bus async durable (NATS JetStream / Kafka) |
+| `mic.idempotency` | Store d'idempotence |
+| `mic.response_cache` | Middleware de cache de réponses HTTP |
+| `mic.read_models` | Read-models (compteurs, leaderboards, timelines, HLL) |
+| `mic.realtime` | WebSocket realtime (backend Redis Streams) |
+
+Namespace **PEP 420** (pas de `mic/__init__.py`).
+
+## Installation
+
+```bash
+pip install "mic-datastore[postgres,redis]"
+```
+
+## Extras
+
+| Extra | Tire |
+| -- | -- |
+| `sql` | sqlmodel + alembic |
+| `postgres` / `mysql` / `oracle` | `sql` + driver (psycopg / PyMySQL / oracledb) |
+| `mongo` (alias `document`) | pymongo |
+| `neo4j` (alias `graph`) | neo4j |
+| `redis` | redis |
+| `nats` / `kafka` | nats-py / aiokafka |
+| `messaging` | `nats` + `kafka` |
+| `ws` | `redis` + `mic-core[auth]` |
+
+## Versionnage
+
+Brique volatile — reste en `0.x` plus longtemps que `mic-core`. Contraindre
+avec `>=0.1,<1`. Release : `make release-pkg PKG=data VERSION=x.y.z` → tag
+`data-vX.Y.Z` (cf. [`../../RELEASING.md`](../../RELEASING.md)).

mic_datastore-0.1.0/README.md

@@ -0,0 +1,47 @@
+# mic-datastore
+
+Briques de **persistance & messaging** du framework MIC. Dépend de `mic-core`
+(DAG `platform → data → core` — jamais l'inverse).
+
+## Modules
+
+| Module | Rôle |
+| -- | -- |
+| `mic.datastorage` | Backends de données : `SqlDataStorage`, `DocumentDataStorage` (MongoDB), `GraphDataStorage` (Neo4j), variantes in-memory |
+| `mic.cache` | Cache (in-memory / Redis) + `RevokeBlacklist` (révocation JWT) |
+| `mic.shard` | Sélection de shard / session factory |
+| `mic.locking` | Verrous distribués (in-memory / Redis) |
+| `mic.outbox` | Pattern transactional outbox + dispatcher |
+| `mic.eventbus` | Pub/sub synchrone (in-memory / Redis Streams) |
+| `mic.queue` | Event bus async durable (NATS JetStream / Kafka) |
+| `mic.idempotency` | Store d'idempotence |
+| `mic.response_cache` | Middleware de cache de réponses HTTP |
+| `mic.read_models` | Read-models (compteurs, leaderboards, timelines, HLL) |
+| `mic.realtime` | WebSocket realtime (backend Redis Streams) |
+
+Namespace **PEP 420** (pas de `mic/__init__.py`).
+
+## Installation
+
+```bash
+pip install "mic-datastore[postgres,redis]"
+```
+
+## Extras
+
+| Extra | Tire |
+| -- | -- |
+| `sql` | sqlmodel + alembic |
+| `postgres` / `mysql` / `oracle` | `sql` + driver (psycopg / PyMySQL / oracledb) |
+| `mongo` (alias `document`) | pymongo |
+| `neo4j` (alias `graph`) | neo4j |
+| `redis` | redis |
+| `nats` / `kafka` | nats-py / aiokafka |
+| `messaging` | `nats` + `kafka` |
+| `ws` | `redis` + `mic-core[auth]` |
+
+## Versionnage
+
+Brique volatile — reste en `0.x` plus longtemps que `mic-core`. Contraindre
+avec `>=0.1,<1`. Release : `make release-pkg PKG=data VERSION=x.y.z` → tag
+`data-vX.Y.Z` (cf. [`../../RELEASING.md`](../../RELEASING.md)).

mic_datastore-0.1.0/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_datastore-0.1.0/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_datastore-0.1.0/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_datastore-0.1.0/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]