spakky-redis 6.3.1__tar.gz

spakky_redis-6.3.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.3
+Name: spakky-redis
+Version: 6.3.1
+Summary: Redis cache backend plugin for Spakky Framework
+Author: Spakky
+Author-email: Spakky <sejong418@icloud.com>
+License: MIT
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: redis>=7.1.0
+Requires-Dist: spakky-cache>=6.3.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Spakky Redis
+
+Redis cache backend plugin for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-redis
+```
+
+## Features
+
+- **Shared cache backend**: `RedisCache[T]` stores values in Redis so multiple process instances can observe the same entries.
+- **Core contract compatibility**: Implements `spakky-cache` sync and async `ICache[T]` paths.
+- **TTL semantics**: Positive TTL values are translated into Redis millisecond expiry; missing and expired keys return `CacheMiss`.
+- **Loud failures**: Redis connection/configuration failures and serialization failures are raised as Spakky cache errors.
+- **Scoped clear**: `clear` removes keys under the configured prefix instead of flushing the Redis database.
+
+## Quick Start
+
+```python
+from datetime import timedelta
+
+from spakky.cache import CacheHit
+from spakky.plugins.redis import RedisCache
+
+cache = RedisCache[str]()
+cache.set("profile:42", "Ada", ttl=timedelta(minutes=5))
+
+result = cache.get("profile:42")
+if isinstance(result, CacheHit):
+    print(result.value)
+```
+
+## Configuration
+
+`RedisCacheConfig` follows the standard Spakky `@Configuration` pattern and reads environment variables with the `SPAKKY_REDIS__` prefix.
+
+| Environment variable | Default |
+|----------------------|---------|
+| `SPAKKY_REDIS__HOST` | `localhost` |
+| `SPAKKY_REDIS__PORT` | `6379` |
+| `SPAKKY_REDIS__DB` | `0` |
+| `SPAKKY_REDIS__USERNAME` | unset |
+| `SPAKKY_REDIS__PASSWORD` | unset |
+| `SPAKKY_REDIS__USE_SSL` | `false` |
+| `SPAKKY_REDIS__KEY_PREFIX` | `spakky:cache:` |
+| `SPAKKY_REDIS__SOCKET_TIMEOUT` | `5.0` |
+
+## Async Usage
+
+```python
+from spakky.cache import CacheHit
+from spakky.plugins.redis import RedisCache
+
+cache = RedisCache[int]()
+await cache.set_async("answer", 42)
+
+result = await cache.get_async("answer")
+if isinstance(result, CacheHit):
+    assert result.value == 42
+```
+
+## Contract Notes
+
+`RedisCache` is a backend implementation of the `spakky-cache` application data cache contract. Business code should depend on `ICache[T]` and can switch between `InMemoryCache` and `RedisCache` without changing cache hit/miss handling.
+
+Values are serialized with pickle and stored under `SPAKKY_REDIS__KEY_PREFIX`. `clear()` and `clear_async()` delete only keys under that prefix. Redis failures, unexpected response types, and serialization failures are raised as Spakky cache errors instead of being treated as cache misses.
+
+This plugin does not add distributed locks, cache stampede protection, tag invalidation, write-through/write-behind policies, or metrics exporters.
+
+## License
+
+MIT License

spakky_redis-6.3.1/README.md

@@ -0,0 +1,74 @@
+# Spakky Redis
+
+Redis cache backend plugin for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-redis
+```
+
+## Features
+
+- **Shared cache backend**: `RedisCache[T]` stores values in Redis so multiple process instances can observe the same entries.
+- **Core contract compatibility**: Implements `spakky-cache` sync and async `ICache[T]` paths.
+- **TTL semantics**: Positive TTL values are translated into Redis millisecond expiry; missing and expired keys return `CacheMiss`.
+- **Loud failures**: Redis connection/configuration failures and serialization failures are raised as Spakky cache errors.
+- **Scoped clear**: `clear` removes keys under the configured prefix instead of flushing the Redis database.
+
+## Quick Start
+
+```python
+from datetime import timedelta
+
+from spakky.cache import CacheHit
+from spakky.plugins.redis import RedisCache
+
+cache = RedisCache[str]()
+cache.set("profile:42", "Ada", ttl=timedelta(minutes=5))
+
+result = cache.get("profile:42")
+if isinstance(result, CacheHit):
+    print(result.value)
+```
+
+## Configuration
+
+`RedisCacheConfig` follows the standard Spakky `@Configuration` pattern and reads environment variables with the `SPAKKY_REDIS__` prefix.
+
+| Environment variable | Default |
+|----------------------|---------|
+| `SPAKKY_REDIS__HOST` | `localhost` |
+| `SPAKKY_REDIS__PORT` | `6379` |
+| `SPAKKY_REDIS__DB` | `0` |
+| `SPAKKY_REDIS__USERNAME` | unset |
+| `SPAKKY_REDIS__PASSWORD` | unset |
+| `SPAKKY_REDIS__USE_SSL` | `false` |
+| `SPAKKY_REDIS__KEY_PREFIX` | `spakky:cache:` |
+| `SPAKKY_REDIS__SOCKET_TIMEOUT` | `5.0` |
+
+## Async Usage
+
+```python
+from spakky.cache import CacheHit
+from spakky.plugins.redis import RedisCache
+
+cache = RedisCache[int]()
+await cache.set_async("answer", 42)
+
+result = await cache.get_async("answer")
+if isinstance(result, CacheHit):
+    assert result.value == 42
+```
+
+## Contract Notes
+
+`RedisCache` is a backend implementation of the `spakky-cache` application data cache contract. Business code should depend on `ICache[T]` and can switch between `InMemoryCache` and `RedisCache` without changing cache hit/miss handling.
+
+Values are serialized with pickle and stored under `SPAKKY_REDIS__KEY_PREFIX`. `clear()` and `clear_async()` delete only keys under that prefix. Redis failures, unexpected response types, and serialization failures are raised as Spakky cache errors instead of being treated as cache misses.
+
+This plugin does not add distributed locks, cache stampede protection, tag invalidation, write-through/write-behind policies, or metrics exporters.
+
+## License
+
+MIT License

