muscles-data-redis 0.1.0__tar.gz

muscles_data_redis-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: muscles-data-redis
+Version: 0.1.0
+Summary: Redis KeyValuePort, LockPort and StreamPort adapter for muscles-data
+Author-email: "Denis B." <denis@butko.info>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles-data<1.0.0,>=0.1.0
+Requires-Dist: redis<9.0,>=5.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# muscles-data-redis
+
+Redis adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports, resource runtime and diagnostics, while this package owns
+Redis-backed `KeyValuePort`, `LockPort` and `StreamPort` implementations.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- MongoDB document-store adapter:
+  [`muscles-data-mongodb`](https://github.com/butkoden/muscles-data-mongodb)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- SQLAlchemy direct SQL resource adapter:
+  [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy)
+- Executable example:
+  [`example_data_redis_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_redis_1)
+
+## Usage
+
+Register the factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.ports import KeyValuePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_redis import RedisDataFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(RedisDataFactory())
+
+runtime = DataRuntime(config=config, catalog=catalog)
+cache = runtime.require_port("cache.redis", KeyValuePort)
+```
+
+Resource config stays in the project:
+
+```yaml
+data:
+  resources:
+    cache.redis:
+      type: redis
+      url_env: REDIS_URL
+      namespace: app
+      timeout: 3
+      stream_group: workers
+      consumer: index-worker
+```
+
+The adapter creates the Redis client lazily by key-value, lock, stream, explicit
+native access or `data.doctor` operations. Application code should use
+`KeyValuePort`, `LockPort` and `StreamPort`; direct client access is only an
+advanced escape hatch with `native_client: true`.
+
+Streams use `XADD`, `XREADGROUP` and `XACK`. The configured consumer group is
+created on first read and messages use the versioned
+`muscles.data.message.v1` envelope. Retry and dead-letter decisions stay with
+the application worker.
+
+See `muscular-example/example_data_redis_1` for an executable example.

muscles_data_redis-0.1.0/README.md

@@ -0,0 +1,69 @@
+# muscles-data-redis
+
+Redis adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports, resource runtime and diagnostics, while this package owns
+Redis-backed `KeyValuePort`, `LockPort` and `StreamPort` implementations.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- MongoDB document-store adapter:
+  [`muscles-data-mongodb`](https://github.com/butkoden/muscles-data-mongodb)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- SQLAlchemy direct SQL resource adapter:
+  [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy)
+- Executable example:
+  [`example_data_redis_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_redis_1)
+
+## Usage
+
+Register the factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.ports import KeyValuePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_redis import RedisDataFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(RedisDataFactory())
+
+runtime = DataRuntime(config=config, catalog=catalog)
+cache = runtime.require_port("cache.redis", KeyValuePort)
+```
+
+Resource config stays in the project:
+
+```yaml
+data:
+  resources:
+    cache.redis:
+      type: redis
+      url_env: REDIS_URL
+      namespace: app
+      timeout: 3
+      stream_group: workers
+      consumer: index-worker
+```
+
+The adapter creates the Redis client lazily by key-value, lock, stream, explicit
+native access or `data.doctor` operations. Application code should use
+`KeyValuePort`, `LockPort` and `StreamPort`; direct client access is only an
+advanced escape hatch with `native_client: true`.
+
+Streams use `XADD`, `XREADGROUP` and `XACK`. The configured consumer group is
+created on first read and messages use the versioned
+`muscles.data.message.v1` envelope. Retry and dead-letter decisions stay with
+the application worker.
+
+See `muscular-example/example_data_redis_1` for an executable example.

muscles_data_redis-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "muscles-data-redis"
+version = "0.1.0"
+description = "Redis KeyValuePort, LockPort and StreamPort adapter for muscles-data"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Denis B.", email = "denis@butko.info" }]
+dependencies = [
+  "muscles-data>=0.1.0,<1.0.0",
+  "redis>=5.0,<9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "integration: tests that require the local backend integration stack",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

muscles_data_redis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

muscles_data_redis-0.1.0/src/muscles_data_redis/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .adapter import (
+    RedisAdapterError,
+    RedisClientMissingError,
+    RedisConfigError,
+    RedisConnectionError,
+    RedisDataAdapter,
+    RedisDataFactory,
+)
+
+
+__all__ = [
+    "RedisAdapterError",
+    "RedisClientMissingError",
+    "RedisConfigError",
+    "RedisConnectionError",
+    "RedisDataAdapter",
+    "RedisDataFactory",
+]

muscles_data_redis-0.1.0/src/muscles_data_redis/adapter.py

@@ -0,0 +1,419 @@
+from __future__ import annotations
+
+import importlib
+import json
+import threading
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import asdict
+from typing import Any, Mapping
+from urllib.parse import urlsplit
+
+from muscles_data.config import DataResourceConfig
+from muscles_data.errors import DataConfigurationError, DataConnectionError, DataError
+from muscles_data.models import DataCapability, HealthResult, InspectResult, LockHandle, StreamReadResult, WriteResult
+
+
+_CLIENT_UNSET = object()
+_ALLOWED_OPTIONS = {
+    "url",
+    "url_env",
+    "namespace",
+    "decode_responses",
+    "timeout",
+    "socket_timeout",
+    "socket_connect_timeout",
+    "stream_group",
+    "consumer",
+    "native_client",
+}
+_LOCK_RELEASE_SCRIPT = """
+local token = redis.call('get', KEYS[1])
+if not token or token ~= ARGV[1] then
+    return 0
+end
+redis.call('del', KEYS[1])
+return 1
+"""
+
+
+class RedisAdapterError(DataError):
+    """Base error for Redis data adapter failures."""
+
+
+class RedisConfigError(ValueError, DataConfigurationError, RedisAdapterError):
+    """Raised when a Redis resource config cannot be mapped safely."""
+
+
+class RedisClientMissingError(DataConfigurationError, RedisAdapterError):
+    """Raised when Redis adapter is used without an available client."""
+
+
+class RedisConnectionError(DataConnectionError, RedisAdapterError):
+    """Raised when a Redis operation cannot reach or use the backend."""
+
+
+class RedisDataAdapter:
+    resource_type = "redis"
+
+    def __init__(
+        self,
+        config: DataResourceConfig,
+        *,
+        client_factory: Callable[[DataResourceConfig], Any] | None = None,
+    ) -> None:
+        self.config = config
+        self._client_factory = client_factory
+        self._client: Any = _CLIENT_UNSET
+        self._lock = threading.RLock()
+        self.closed = False
+
+    def get(self, key: str) -> bytes | None:
+        try:
+            value = self._client_instance().get(self._key(key))
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+        return _bytes_or_none(value)
+
+    def set(self, key: str, value: bytes, ttl_seconds: float | None = None) -> WriteResult:
+        kwargs: dict[str, Any] = {}
+        if ttl_seconds is not None:
+            kwargs["px"] = _ttl_ms(ttl_seconds, "Redis key ttl_seconds")
+        try:
+            written = bool(self._client_instance().set(self._key(key), bytes(value), **kwargs))
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+        return WriteResult(written=1 if written else 0, matched=1 if written else 0)
+
+    def delete(self, key: str) -> WriteResult:
+        try:
+            deleted = int(self._client_instance().delete(self._key(key)) or 0)
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+        return WriteResult(deleted=deleted, matched=deleted)
+
+    def exists(self, key: str) -> bool:
+        try:
+            return bool(self._client_instance().exists(self._key(key)))
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+
+    def acquire_lock(self, name: str, ttl_seconds: float):
+        ttl_ms = _ttl_ms(ttl_seconds, "Redis lock ttl_seconds")
+        token = uuid.uuid4().hex
+        lock_key = self._lock_key(name)
+        try:
+            acquired = bool(self._client_instance().set(lock_key, token, nx=True, px=ttl_ms))
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+        if not acquired:
+            return None
+        return LockHandle(name=str(name), token=token, expires_at=time.monotonic() + float(ttl_seconds))
+
+    def release_lock(self, handle) -> WriteResult:
+        if handle is None:
+            return WriteResult()
+        name = getattr(handle, "name", None)
+        token = getattr(handle, "token", None)
+        if not name or not token:
+            raise RedisConfigError("Redis lock handle requires name and token")
+        try:
+            deleted = int(self._client_instance().eval(_LOCK_RELEASE_SCRIPT, 1, self._lock_key(str(name)), str(token)) or 0)
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+        matched = 1 if deleted else 0
+        return WriteResult(deleted=matched, matched=matched)
+
+    def publish(self, stream: str, message: Mapping[str, Any]) -> WriteResult:
+        try:
+            message_id = self._client_instance().xadd(self._stream_key(stream), _stream_fields(message))
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+        return WriteResult(written=1, matched=1, message_id=_text(message_id))
+
+    def read(self, stream: str, cursor: str | None = None, limit: int = 100) -> StreamReadResult:
+        if limit <= 0:
+            return StreamReadResult(messages=[], cursor=cursor)
+        stream_name = str(stream)
+        stream_key = self._stream_key(stream_name)
+        try:
+            self._ensure_group(stream_key)
+            response = self._client_instance().xreadgroup(
+                self.stream_group(),
+                self.consumer_name(),
+                {stream_key: cursor or ">"},
+                count=max(0, int(limit)),
+            )
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+
+        messages: list[dict[str, Any]] = []
+        next_cursor = cursor
+        for _raw_name, entries in response or []:
+            for message_id, fields in entries:
+                normalized_id = _text(message_id)
+                messages.append(
+                    {
+                        "stream": stream_name,
+                        "id": normalized_id,
+                        **_decode_envelope(fields),
+                    }
+                )
+                next_cursor = normalized_id
+        return StreamReadResult(messages=messages, cursor=next_cursor)
+
+    def ack(self, stream: str, message_id: str) -> WriteResult:
+        group = self.stream_group()
+        try:
+            matched = int(self._client_instance().xack(self._stream_key(stream), group, str(message_id)) or 0)
+        except (RedisClientMissingError, RedisConfigError):
+            raise
+        except Exception as exc:
+            raise RedisConnectionError(self._safe_error(exc)) from exc
+        return WriteResult(matched=matched)
+
+    def inspect(self) -> dict[str, Any]:
+        return asdict(
+            InspectResult(
+                name=self.config.name,
+                type=self.config.type,
+                capabilities=[],
+                initialized=self._client is not _CLIENT_UNSET,
+                status="ok",
+                options=self.config.safe_options(),
+                details={
+                    "backend": "redis",
+                    "namespace_enabled": bool(self.namespace()),
+                    "stream_group": self.stream_group(),
+                },
+            )
+        )
+
+    def health(self) -> HealthResult:
+        try:
+            ping = bool(self._client_instance().ping())
+        except DataConfigurationError as exc:
+            return HealthResult(status="failed", code="configuration_error", message=str(exc))
+        except Exception as exc:
+            return HealthResult(status="failed", code="connection_failed", message=self._safe_error(exc))
+        if not ping:
+            return HealthResult(status="failed", code="connection_failed", message="Redis ping failed")
+        return HealthResult(status="ok", code="ok", message="Redis connection is available")
+
+    def close(self) -> None:
+        if self._client is _CLIENT_UNSET:
+            self.closed = True
+            return
+        close = getattr(self._client, "close", None)
+        if callable(close):
+            close()
+        self.closed = True
+
+    def native_client(self):
+        return self._client_instance()
+
+    def namespace(self) -> str:
+        return str(self.config.options.get("namespace", "")).strip(":")
+
+    def stream_group(self) -> str:
+        group = str(self.config.options.get("stream_group", "default"))
+        if not group:
+            raise RedisConfigError("Redis stream_group must not be empty")
+        return group
+
+    def consumer_name(self) -> str:
+        consumer = str(self.config.options.get("consumer", "muscles-worker"))
+        if not consumer:
+            raise RedisConfigError("Redis consumer must not be empty")
+        return consumer
+
+    def _ensure_group(self, stream_key: str) -> None:
+        create = getattr(self._client_instance(), "xgroup_create", None)
+        if not callable(create):
+            raise RedisConfigError("Redis client does not support consumer groups")
+        try:
+            create(stream_key, self.stream_group(), id="0-0", mkstream=True)
+        except Exception as exc:
+            if "busygroup" not in str(exc).lower() and "already exists" not in str(exc).lower():
+                raise RedisConnectionError(self._safe_error(exc)) from exc
+
+    def _key(self, key: str) -> str:
+        normalized = _name(key, "Redis key")
+        namespace = self.namespace()
+        return f"{namespace}:{normalized}" if namespace else normalized
+
+    def _lock_key(self, name: str) -> str:
+        return self._key(f"lock:{_name(name, 'Redis lock name')}")
+
+    def _stream_key(self, stream: str) -> str:
+        return self._key(f"stream:{_name(stream, 'Redis stream name')}")
+
+    def _client_instance(self):
+        if self._client is _CLIENT_UNSET:
+            with self._lock:
+                if self._client is _CLIENT_UNSET:
+                    self._validate_options()
+                    client = (
+                        self._client_factory(self.config)
+                        if self._client_factory
+                        else _default_redis_client(self.config)
+                    )
+                    if client is None:
+                        raise RedisClientMissingError("Redis client is not available")
+                    self._client = client
+        return self._client
+
+    def _validate_options(self) -> None:
+        unknown = sorted(set(self.config.options) - _ALLOWED_OPTIONS)
+        if unknown:
+            names = ", ".join(unknown)
+            raise RedisConfigError(f"Unsupported Redis resource options: {names}")
+        if not self.config.options.get("url") and not self.config.options.get("url_env"):
+            raise RedisConfigError("Redis resource requires url_env")
+        for option in ("timeout", "socket_timeout", "socket_connect_timeout"):
+            if option in self.config.options and float(self.config.options[option]) <= 0:
+                raise RedisConfigError(f"Redis {option} must be positive")
+
+    def _safe_error(self, exc: Exception) -> str:
+        message = str(exc)
+        try:
+            url = str(self.config.resolved_options().get("url", ""))
+        except DataConfigurationError:
+            url = str(self.config.options.get("url", ""))
+        sensitive_values = {url}
+        try:
+            parsed = urlsplit(url)
+            if parsed.username:
+                sensitive_values.add(parsed.username)
+            if parsed.password:
+                sensitive_values.add(parsed.password)
+        except Exception:  # pragma: no cover
+            pass
+        for value in sorted((item for item in sensitive_values if item), key=len, reverse=True):
+            message = message.replace(value, "***")
+        return message
+
+
+class RedisDataFactory:
+    resource_type = "redis"
+
+    def __init__(self, *, client_factory: Callable[[DataResourceConfig], Any] | None = None) -> None:
+        self._client_factory = client_factory
+
+    def capabilities(self, config: DataResourceConfig) -> set[DataCapability]:
+        native = {DataCapability.NATIVE_CLIENT} if bool(config.options.get("native_client")) else set()
+        return {
+            DataCapability.KEY_VALUE,
+            DataCapability.CACHE,
+            DataCapability.LOCK,
+            DataCapability.STREAM,
+            DataCapability.HEALTHCHECK,
+        } | native
+
+    def create(self, config: DataResourceConfig) -> RedisDataAdapter:
+        return RedisDataAdapter(config, client_factory=self._client_factory)
+
+
+def _default_redis_client(config: DataResourceConfig):
+    try:
+        redis_module = importlib.import_module("redis")
+    except ImportError as exc:
+        raise RedisClientMissingError("redis package is not installed; install muscles-data-redis") from exc
+    redis_cls = getattr(redis_module, "Redis", None)
+    from_url = getattr(redis_cls, "from_url", None) if redis_cls is not None else None
+    if from_url is None:
+        from_url = getattr(redis_module, "from_url", None)
+    if from_url is None:
+        raise RedisClientMissingError("redis package does not expose Redis.from_url")
+
+    options = config.resolved_options()
+    kwargs: dict[str, Any] = {}
+    kwargs["decode_responses"] = bool(options.get("decode_responses", False))
+    timeout = options.get("timeout")
+    if timeout is not None:
+        kwargs["socket_timeout"] = float(timeout)
+        kwargs["socket_connect_timeout"] = float(timeout)
+    for option in ("socket_timeout", "socket_connect_timeout"):
+        if option in options:
+            kwargs[option] = float(options[option])
+    return from_url(str(options["url"]), **kwargs)
+
+
+def _ttl_ms(value: float, label: str) -> int:
+    seconds = float(value)
+    if seconds <= 0:
+        raise RedisConfigError(f"{label} must be positive")
+    return max(1, int(seconds * 1000))
+
+
+def _name(value: str, label: str) -> str:
+    normalized = str(value).strip()
+    if not normalized:
+        raise RedisConfigError(f"{label} must not be empty")
+    return normalized.strip(":")
+
+
+def _bytes_or_none(value: Any) -> bytes | None:
+    if value is None:
+        return None
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, bytearray):
+        return bytes(value)
+    if isinstance(value, memoryview):
+        return value.tobytes()
+    return str(value).encode("utf-8")
+
+
+def _text(value: Any) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    return str(value)
+
+
+def _stream_fields(message: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "_schema": "muscles.data.message.v1",
+        "_payload": json.dumps(dict(message), ensure_ascii=False, sort_keys=True),
+    }
+
+
+def _read_fields(fields: Mapping[Any, Any]) -> dict[str, Any]:
+    return {_text(key): _decode_stream_value(value) for key, value in dict(fields).items()}
+
+
+def _decode_stream_value(value: Any) -> Any:
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    return value
+
+
+def _decode_envelope(fields: Mapping[Any, Any]) -> dict[str, Any]:
+    normalized = _read_fields(fields)
+    try:
+        payload = json.loads(str(normalized.get("_payload", "{}")))
+    except (TypeError, ValueError) as exc:
+        raise RedisConnectionError("Redis stream message has invalid envelope payload") from exc
+    if not isinstance(payload, dict):
+        raise RedisConnectionError("Redis stream message envelope payload must be an object")
+    return {
+        "fields": payload,
+        "envelope": {"version": 1, "schema": normalized.get("_schema")},
+    }

muscles_data_redis-0.1.0/src/muscles_data_redis.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: muscles-data-redis
+Version: 0.1.0
+Summary: Redis KeyValuePort, LockPort and StreamPort adapter for muscles-data
+Author-email: "Denis B." <denis@butko.info>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles-data<1.0.0,>=0.1.0
+Requires-Dist: redis<9.0,>=5.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# muscles-data-redis
+
+Redis adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports, resource runtime and diagnostics, while this package owns
+Redis-backed `KeyValuePort`, `LockPort` and `StreamPort` implementations.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- MongoDB document-store adapter:
+  [`muscles-data-mongodb`](https://github.com/butkoden/muscles-data-mongodb)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- SQLAlchemy direct SQL resource adapter:
+  [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy)
+- Executable example:
+  [`example_data_redis_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_redis_1)
+
+## Usage
+
+Register the factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.ports import KeyValuePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_redis import RedisDataFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(RedisDataFactory())
+
+runtime = DataRuntime(config=config, catalog=catalog)
+cache = runtime.require_port("cache.redis", KeyValuePort)
+```
+
+Resource config stays in the project:
+
+```yaml
+data:
+  resources:
+    cache.redis:
+      type: redis
+      url_env: REDIS_URL
+      namespace: app
+      timeout: 3
+      stream_group: workers
+      consumer: index-worker
+```
+
+The adapter creates the Redis client lazily by key-value, lock, stream, explicit
+native access or `data.doctor` operations. Application code should use
+`KeyValuePort`, `LockPort` and `StreamPort`; direct client access is only an
+advanced escape hatch with `native_client: true`.
+
+Streams use `XADD`, `XREADGROUP` and `XACK`. The configured consumer group is
+created on first read and messages use the versioned
+`muscles.data.message.v1` envelope. Retry and dead-letter decisions stay with
+the application worker.
+
+See `muscular-example/example_data_redis_1` for an executable example.

muscles_data_redis-0.1.0/src/muscles_data_redis.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/muscles_data_redis/__init__.py
+src/muscles_data_redis/adapter.py
+src/muscles_data_redis.egg-info/PKG-INFO
+src/muscles_data_redis.egg-info/SOURCES.txt
+src/muscles_data_redis.egg-info/dependency_links.txt
+src/muscles_data_redis.egg-info/requires.txt
+src/muscles_data_redis.egg-info/top_level.txt
+tests/test_integration.py
+tests/test_redis_adapter.py

muscles_data_redis-0.1.0/src/muscles_data_redis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

muscles_data_redis-0.1.0/src/muscles_data_redis.egg-info/requires.txt

@@ -0,0 +1,5 @@
+muscles-data<1.0.0,>=0.1.0
+redis<9.0,>=5.0
+
+[dev]
+pytest<9.0,>=8.0

muscles_data_redis-0.1.0/src/muscles_data_redis.egg-info/top_level.txt

@@ -0,0 +1 @@
+muscles_data_redis

muscles_data_redis-0.1.0/tests/test_integration.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+import time
+from uuid import uuid4
+
+import pytest
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.ports import KeyValuePort, LockPort, StreamPort
+from muscles_data.runtime import DataRuntime
+
+from muscles_data_redis import RedisDataFactory
+
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(not os.getenv("MUSCLES_DATA_INTEGRATION"), reason="backend integration is disabled"),
+]
+
+
+def test_redis_real_kv_lock_stream_lifecycle():
+    namespace = f"muscles-data-it-{uuid4().hex[:12]}"
+    config = DataConfig.from_raw(
+        {
+            "data": {
+                "resources": {
+                    "cache.redis": {
+                        "type": "redis",
+                        "url_env": "REDIS_URL",
+                        "namespace": namespace,
+                        "stream_group": f"group-{namespace}",
+                        "consumer": f"consumer-{namespace}",
+                    }
+                }
+            }
+        }
+    )
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(RedisDataFactory())
+    runtime = DataRuntime(config=config, catalog=catalog)
+
+    try:
+        key_value = runtime.require_port("cache.redis", KeyValuePort)
+        lock = runtime.require_port("cache.redis", LockPort)
+        stream = runtime.require_port("cache.redis", StreamPort)
+        contracts = pytest.importorskip("muscles_data.contracts")
+        for name, port in (
+            ("assert_key_value_contract", key_value),
+            ("assert_lock_contract", lock),
+            ("assert_stream_contract", stream),
+        ):
+            contract = getattr(contracts, name, None)
+            if contract is not None:
+                contract(lambda port=port: port)
+        assert key_value.set("ttl", b"short", ttl_seconds=0.1).written == 1
+        time.sleep(0.2)
+        assert key_value.exists("ttl") is False
+        assert runtime.doctor()["status"] == "ok"
+    finally:
+        runtime.close()

muscles_data_redis-0.1.0/tests/test_redis_adapter.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.models import DataCapability, LockHandle
+from muscles_data.ports import KeyValuePort, LockPort, StreamPort
+from muscles_data.runtime import DataRuntime
+
+from muscles_data_redis import RedisClientMissingError, RedisConfigError, RedisConnectionError, RedisDataFactory
+
+
+class FakeRedisClient:
+    def __init__(self, *, fail_ping: bool = False) -> None:
+        self.fail_ping = fail_ping
+        self.values: dict[str, Any] = {}
+        self.sets: list[dict[str, Any]] = []
+        self.deletes: list[tuple[str, ...]] = []
+        self.streams: dict[str, list[tuple[str, dict[str, Any]]]] = {}
+        self.xacks: list[dict[str, Any]] = []
+        self.xgroups: list[dict[str, Any]] = []
+        self.pings = 0
+        self.closed = False
+
+    def set(self, name: str, value, **kwargs):
+        self.sets.append({"name": name, "value": value, **kwargs})
+        if kwargs.get("nx") and name in self.values:
+            return False
+        self.values[name] = value
+        return True
+
+    def get(self, name: str):
+        return self.values.get(name)
+
+    def delete(self, *names: str) -> int:
+        self.deletes.append(tuple(names))
+        deleted = 0
+        for name in names:
+            deleted += 1 if self.values.pop(name, None) is not None else 0
+        return deleted
+
+    def exists(self, *names: str) -> int:
+        return sum(1 for name in names if name in self.values)
+
+    def eval(self, _script: str, _numkeys: int, key: str, expected_token: str):
+        if self.values.get(key) != expected_token:
+            return 0
+        self.values.pop(key, None)
+        return 1
+
+    def xadd(self, name: str, fields: dict[str, Any]):
+        stream = self.streams.setdefault(name, [])
+        message_id = f"{len(stream) + 1}-0"
+        stream.append((message_id, dict(fields)))
+        return message_id
+
+    def xread(self, streams: dict[str, str], count: int | None = None, block: int | None = None):
+        del block
+        output = []
+        for name, cursor in streams.items():
+            messages = [
+                (message_id, fields)
+                for message_id, fields in self.streams.get(name, [])
+                if cursor in {"0", "0-0", ">"} or message_id > cursor
+            ]
+            output.append((name, messages[:count]))
+        return output
+
+    def xgroup_create(self, name: str, groupname: str, id: str = "0-0", mkstream: bool = False):
+        self.xgroups.append({"name": name, "groupname": groupname, "id": id, "mkstream": mkstream})
+
+    def xreadgroup(self, groupname: str, consumername: str, streams: dict[str, str], count: int | None = None, block: int | None = None):
+        del groupname, consumername, block
+        return self.xread(streams, count=count)
+
+    def xack(self, name: str, groupname: str, *ids: str) -> int:
+        self.xacks.append({"name": name, "groupname": groupname, "ids": ids})
+        known = {message_id for message_id, _fields in self.streams.get(name, [])}
+        return sum(1 for message_id in ids if message_id in known)
+
+    def ping(self) -> bool:
+        self.pings += 1
+        if self.fail_ping:
+            raise TimeoutError("redis password=redis-secret timed out")
+        return True
+
+    def close(self) -> None:
+        self.closed = True
+
+
+def _config() -> dict:
+    return {
+        "data": {
+            "resources": {
+                "cache.redis": {
+                    "type": "redis",
+                    "url": "redis://:redis-secret@localhost:6379/0",
+                    "namespace": "app",
+                    "stream_group": "workers",
+                    "native_client": True,
+                }
+            }
+        }
+    }
+
+
+def _runtime(client: FakeRedisClient | None):
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(RedisDataFactory(client_factory=lambda _config: client))
+    return DataRuntime(config=DataConfig.from_raw(_config()), catalog=catalog)
+
+
+def test_redis_external_adapter_maps_key_value_lock_stream_and_native_access():
+    client = FakeRedisClient()
+    runtime = _runtime(client)
+
+    listed = runtime.list_resources()[0]
+    assert listed["type"] == "redis"
+    assert {"key_value", "cache", "lock", "stream"} <= set(listed["capabilities"])
+    assert listed["initialized"] is False
+
+    cache = runtime.require_port("cache.redis", KeyValuePort)
+    assert cache.set("cursor", b"cursor-1", ttl_seconds=2.5).written == 1
+    assert client.sets[0]["name"] == "app:cursor"
+    assert client.sets[0]["px"] == 2500
+    assert cache.get("cursor") == b"cursor-1"
+    assert cache.exists("cursor") is True
+
+    lock = runtime.require_port("cache.redis", LockPort)
+    handle = lock.acquire_lock("daily-job", ttl_seconds=5)
+    assert isinstance(handle, LockHandle)
+    assert lock.release_lock(handle).deleted == 1
+
+    stream = runtime.require_port("cache.redis", StreamPort)
+    assert stream.publish("events", {"kind": "created"}).written == 1
+    read = stream.read("events", limit=10)
+    assert read.messages[0]["fields"] == {"kind": "created"}
+    assert read.messages[0]["envelope"]["version"] == 1
+    assert stream.ack("events", "1-0").matched == 1
+    assert client.xgroups[0]["groupname"] == "workers"
+
+    native = runtime.require_resource("cache.redis", DataCapability.NATIVE_CLIENT).native_client()
+    assert native is client
+    assert runtime.doctor()["status"] == "ok"
+    assert client.pings == 1
+    assert runtime.close()["status"] == "ok"
+    assert client.closed is True
+
+
+def test_redis_external_adapter_reports_safe_failures():
+    with pytest.raises(RedisClientMissingError):
+        _runtime(None).require_port("cache.redis", KeyValuePort).get("cursor")
+
+    failing = _runtime(FakeRedisClient(fail_ping=True)).doctor()
+    assert failing["status"] == "failed"
+    assert "redis-secret" not in repr(failing)
+
+    bad_client = FakeRedisClient()
+    bad_client.get = lambda _name: (_ for _ in ()).throw(RuntimeError("redis://:redis-secret@localhost unavailable"))
+    with pytest.raises(RedisConnectionError):
+        _runtime(bad_client).require_port("cache.redis", KeyValuePort).get("cursor")
+
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(RedisDataFactory(client_factory=lambda config: config.resolved_options()))
+    unsupported = DataRuntime(
+        config=DataConfig.from_raw({"data": {"resources": {"cache.redis": {"type": "redis", "url": "redis://localhost", "unsafe": True}}}}),
+        catalog=catalog,
+    )
+    with pytest.raises(RedisConfigError, match="Unsupported Redis resource options"):
+        unsupported.require_port("cache.redis", KeyValuePort).get("cursor")
+
+
+def test_redis_stream_uses_consumer_groups_and_resolves_url_env(monkeypatch):
+    monkeypatch.setenv("REDIS_URL", "redis://localhost:6379/0")
+    client = FakeRedisClient()
+    captured: list[dict] = []
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(
+        RedisDataFactory(client_factory=lambda config: captured.append(config.resolved_options()) or client)
+    )
+    runtime = DataRuntime(
+        config=DataConfig.from_raw(
+            {
+                "data": {
+                    "resources": {
+                        "stream.redis": {
+                            "type": "redis",
+                            "url_env": "REDIS_URL",
+                            "namespace": "assetforge",
+                            "stream_group": "workers",
+                            "consumer": "worker-1",
+                        }
+                    }
+                }
+            }
+        ),
+        catalog=catalog,
+    )
+
+    stream = runtime.require_port("stream.redis", StreamPort)
+    stream.publish("index", {"job": "reindex"})
+    stream.read("index")
+
+    assert captured[0]["url"] == "redis://localhost:6379/0"
+    assert client.xgroups[0]["mkstream"] is True
+
+
+def test_redis_doctor_reports_configuration_error_for_missing_url_env():
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(RedisDataFactory(client_factory=lambda config: config.resolved_options()))
+    runtime = DataRuntime(
+        config=DataConfig.from_raw(
+            {"data": {"resources": {"stream.redis": {"type": "redis", "url_env": "MISSING_REDIS_URL"}}}}
+        ),
+        catalog=catalog,
+    )
+
+    doctor = runtime.doctor()
+    check = doctor["checks"][0]
+    assert check["status"] == "failed"
+    assert check["code"] == "configuration_error"