spakky_redis-6.3.1/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "spakky-redis"
+version = "6.3.1"
+description = "Redis cache backend plugin for Spakky Framework"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Spakky", email = "sejong418@icloud.com" }]
+dependencies = [
+    "pydantic-settings>=2.13.1",
+    "redis>=7.1.0",
+    "spakky-cache>=6.3.1",
+]
+
+[project.entry-points."spakky.plugins"]
+spakky-redis = "spakky.plugins.redis.main:initialize"
+
+[dependency-groups]
+dev = [
+    "fakeredis>=2.32.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "spakky.plugins.redis"
+
+[tool.pyrefly]
+python-version = "3.11"
+search_path = ["src", ".", "../../core/spakky/src", "../../core/spakky-cache/src"]
+project_excludes = ["**/__pycache__", "**/*.pyc"]
+
+[tool.ruff]
+builtins = ["_"]
+cache-dir = "~/.cache/ruff"
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "../../core/spakky/src", "../../core/spakky-cache/src"]
+testpaths = "tests"
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+addopts = """
+    --cov
+    --cov-report=term
+    --cov-report=xml
+    --no-cov-on-fail
+    --strict-markers
+    --dist=loadfile
+    -p no:warnings
+    -n auto
+    --spec
+"""
+spec_test_format = "{result} {docstring_summary}"
+
+[tool.coverage.run]
+include = ["src/spakky/plugins/redis/**/*.py"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+precision = 2
+fail_under = 90
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+    "@(typing\\.)?overload",
+    "\\.\\.\\.",
+    "pass",
+]
+
+[tool.uv.sources]
+spakky = { workspace = true }
+spakky-cache = { workspace = true }

spakky_redis-6.3.1/src/spakky/plugins/redis/__init__.py

@@ -0,0 +1,23 @@
+"""Redis cache backend plugin for Spakky Framework."""
+
+from spakky.core.application.plugin import Plugin
+
+from spakky.plugins.redis.cache import RedisCache
+from spakky.plugins.redis.common.config import RedisCacheConfig
+from spakky.plugins.redis.error import (
+    AbstractSpakkyRedisError,
+    RedisCacheOperationError,
+    RedisCacheSerializationError,
+)
+
+PLUGIN_NAME = Plugin(name="spakky-redis")
+"""Plugin identifier for the Spakky Redis package."""
+
+__all__ = [
+    "AbstractSpakkyRedisError",
+    "PLUGIN_NAME",
+    "RedisCache",
+    "RedisCacheConfig",
+    "RedisCacheOperationError",
+    "RedisCacheSerializationError",
+]

spakky_redis-6.3.1/src/spakky/plugins/redis/cache.py

@@ -0,0 +1,367 @@
+"""Redis implementation of the spakky-cache contract."""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Iterator
+from datetime import timedelta
+import pickle
+from typing import Generic, TypeVar
+
+from redis import Redis
+from redis.asyncio import Redis as AsyncRedis
+from redis.exceptions import RedisError
+from typing_extensions import override
+
+from spakky.cache import ICache, CacheHit, CacheMiss, CacheResult, CacheTTL
+from spakky.cache.error import InvalidCacheTTLError
+from spakky.core.pod.annotations.pod import Pod
+from spakky.plugins.redis.common.config import RedisCacheConfig
+from spakky.plugins.redis.error import (
+    RedisCacheOperationError,
+    RedisCacheSerializationError,
+)
+
+T = TypeVar("T")
+RedisKey = str | bytes
+
+
+class ISyncRedisClient(ABC):
+    """Explicit sync Redis boundary used by RedisCache."""
+
+    @abstractmethod
+    def ping(self) -> None: ...
+
+    @abstractmethod
+    def get(self, name: str) -> bytes | None: ...
+
+    @abstractmethod
+    def set(self, name: str, value: bytes, *, px: int | None = None) -> None: ...
+
+    @abstractmethod
+    def delete(self, *names: RedisKey) -> int: ...
+
+    @abstractmethod
+    def scan_iter(self, match: str) -> Iterator[RedisKey]: ...
+
+
+class IAsyncRedisClient(ABC):
+    """Explicit async Redis boundary used by RedisCache."""
+
+    @abstractmethod
+    async def get(self, name: str) -> bytes | None: ...
+
+    @abstractmethod
+    async def set(self, name: str, value: bytes, *, px: int | None = None) -> None: ...
+
+    @abstractmethod
+    async def delete(self, *names: RedisKey) -> int: ...
+
+    @abstractmethod
+    def scan_iter(self, match: str) -> AsyncIterator[RedisKey]: ...
+
+
+class IRawSyncRedisClient(ABC):
+    """Explicit raw sync Redis boundary before response narrowing."""
+
+    @abstractmethod
+    def ping(self) -> object: ...
+
+    @abstractmethod
+    def get(self, name: str) -> object: ...
+
+    @abstractmethod
+    def set(self, name: str, value: bytes, *, px: int | None = None) -> object: ...
+
+    @abstractmethod
+    def delete(self, *names: RedisKey) -> object: ...
+
+    @abstractmethod
+    def scan_iter(self, match: str) -> Iterator[RedisKey]: ...
+
+
+class IRawAsyncRedisClient(ABC):
+    """Explicit raw async Redis boundary before response narrowing."""
+
+    @abstractmethod
+    async def get(self, name: str) -> object: ...
+
+    @abstractmethod
+    async def set(
+        self, name: str, value: bytes, *, px: int | None = None
+    ) -> object: ...
+
+    @abstractmethod
+    async def delete(self, *names: RedisKey) -> object: ...
+
+    @abstractmethod
+    def scan_iter(self, match: str) -> AsyncIterator[RedisKey]: ...
+
+
+class RedisRawSyncClient(IRawSyncRedisClient):
+    """Raw sync Redis client wrapper for redis-py."""
+
+    def __init__(self, raw: Redis) -> None:
+        self._raw = raw
+
+    @override
+    def ping(self) -> object:
+        return self._raw.ping()
+
+    @override
+    def get(self, name: str) -> object:
+        return self._raw.get(name)
+
+    @override
+    def set(self, name: str, value: bytes, *, px: int | None = None) -> object:
+        return self._raw.set(name, value, px=px)
+
+    @override
+    def delete(self, *names: RedisKey) -> object:
+        return self._raw.delete(*names)
+
+    @override
+    def scan_iter(self, match: str) -> Iterator[RedisKey]:
+        return self._raw.scan_iter(match=match)
+
+
+class RedisRawAsyncClient(IRawAsyncRedisClient):
+    """Raw async Redis client wrapper for redis-py."""
+
+    def __init__(self, raw: AsyncRedis) -> None:
+        self._raw = raw
+
+    @override
+    async def get(self, name: str) -> object:
+        return await self._raw.get(name)
+
+    @override
+    async def set(self, name: str, value: bytes, *, px: int | None = None) -> object:
+        return await self._raw.set(name, value, px=px)
+
+    @override
+    async def delete(self, *names: RedisKey) -> object:
+        return await self._raw.delete(*names)
+
+    @override
+    def scan_iter(self, match: str) -> AsyncIterator[RedisKey]:
+        return self._raw.scan_iter(match=match)
+
+
+class SyncRedisAdapter(ISyncRedisClient):
+    """Typed boundary over the redis-py sync client."""
+
+    def __init__(self, raw: IRawSyncRedisClient) -> None:
+        self._raw = raw
+
+    @override
+    def ping(self) -> None:
+        try:
+            self._raw.ping()
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+
+    @override
+    def get(self, name: str) -> bytes | None:
+        try:
+            payload = self._raw.get(name)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+        if payload is None:
+            return None
+        if isinstance(payload, bytes):
+            return payload
+        raise RedisCacheOperationError
+
+    @override
+    def set(self, name: str, value: bytes, *, px: int | None = None) -> None:
+        try:
+            self._raw.set(name, value, px=px)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+
+    @override
+    def delete(self, *names: RedisKey) -> int:
+        try:
+            deleted = self._raw.delete(*names)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+        if isinstance(deleted, int):
+            return deleted
+        raise RedisCacheOperationError
+
+    @override
+    def scan_iter(self, match: str) -> Iterator[RedisKey]:
+        try:
+            return self._raw.scan_iter(match=match)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+
+
+class AsyncRedisAdapter(IAsyncRedisClient):
+    """Typed boundary over the redis-py async client."""
+
+    def __init__(self, raw: IRawAsyncRedisClient) -> None:
+        self._raw = raw
+
+    @override
+    async def get(self, name: str) -> bytes | None:
+        try:
+            payload = await self._raw.get(name)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+        if payload is None:
+            return None
+        if isinstance(payload, bytes):
+            return payload
+        raise RedisCacheOperationError
+
+    @override
+    async def set(self, name: str, value: bytes, *, px: int | None = None) -> None:
+        try:
+            await self._raw.set(name, value, px=px)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+
+    @override
+    async def delete(self, *names: RedisKey) -> int:
+        try:
+            deleted = await self._raw.delete(*names)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+        if isinstance(deleted, int):
+            return deleted
+        raise RedisCacheOperationError
+
+    @override
+    def scan_iter(self, match: str) -> AsyncIterator[RedisKey]:
+        try:
+            return self._raw.scan_iter(match=match)
+        except RedisError as e:
+            raise RedisCacheOperationError from e
+
+
+@Pod()
+class RedisCache(ICache[T], Generic[T]):
+    """Redis-backed cache that stores pickled values under a configured prefix."""
+
+    def __init__(
+        self,
+        config: RedisCacheConfig | None = None,
+        *,
+        client: ISyncRedisClient | None = None,
+        async_client: IAsyncRedisClient | None = None,
+    ) -> None:
+        self._config = config or RedisCacheConfig()
+        self._client = client or self._create_client()
+        self._async_client = async_client or self._create_async_client()
+        self._ping()
+
+    @override
+    def get(self, key: str) -> CacheResult[T]:
+        payload = self._client.get(self._redis_key(key))
+        if payload is None:
+            return CacheMiss()
+        return CacheHit(value=self._deserialize(payload))
+
+    @override
+    def set(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
+        payload = self._serialize(value)
+        ttl_ms = self._ttl_ms(ttl)
+        self._client.set(self._redis_key(key), payload, px=ttl_ms)
+
+    @override
+    def delete(self, key: str) -> bool:
+        return self._client.delete(self._redis_key(key)) > 0
+
+    @override
+    def clear(self) -> None:
+        keys = list(self._client.scan_iter(match=f"{self._config.key_prefix}*"))
+        if keys:
+            self._client.delete(*keys)
+
+    @override
+    async def get_async(self, key: str) -> CacheResult[T]:
+        payload = await self._async_client.get(self._redis_key(key))
+        if payload is None:
+            return CacheMiss()
+        return CacheHit(value=self._deserialize(payload))
+
+    @override
+    async def set_async(self, key: str, value: T, *, ttl: CacheTTL = None) -> None:
+        payload = self._serialize(value)
+        ttl_ms = self._ttl_ms(ttl)
+        await self._async_client.set(self._redis_key(key), payload, px=ttl_ms)
+
+    @override
+    async def delete_async(self, key: str) -> bool:
+        return await self._async_client.delete(self._redis_key(key)) > 0
+
+    @override
+    async def clear_async(self) -> None:
+        keys = [
+            key
+            async for key in self._async_client.scan_iter(
+                match=f"{self._config.key_prefix}*"
+            )
+        ]
+        if keys:
+            await self._async_client.delete(*keys)
+
+    def _create_client(self) -> ISyncRedisClient:
+        return SyncRedisAdapter(
+            RedisRawSyncClient(
+                Redis.from_url(
+                    self._config.connection_url,
+                    username=self._config.username,
+                    password=self._config.password,
+                    socket_timeout=self._config.socket_timeout,
+                )
+            )
+        )
+
+    def _create_async_client(self) -> IAsyncRedisClient:
+        return AsyncRedisAdapter(
+            RedisRawAsyncClient(
+                AsyncRedis.from_url(
+                    self._config.connection_url,
+                    username=self._config.username,
+                    password=self._config.password,
+                    socket_timeout=self._config.socket_timeout,
+                )
+            )
+        )
+
+    def _ping(self) -> None:
+        self._client.ping()
+
+    def _redis_key(self, key: str) -> str:
+        return f"{self._config.key_prefix}{key}"
+
+    def _ttl_ms(self, ttl: CacheTTL) -> int | None:
+        if ttl is None:
+            return None
+        if isinstance(ttl, timedelta):
+            ttl_seconds = ttl.total_seconds()
+        else:
+            ttl_seconds = float(ttl)
+        if ttl_seconds <= 0:
+            raise InvalidCacheTTLError()
+        return max(1, int(ttl_seconds * 1000))
+
+    def _serialize(self, value: T) -> bytes:
+        try:
+            return pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)
+        except (pickle.PickleError, AttributeError, TypeError) as e:
+            raise RedisCacheSerializationError from e
+
+    def _deserialize(self, payload: bytes) -> T:
+        try:
+            value = pickle.loads(payload)
+        except (
+            pickle.PickleError,
+            EOFError,
+            AttributeError,
+            ImportError,
+            IndexError,
+        ) as e:
+            raise RedisCacheSerializationError from e
+        return value

spakky_redis-6.3.1/src/spakky/plugins/redis/common/__init__.py

@@ -0,0 +1 @@
+"""Common Redis plugin configuration."""

spakky_redis-6.3.1/src/spakky/plugins/redis/common/config.py

@@ -0,0 +1,57 @@
+"""Redis cache backend configuration."""
+
+from typing import ClassVar
+
+from pydantic import NonNegativeInt, PositiveInt
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from spakky.core.stereotype.configuration import Configuration
+
+SPAKKY_REDIS_CONFIG_ENV_PREFIX: str = "SPAKKY_REDIS__"
+
+
+@Configuration()
+class RedisCacheConfig(BaseSettings):
+    """Redis cache backend configuration loaded from environment variables."""
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix=SPAKKY_REDIS_CONFIG_ENV_PREFIX,
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+    )
+
+    host: str = "localhost"
+    """Redis server hostname."""
+
+    port: PositiveInt = 6379
+    """Redis server port."""
+
+    db: NonNegativeInt = 0
+    """Redis database index."""
+
+    username: str | None = None
+    """Optional Redis ACL username."""
+
+    password: str | None = None
+    """Optional Redis password."""
+
+    use_ssl: bool = False
+    """Use redis+ssl transport when true."""
+
+    key_prefix: str = "spakky:cache:"
+    """Prefix applied to keys managed by this cache backend."""
+
+    socket_timeout: float = 5.0
+    """Socket timeout in seconds for Redis operations."""
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    @property
+    def scheme(self) -> str:
+        """Return the Redis URL scheme for this configuration."""
+        return "rediss" if self.use_ssl else "redis"
+
+    @property
+    def connection_url(self) -> str:
+        """Return a Redis connection URL without embedding credentials."""
+        return f"{self.scheme}://{self.host}:{self.port}/{self.db}"

spakky_redis-6.3.1/src/spakky/plugins/redis/error.py

@@ -0,0 +1,21 @@
+"""Error classes for the spakky-redis package."""
+
+from abc import ABC
+
+from spakky.cache.error import AbstractSpakkyCacheError
+
+
+class AbstractSpakkyRedisError(AbstractSpakkyCacheError, ABC):
+    """Base class for Redis cache backend errors."""
+
+
+class RedisCacheOperationError(AbstractSpakkyRedisError):
+    """Raised when a Redis operation fails."""
+
+    message = "Redis cache operation failed"
+
+
+class RedisCacheSerializationError(AbstractSpakkyRedisError):
+    """Raised when a cache value cannot be serialized or deserialized."""
+
+    message = "Redis cache serialization failed"

spakky_redis-6.3.1/src/spakky/plugins/redis/main.py

@@ -0,0 +1,12 @@
+"""Plugin initialization for Redis cache integration."""
+
+from spakky.core.application.application import SpakkyApplication
+
+from spakky.plugins.redis.cache import RedisCache
+from spakky.plugins.redis.common.config import RedisCacheConfig
+
+
+def initialize(app: SpakkyApplication) -> None:
+    """Register Redis cache configuration and backend pods."""
+    app.add(RedisCacheConfig)
+    app.add(RedisCache)

spakky_redis-6.3.1/src/spakky/plugins/redis/py.typed

@@ -0,0 +1 @@
+