cledar-sdk 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

{cledar_sdk-1.2.1.dist-info → cledar_sdk-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cledar-sdk
-Version: 1.2.1
+Version: 1.3.0
 Summary: Cledar Python SDK
 Author: Cledar
 License-File: LICENSE

{cledar_sdk-1.2.1.dist-info → cledar_sdk-1.3.0.dist-info}/RECORD

@@ -52,14 +52,17 @@ nonce_service/__init__.py,sha256=Rh6JWML_ncfb_t_mVl7PIKOXpELRdfunMsFWAtbt5EE,68
 nonce_service/nonce_service.py,sha256=6RhA2eEztH_pNdjkBI5eqmRh14I96NjgVYy2v_z7vdM,1100
 nonce_service/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nonce_service/tests/test_nonce_service.py,sha256=sWzCBXghZNDOnSo8NQB6tyJJ95g2tZGRPlThFqD2P7g,4047
-redis_service/README.md,sha256=GFzNRpCvPRl-QoOFiDTmj1ncgUoU_HaJV74zVtdwG9M,10176
-redis_service/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+redis_service/README.md,sha256=rsIieAu4TwjoeIbHG30x3t3TyR9P9Ulcy69gdfG_jRg,14632
+redis_service/__init__.py,sha256=SgTAyteZ3pPV8R608-EQ84RmytUfSQaPGl0UJxLnGL0,250
+redis_service/async_example.py,sha256=m8dkSspJK8yti9U_Q3_Sc9XW1aq3RYL4EzBdLx5_u84,2949
 redis_service/example.py,sha256=OApl0JU59viBUZORLxlYBhVMdCc5QvOBdOjscxbm_aQ,1091
 redis_service/exceptions.py,sha256=vvD7SO0xHutSLvUf0ttMo7C6OeaVi8f3bxMservsSVI,737
 redis_service/logger.py,sha256=OBOTx6zk_6wkpB2N_FRV7gXR3xy4dpy4iX2B0oFfZ90,60
 redis_service/model.py,sha256=ykW_KHygNHhfHPvP2RyJj0g_WENXxJEP2HvGy7Yb4uo,174
-redis_service/redis.py,sha256=d8hqkVokVs6eMsteJEsEYZ56nb7WhTQ8Gc_sT4zkSRY,9974
+redis_service/redis.py,sha256=DuWaXMU5RhAW2Rf9T-Hg_1FIrQqkPin1vTXQMJJ6Sno,19817
 redis_service/redis_config_store.py,sha256=EFhyvg_Eklrh2tc5dtFpe6nnjMDkTqYT_egclhf0KaI,8919
+redis_service/tests/test_async_integration_redis.py,sha256=I-rWvOm9Cnpl8AZcrPb58tTbkq_YKh3WR2bwXB-EJRM,5005
+redis_service/tests/test_async_redis_service.py,sha256=DgzBZscXu_FiV6QIZT2AHQ0rk_Zwzu2HmsifeDhArRU,12501
 redis_service/tests/test_integration_redis.py,sha256=O3z5EgkeB6Sd9C1S3rRMW916bybDCAHb-DgTFZGLTqI,3345
 redis_service/tests/test_redis_service.py,sha256=n3FIYBk9SGzpDkRWnPj-Mi3NKYtDEpbwgjpjb_JwjF4,10252
 storage_service/README.md,sha256=Rkew1joVijHVEfyXS9C7dDw55rQ4HYRbHkRYlZiREak,15655
@@ -74,7 +77,7 @@ storage_service/tests/test_integration_filesystem.py,sha256=-H3Skc_geYIjXW1si-8u
 storage_service/tests/test_integration_s3.py,sha256=Ivg_52LXibqVGMS-53z4zda_Yh4u6FO8WplUUu5WWBc,13614
 storage_service/tests/test_local.py,sha256=3CgtxQ_lBBaPR4t9Ip0i7T98scrTOCdkmHYMVansNCc,11256
 storage_service/tests/test_s3.py,sha256=zAppsvVCeLx_NN1tQfqHo57mONEjeFDmiwyecrS3ZgQ,16355
-cledar_sdk-1.2.1.dist-info/METADATA,sha256=9087LMoW_Hd1TC5jwPFbg_w8a43r1ug9ssJJ_02gEzA,6752
-cledar_sdk-1.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cledar_sdk-1.2.1.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
-cledar_sdk-1.2.1.dist-info/RECORD,,
+cledar_sdk-1.3.0.dist-info/METADATA,sha256=x9Pa7dwAJdLAW5A1eY8qQD-DTvMkUp5nrkWpCXvD3nA,6752
+cledar_sdk-1.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cledar_sdk-1.3.0.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
+cledar_sdk-1.3.0.dist-info/RECORD,,

redis_service/README.md

@@ -7,6 +7,7 @@ The `redis_service` package provides a typed, high-level interface over Redis fo
 ### Key Features
 
 - **Typed API with Pydantic**: Validate JSON payloads into Pydantic models on read
+- **Async/Sync Support**: Both `AsyncRedisService` (async/await) and `RedisService` (synchronous) available
 - **Safe Serialization**: Custom JSON encoder for `Enum` (to lowercase names) and `datetime` (ISO 8601)
 - **Ergonomic Helpers**: `get`, `get_raw`, `set`, `list_keys`, `mget`, `delete`
 - **Bulk Reads**: `mget` returns a list with typed results, `None`, or `FailedValue` for per-key errors
@@ -21,6 +22,7 @@ The `redis_service` package provides a typed, high-level interface over Redis fo
 - Reading and writing typed configuration objects
 - Bulk retrieval of many keys while tolerating per-key failures
 - Observing and reacting to configuration changes in near real-time
+- Asynchronous I/O for high-performance applications (FastAPI, aiohttp, etc.)
 
 ## Installation
 
@@ -34,7 +36,9 @@ uv sync --all-groups
 pip install -e .
 ```
 
-## Usage Example
+## Usage Examples
+
+### Synchronous Usage
 
 ```python
 from pydantic import BaseModel
@@ -78,6 +82,122 @@ bulk = service.mget(keys, UserModel)
 service.delete("greeting")
 ```
 
+### Asynchronous Usage
+
+```python
+import asyncio
+from pydantic import BaseModel
+from redis_service.redis import AsyncRedisService, RedisServiceConfig
+
+
+class UserModel(BaseModel):
+    user_id: int
+    name: str
+
+
+async def main():
+    # Configure and create async service
+    config = RedisServiceConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+    )
+    service = AsyncRedisService(config)
+    await service.connect()
+
+    try:
+        # Health check
+        assert await service.is_alive() is True
+
+        # Write a typed value (automatically serialized to JSON)
+        user = UserModel(user_id=1, name="Alice")
+        await service.set("user:1", user)
+
+        # Read and validate back into the model
+        loaded = await service.get("user:1", UserModel)
+        print(loaded)  # UserModel(user_id=1, name='Alice')
+
+        # Raw access (no validation/decoding beyond Redis decode_responses)
+        await service.set("greeting", "hello")
+        print(await service.get_raw("greeting"))  # "hello"
+
+        # List keys by pattern and bulk-fetch
+        keys = await service.list_keys("user:*")
+        bulk = await service.mget(keys, UserModel)
+        # bulk is a list of UserModel | None | FailedValue
+
+        # Delete
+        await service.delete("greeting")
+
+    finally:
+        # Always close the connection
+        await service.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### FastAPI Integration Example
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from pydantic import BaseModel
+from redis_service.redis import AsyncRedisService, RedisServiceConfig
+
+
+class UserModel(BaseModel):
+    user_id: int
+    name: str
+
+
+# Global service instance
+redis_service: AsyncRedisService | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: initialize Redis service
+    global redis_service
+    config = RedisServiceConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+    )
+    redis_service = AsyncRedisService(config)
+    await redis_service.connect()
+
+    yield
+
+    # Shutdown: close Redis connection
+    if redis_service:
+        await redis_service.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+def get_redis() -> AsyncRedisService:
+    if redis_service is None:
+        raise RuntimeError("Redis service not initialized")
+    return redis_service
+
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: int, redis: AsyncRedisService = Depends(get_redis)):
+    user = await redis.get(f"user:{user_id}", UserModel)
+    if user is None:
+        return {"error": "User not found"}
+    return user
+
+
+@app.post("/users")
+async def create_user(user: UserModel, redis: AsyncRedisService = Depends(get_redis)):
+    await redis.set(f"user:{user.user_id}", user)
+    return {"status": "created", "user": user}
+```
+
 ## Development
 
 ### Project Structure
@@ -85,16 +205,18 @@ service.delete("greeting")
 ```
 redis_service/
 ├── __init__.py
-├── exceptions.py            # Custom exceptions
-├── logger.py                # Module logger
-├── model.py                 # Base config type for RedisConfigStore
-├── redis.py                 # Main RedisService implementation
-├── redis_config_store.py    # Config store with caching and watchers
-├── example.py               # Small example of using RedisConfigStore
+├── exceptions.py                      # Custom exceptions
+├── logger.py                          # Module logger
+├── model.py                           # Base config type for RedisConfigStore
+├── redis.py                           # RedisService and AsyncRedisService
+├── redis_config_store.py              # Config store with caching and watchers
+├── example.py                         # Small example of using RedisConfigStore
 ├── tests/
-│   ├── test_redis_service.py       # Unit tests (mocked Redis)
-│   └── test_integration_redis.py   # Integration tests with testcontainers
-└── README.md                # This file
+│   ├── test_redis_service.py          # Sync unit tests (mocked Redis)
+│   ├── test_async_redis_service.py    # Async unit tests (mocked Redis)
+│   ├── test_integration_redis.py      # Sync integration tests with testcontainers
+│   └── test_async_integration_redis.py # Async integration tests with testcontainers
+└── README.md                          # This file
 ```
 
 ## Running Linters
@@ -158,9 +280,9 @@ PYTHONPATH=$PWD uv run pytest redis_service/tests/test_redis_service.py::test_se
 
 ### Unit Test Details
 
-- **Test Framework**: pytest
-- **Mocking**: unittest.mock
-- **Test Count**: 30 unit tests
+- **Test Framework**: pytest, pytest-asyncio
+- **Mocking**: unittest.mock (sync), AsyncMock (async)
+- **Test Count**: 60 unit tests (30 sync + 30 async)
 
 ## Running Integration Tests
 
@@ -183,10 +305,10 @@ PYTHONPATH=$PWD uv run pytest redis_service/tests/test_integration_redis.py -v
 
 ### Integration Test Details
 
-- **Test Framework**: pytest + testcontainers
+- **Test Framework**: pytest, pytest-asyncio + testcontainers
 - **Container**: Redis
 - **Image**: `redis:7.2-alpine`
-- **Test Count**: 8 integration tests
+- **Test Count**: 17 integration tests (8 sync + 9 async)
 
 ### Run All Tests (Unit + Integration)
 
@@ -284,7 +406,7 @@ class RedisServiceConfig:
     redis_password: str | None = None
 ```
 
-### RedisService
+### RedisService (Synchronous)
 
 High-level service over `redis.Redis` with JSON handling and typed reads.
 
@@ -298,6 +420,24 @@ High-level service over `redis.Redis` with JSON handling and typed reads.
 - `mget(keys: list[str], model: type[T]) -> list[T | None | FailedValue]` — Bulk read with per-key error details
 - `delete(key: str) -> bool` — Delete a key; returns True if a key was removed
 
+### AsyncRedisService (Asynchronous)
+
+High-level async service over `redis.asyncio.Redis` with JSON handling and typed reads.
+
+#### Methods
+
+All methods are async (use `await`):
+
+- `connect() -> None` — Establish connection to Redis (must be called before using other methods)
+- `close() -> None` — Close the Redis connection
+- `is_alive() -> bool` — Ping Redis to check connectivity
+- `set(key: str, value: Any) -> bool` — Serialize and store a value; supports dict/list, Pydantic models, primitives
+- `get(key: str, model: type[T]) -> T | None` — Read and validate JSON into the given Pydantic model
+- `get_raw(key: str) -> Any | None` — Read raw value (usually string) without validation
+- `list_keys(pattern: str) -> list[str]` — List keys matching a glob-like pattern
+- `mget(keys: list[str], model: type[T]) -> list[T | None | FailedValue]` — Bulk read with per-key error details
+- `delete(key: str) -> bool` — Delete a key; returns True if a key was removed
+
 #### Exceptions
 
 - `RedisConnectionError` — Connection/transport errors

redis_service/__init__.py

@@ -0,0 +1,15 @@
+from .redis import (
+    AsyncRedisService,
+    CustomEncoder,
+    FailedValue,
+    RedisService,
+    RedisServiceConfig,
+)
+
+__all__ = [
+    "AsyncRedisService",
+    "CustomEncoder",
+    "FailedValue",
+    "RedisService",
+    "RedisServiceConfig",
+]

redis_service/async_example.py

@@ -0,0 +1,111 @@
+"""
+Example usage of AsyncRedisService with async/await.
+
+This example demonstrates:
+- Connecting to Redis asynchronously
+- Setting and getting typed values
+- Concurrent operations
+- Proper connection lifecycle management
+"""
+
+import asyncio
+
+from pydantic import BaseModel
+
+from redis_service.redis import AsyncRedisService, RedisServiceConfig
+
+
+class UserModel(BaseModel):
+    user_id: int
+    name: str
+    email: str
+
+
+async def basic_usage_example() -> None:
+    """Basic async Redis operations."""
+    print("=== Basic Async Usage ===")
+
+    # Configure service
+    config = RedisServiceConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+    )
+
+    # Create and connect
+    service = AsyncRedisService(config)
+    await service.connect()
+
+    try:
+        # Health check
+        is_alive = await service.is_alive()
+        print(f"Redis is alive: {is_alive}")
+
+        # Store typed data
+        user = UserModel(user_id=1, name="Alice", email="alice@example.com")
+        await service.set("user:1", user)
+        print(f"Stored user: {user}")
+
+        # Retrieve and validate
+        retrieved = await service.get("user:1", UserModel)
+        print(f"Retrieved user: {retrieved}")
+
+        # Store raw string
+        await service.set("greeting", "Hello, async world!")
+        greeting = await service.get_raw("greeting")
+        print(f"Greeting: {greeting}")
+
+    finally:
+        # Always close connection
+        await service.close()
+        print("Connection closed")
+
+
+async def concurrent_operations_example() -> None:
+    """Demonstrate concurrent async operations."""
+    print("\n=== Concurrent Operations ===")
+
+    config = RedisServiceConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+    )
+
+    service = AsyncRedisService(config)
+    await service.connect()
+
+    try:
+        # Create multiple users concurrently
+        users = [
+            UserModel(user_id=i, name=f"User{i}", email=f"user{i}@example.com")
+            for i in range(1, 11)
+        ]
+
+        # Store all users concurrently
+        set_tasks = [service.set(f"user:{u.user_id}", u) for u in users]
+        results = await asyncio.gather(*set_tasks)
+        print(f"Stored {sum(results)} users concurrently")
+
+        # Retrieve all users concurrently
+        keys = [f"user:{i}" for i in range(1, 11)]
+        retrieved = await service.mget(keys, UserModel)
+        user_count = len([r for r in retrieved if isinstance(r, UserModel)])
+        print(f"Retrieved {user_count} users")
+
+        # Clean up concurrently
+        delete_tasks = [service.delete(key) for key in keys]
+        await asyncio.gather(*delete_tasks)
+        print("Cleaned up all users")
+
+    finally:
+        await service.close()
+
+
+async def main() -> None:
+    """Run all examples."""
+    await basic_usage_example()
+    await concurrent_operations_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

redis_service/redis.py

@@ -6,6 +6,7 @@ from enum import Enum
 from typing import Any, TypeVar, cast
 
 import redis
+import redis.asyncio as aioredis
 from pydantic import BaseModel, ValidationError
 
 from .exceptions import (
@@ -276,3 +277,249 @@ class RedisService:
         except redis.RedisError as exc:
             logger.exception("Error deleting Redis key.", extra={"key": key})
             raise RedisOperationError(f"Failed to delete key '{key}'") from exc
+
+
+class AsyncRedisService:
+    """Asynchronous Redis service with async/await support."""
+
+    def __init__(self, config: RedisServiceConfig):
+        self.config = config
+        self._client: aioredis.Redis
+
+    async def connect(self) -> None:
+        """Establish connection to Redis asynchronously."""
+        try:
+            self._client = aioredis.Redis(
+                host=self.config.redis_host,
+                port=self.config.redis_port,
+                db=self.config.redis_db,
+                password=self.config.redis_password,
+                decode_responses=True,
+            )
+            logger.info(
+                "Async Redis client initialized.",
+                extra={
+                    "host": self.config.redis_host,
+                    "port": self.config.redis_port,
+                    "db": self.config.redis_db,
+                },
+            )
+            await self._client.ping()
+            logger.info(
+                "Async Redis client pinged successfully.",
+                extra={"host": self.config.redis_host},
+            )
+        except aioredis.ConnectionError as exc:
+            logger.exception("Failed to initialize async Redis client.")
+            raise RedisConnectionError("Could not initialize Redis client") from exc
+
+    async def close(self) -> None:
+        """Close the Redis connection."""
+        await self._client.aclose()
+        logger.info("Async Redis client closed.")
+
+    async def is_alive(self) -> bool:
+        """Check if Redis connection is alive."""
+        try:
+            return bool(await self._client.ping())
+        except aioredis.ConnectionError:
+            logger.exception(
+                "Redis connection error during health check. Can't ping Redis host %s",
+                self.config.redis_host,
+            )
+            return False
+
+    def _prepare_for_serialization(self, value: Any) -> Any:
+        """
+        Recursively process data structures, converting BaseModel instances to
+        serializable dicts.
+        """
+        if isinstance(value, BaseModel):
+            return value.model_dump()
+        if isinstance(value, list):
+            return [self._prepare_for_serialization(item) for item in value]
+        if isinstance(value, dict):
+            return {k: self._prepare_for_serialization(v) for k, v in value.items()}
+        return value
+
+    async def set(self, key: str, value: Any) -> bool:
+        """Set a key-value pair in Redis."""
+        if not isinstance(key, str):
+            raise ValueError(f"Key must be a string, got {type(key)}")
+        if value is None:
+            logger.debug("Value is none", extra={"key": key})
+        try:
+            processed_value = self._prepare_for_serialization(value)
+            if isinstance(processed_value, (dict, list)):
+                try:
+                    final_value = json.dumps(processed_value, cls=CustomEncoder)
+
+                except (TypeError, ValueError) as exc:
+                    logger.exception(
+                        "Serialization error before setting Redis key.",
+                        extra={"key": key},
+                    )
+                    raise RedisSerializationError(
+                        "Failed to serialize value for Redis"
+                    ) from exc
+
+            else:
+                final_value = processed_value
+            return bool(await self._client.set(key, final_value))
+
+        except aioredis.ConnectionError as exc:
+            logger.exception("Redis connection error.", extra={"key": key})
+            raise RedisConnectionError(
+                f"Error connecting to Redis host {self.config.redis_host}"
+            ) from exc
+
+        except aioredis.RedisError as exc:
+            logger.exception("Error setting Redis key.", extra={"key": key})
+            raise RedisOperationError(f"Failed to set key '{key}'") from exc
+
+    async def get(self, key: str, model: type[T]) -> T | None:
+        """Get a value from Redis and validate it against a Pydantic model."""
+        if not isinstance(key, str):
+            raise ValueError(f"Key must be a string, got {type(key)}")
+
+        try:
+            value = await self._client.get(key)
+            if value is None:
+                logger.debug("Value is none", extra={"key": key})
+                return None
+            try:
+                return model.model_validate(json.loads(str(value)))
+
+            except json.JSONDecodeError as exc:
+                logger.exception("JSON Decode error.", extra={"key": key})
+                raise RedisDeserializationError(
+                    f"Failed to decode JSON for key '{key}'"
+                ) from exc
+
+            except ValidationError as exc:
+                logger.exception(
+                    "Validation error.", extra={"key": key, "model": model}
+                )
+                raise RedisDeserializationError(
+                    f"Validation failed for key '{key}' and model '{model.__name__}'"
+                ) from exc
+
+        except aioredis.ConnectionError as exc:
+            logger.exception("Redis connection error.", extra={"key": key})
+            raise RedisConnectionError(
+                f"Error connecting to Redis host {self.config.redis_host}"
+            ) from exc
+
+        except aioredis.RedisError as exc:
+            logger.exception("Error getting Redis key.", extra={"key": key})
+            raise RedisOperationError(f"Failed to get key '{key}'") from exc
+
+    async def get_raw(self, key: str) -> Any | None:
+        """Get a raw value from Redis without deserialization."""
+        if not isinstance(key, str):
+            raise ValueError(f"Key must be a string, got {type(key)}")
+
+        try:
+            value = await self._client.get(key)
+            if value is None:
+                logger.debug("Value is none", extra={"key": key})
+            return value
+
+        except aioredis.ConnectionError as exc:
+            logger.exception("Redis connection error.", extra={"key": key})
+            raise RedisConnectionError(
+                f"Error connecting to Redis host {self.config.redis_host}"
+            ) from exc
+
+        except aioredis.RedisError as exc:
+            logger.exception("Error getting Redis key.", extra={"key": key})
+            raise RedisOperationError(f"Failed to get key '{key}'") from exc
+
+    async def list_keys(self, pattern: str) -> list[str]:
+        """List keys matching a pattern."""
+        if not isinstance(pattern, str):
+            raise ValueError(f"Pattern must be a string, got {type(pattern)}")
+
+        try:
+            keys_result = await self._client.keys(pattern)
+            return cast(list[str], keys_result)
+
+        except aioredis.ConnectionError as exc:
+            logger.exception("Redis connection error.", extra={"pattern": pattern})
+            raise RedisConnectionError(
+                f"Error connecting to Redis host {self.config.redis_host}"
+            ) from exc
+
+        except aioredis.RedisError as exc:
+            logger.exception("Error listing Redis keys.", extra={"pattern": pattern})
+            raise RedisOperationError(
+                f"Failed to list keys for pattern '{pattern}'"
+            ) from exc
+
+    async def mget(
+        self, keys: list[str], model: type[T]
+    ) -> list[T | None | FailedValue]:
+        """Get multiple values from Redis."""
+        if not isinstance(keys, list):
+            raise ValueError(f"Keys must be a list, got {type(keys)}")
+
+        if not keys:
+            return []
+
+        try:
+            values = cast(list[Any], await self._client.mget(keys))
+            results: list[T | None | FailedValue] = []
+
+            for value, key in zip(values, keys, strict=False):
+                if value is None:
+                    results.append(None)
+                    continue
+
+                try:
+                    validated_data = model.model_validate(json.loads(str(value)))
+                    results.append(validated_data)
+
+                except json.JSONDecodeError as exc:
+                    logger.exception("JSON Decode error.", extra={"key": key})
+                    results.append(FailedValue(key=key, error=exc))
+                    continue
+
+                except ValidationError as exc:
+                    logger.exception(
+                        "Validation error.",
+                        extra={"key": key, "model": model.__name__},
+                    )
+                    results.append(FailedValue(key=key, error=exc))
+                    continue
+
+            return results
+
+        except aioredis.ConnectionError as exc:
+            logger.exception("Redis connection error.", extra={"keys": keys})
+            raise RedisConnectionError(
+                f"Error connecting to Redis host {self.config.redis_host}"
+            ) from exc
+
+        except aioredis.RedisError as exc:
+            logger.exception("Error getting multiple Redis keys.")
+            raise RedisOperationError("Failed to mget keys") from exc
+
+    async def delete(self, key: str) -> bool:
+        """Delete a key from Redis."""
+        if not isinstance(key, str):
+            raise ValueError(f"Key must be a string, got {type(key)}")
+
+        try:
+            result = await self._client.delete(key)
+            logger.info("Key deleted successfully", extra={"key": key})
+            return bool(result)
+
+        except aioredis.ConnectionError as exc:
+            logger.exception("Redis connection error.", extra={"key": key})
+            raise RedisConnectionError(
+                f"Error connecting to Redis host {self.config.redis_host}"
+            ) from exc
+
+        except aioredis.RedisError as exc:
+            logger.exception("Error deleting Redis key.", extra={"key": key})
+            raise RedisOperationError(f"Failed to delete key '{key}'") from exc

redis_service/tests/test_async_integration_redis.py

@@ -0,0 +1,162 @@
+# mypy: disable-error-code=no-untyped-def
+import json
+from collections.abc import AsyncGenerator
+from datetime import datetime
+from enum import Enum
+
+import pytest
+import pytest_asyncio
+from pydantic import BaseModel
+from testcontainers.redis import RedisContainer
+
+from redis_service.redis import (
+    AsyncRedisService,
+    FailedValue,
+    RedisServiceConfig,
+)
+
+
+class UserModel(BaseModel):
+    user_id: int
+    name: str
+
+
+class Color(Enum):
+    RED = 1
+    BLUE = 2
+
+
+@pytest.fixture(scope="module")
+def redis_container():
+    """Start a Redis container for testing."""
+    with RedisContainer("redis:7.2-alpine") as redis_db:
+        yield redis_db
+
+
+@pytest_asyncio.fixture(scope="function")
+async def async_redis_service(
+    redis_container: RedisContainer,
+) -> AsyncGenerator[AsyncRedisService, None]:
+    host = redis_container.get_container_host_ip()
+    port = int(redis_container.get_exposed_port(6379))
+
+    config = RedisServiceConfig(redis_host=host, redis_port=port, redis_db=0)
+    service = AsyncRedisService(config)
+    await service.connect()
+    yield service
+    await service.close()
+
+
+@pytest.mark.asyncio
+async def test_is_alive(async_redis_service: AsyncRedisService) -> None:
+    assert await async_redis_service.is_alive() is True
+
+
+@pytest.mark.asyncio
+async def test_set_and_get_pydantic_model(
+    async_redis_service: AsyncRedisService,
+) -> None:
+    key = "async:user:1"
+    model = UserModel(user_id=1, name="Alice")
+    assert await async_redis_service.set(key, model) is True
+    got = await async_redis_service.get(key, UserModel)
+    assert isinstance(got, UserModel)
+    assert got == model
+
+
+@pytest.mark.asyncio
+async def test_set_plain_string_and_get_raw(
+    async_redis_service: AsyncRedisService,
+) -> None:
+    key = "async:greeting"
+    assert await async_redis_service.set(key, "hello") is True
+    assert await async_redis_service.get_raw(key) == "hello"
+
+
+@pytest.mark.asyncio
+async def test_set_with_enum_and_datetime_uses_custom_encoder(
+    async_redis_service: AsyncRedisService,
+) -> None:
+    key = "async:meta"
+    now = datetime(2024, 1, 2, 3, 4, 5)
+    payload = {"color": Color.RED, "when": now}
+    assert await async_redis_service.set(key, payload) is True
+
+    raw = await async_redis_service.get_raw(key)
+    data = json.loads(raw)  # type: ignore
+    assert data["color"] == "red"
+    assert data["when"] == now.isoformat()
+
+
+@pytest.mark.asyncio
+async def test_list_keys(async_redis_service: AsyncRedisService) -> None:
+    prefix = "async:listkeys:test:"
+    keys = [f"{prefix}{i}" for i in range(3)]
+    for k in keys:
+        assert await async_redis_service.set(k, {"i": 1}) is True
+
+    listed = await async_redis_service.list_keys(f"{prefix}*")
+    for k in keys:
+        assert k in listed
+
+
+@pytest.mark.asyncio
+async def test_mget_mixed_results(async_redis_service: AsyncRedisService) -> None:
+    ok = UserModel(user_id=2, name="Bob")
+    k1 = "async:mget:ok"
+    k2 = "async:mget:not_json"
+    k3 = "async:mget:bad_validation"
+    k4 = "async:mget:none"
+
+    assert await async_redis_service.set(k1, ok) is True
+    assert await async_redis_service.set(k2, "{not-json}") is True
+    assert await async_redis_service.set(k3, json.dumps({"user_id": 3})) is True
+
+    results = await async_redis_service.mget([k1, k2, k3, k4], UserModel)
+
+    assert isinstance(results[0], UserModel)
+    assert isinstance(results[1], FailedValue)
+    assert isinstance(results[2], FailedValue)
+    assert results[3] is None
+
+
+@pytest.mark.asyncio
+async def test_delete(async_redis_service: AsyncRedisService) -> None:
+    key = "async:delete:test"
+    assert await async_redis_service.set(key, {"x": 1}) is True
+    assert await async_redis_service.delete(key) is True
+    assert await async_redis_service.get_raw(key) is None
+
+
+@pytest.mark.asyncio
+async def test_context_manager_pattern(redis_container: RedisContainer) -> None:
+    """Test that service can be used with proper async context management."""
+    host = redis_container.get_container_host_ip()
+    port = int(redis_container.get_exposed_port(6379))
+
+    config = RedisServiceConfig(redis_host=host, redis_port=port, redis_db=0)
+    service = AsyncRedisService(config)
+
+    try:
+        await service.connect()
+        assert await service.is_alive() is True
+        await service.set("test:key", "test:value")
+        assert await service.get_raw("test:key") == "test:value"
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_concurrent_operations(async_redis_service: AsyncRedisService) -> None:
+    """Test multiple concurrent async operations."""
+    import asyncio
+
+    async def set_and_get(key: str, value: str) -> str | None:
+        await async_redis_service.set(key, value)
+        return await async_redis_service.get_raw(key)
+
+    tasks = [set_and_get(f"async:concurrent:{i}", f"value:{i}") for i in range(10)]
+    results = await asyncio.gather(*tasks)
+
+    for i, result in enumerate(results):
+        assert result == f"value:{i}"

redis_service/tests/test_async_redis_service.py

@@ -0,0 +1,384 @@
+# mypy: disable-error-code=no-untyped-def
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from enum import Enum
+from unittest.mock import AsyncMock, patch
+
+import pytest
+import redis.asyncio as aioredis
+from pydantic import BaseModel
+
+from redis_service.redis import (
+    AsyncRedisService,
+    FailedValue,
+    RedisServiceConfig,
+)
+
+
+class UserModel(BaseModel):
+    user_id: int
+    name: str
+
+
+class Color(Enum):
+    RED = 1
+    BLUE = 2
+
+
+@pytest.fixture(name="config")
+def fixture_config() -> RedisServiceConfig:
+    return RedisServiceConfig(redis_host="localhost", redis_port=6379, redis_db=0)
+
+
+@pytest.fixture(name="async_redis_client")
+def fixture_async_redis_client() -> AsyncMock:
+    client = AsyncMock()
+    client.ping = AsyncMock(return_value=True)
+    client.aclose = AsyncMock()
+    return client
+
+
+@pytest.fixture(name="service")
+def fixture_service(
+    config: RedisServiceConfig, async_redis_client: AsyncMock
+) -> AsyncRedisService:
+    with patch("redis_service.redis.aioredis.Redis", return_value=async_redis_client):
+        service = AsyncRedisService(config)
+        service._client = async_redis_client
+        return service
+
+
+@pytest.mark.asyncio
+async def test_connect_success_initializes_client(config: RedisServiceConfig) -> None:
+    with patch("redis_service.redis.aioredis.Redis") as redis_instance:
+        mock_client = AsyncMock()
+        mock_client.ping = AsyncMock(return_value=True)
+        redis_instance.return_value = mock_client
+
+        service = AsyncRedisService(config)
+        await service.connect()
+
+        redis_instance.assert_called_once_with(
+            host=config.redis_host,
+            port=config.redis_port,
+            db=config.redis_db,
+            password=config.redis_password,
+            decode_responses=True,
+        )
+
+
+@pytest.mark.asyncio
+async def test_connect_failure_raises_connection_error(
+    config: RedisServiceConfig,
+) -> None:
+    with patch("redis_service.redis.aioredis.Redis") as redis_instance:
+        mock_client = AsyncMock()
+        mock_client.ping = AsyncMock(side_effect=aioredis.ConnectionError())
+        redis_instance.return_value = mock_client
+
+        service = AsyncRedisService(config)
+        with pytest.raises(Exception) as exc:
+            await service.connect()
+        assert "Could not initialize Redis client" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_is_alive_true(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.ping.return_value = True
+    assert await service.is_alive() is True
+
+
+@pytest.mark.asyncio
+async def test_is_alive_false_on_exception(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.ping.side_effect = aioredis.ConnectionError()
+    assert await service.is_alive() is False
+
+
+@pytest.mark.asyncio
+async def test_set_with_pydantic_model_serializes_and_sets(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    model = UserModel(user_id=1, name="Alice")
+    async_redis_client.set = AsyncMock(return_value=True)
+
+    result = await service.set("user:1", model)
+    assert result is True
+    value = async_redis_client.set.call_args.args[1]
+
+    as_dict = json.loads(value)
+    assert as_dict == model.model_dump()
+
+
+@pytest.mark.asyncio
+async def test_set_with_dict_enum_datetime_uses_custom_encoder(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    now = datetime(2024, 1, 2, 3, 4, 5)
+    payload = {"color": Color.RED, "when": now}
+    async_redis_client.set = AsyncMock(return_value=True)
+
+    assert await service.set("meta", payload) is True
+    value = async_redis_client.set.call_args.args[1]
+    as_dict = json.loads(value)
+    assert as_dict["color"] == "red"
+    assert as_dict["when"] == now.isoformat()
+
+
+@pytest.mark.asyncio
+async def test_set_serialization_error_raises(service: AsyncRedisService) -> None:
+    bad = {"x": {1}}
+    with pytest.raises(Exception) as exc:
+        await service.set("k", bad)
+    assert "Failed to serialize value" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_set_connection_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.set = AsyncMock(side_effect=aioredis.ConnectionError("conn"))
+    with pytest.raises(Exception) as exc:
+        await service.set("k", {"a": 1})
+    assert "Error connecting to Redis host" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_set_redis_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.set = AsyncMock(side_effect=aioredis.RedisError("oops"))
+    with pytest.raises(Exception) as exc:
+        await service.set("k", {"a": 1})
+    assert "Failed to set key" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_get_returns_none_for_missing(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.get = AsyncMock(return_value=None)
+    assert await service.get("missing", UserModel) is None
+
+
+@pytest.mark.asyncio
+async def test_get_success_deserializes_to_model(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    model = UserModel(user_id=2, name="Bob")
+    async_redis_client.get = AsyncMock(return_value=json.dumps(model.model_dump()))
+    got = await service.get("user:2", UserModel)
+    assert isinstance(got, UserModel)
+    assert got == model
+
+
+@pytest.mark.asyncio
+async def test_get_json_decode_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.get = AsyncMock(return_value="not-json")
+    with pytest.raises(Exception) as exc:
+        await service.get("k", UserModel)
+    assert "Failed to decode JSON" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_get_validation_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.get = AsyncMock(return_value=json.dumps({"user_id": 3}))
+    with pytest.raises(Exception) as exc:
+        await service.get("k", UserModel)
+    assert "Validation failed" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_get_connection_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.get = AsyncMock(side_effect=aioredis.ConnectionError("down"))
+    with pytest.raises(Exception) as exc:
+        await service.get("k", UserModel)
+    assert "Error connecting to Redis host" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_get_redis_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.get = AsyncMock(side_effect=aioredis.RedisError("nope"))
+    with pytest.raises(Exception) as exc:
+        await service.get("k", UserModel)
+    assert "Failed to get key" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_get_raw_returns_value(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.get = AsyncMock(return_value="raw")
+    assert await service.get_raw("k") == "raw"
+
+
+@pytest.mark.asyncio
+async def test_get_raw_errors_map(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.get = AsyncMock(side_effect=aioredis.RedisError("err"))
+    with pytest.raises(Exception) as exc:
+        await service.get_raw("k")
+    assert "Failed to get key" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_list_keys_success(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.keys = AsyncMock(return_value=["a", "b"])
+    assert await service.list_keys("*") == ["a", "b"]
+
+
+@pytest.mark.asyncio
+async def test_list_keys_connection_error(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.keys = AsyncMock(side_effect=aioredis.ConnectionError("err"))
+    with pytest.raises(Exception) as exc:
+        await service.list_keys("*")
+    assert "Error connecting to Redis host" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_list_keys_redis_error(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.keys = AsyncMock(side_effect=aioredis.RedisError("err"))
+    with pytest.raises(Exception) as exc:
+        await service.list_keys("*")
+    assert "Failed to list keys" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_mget_empty_returns_empty(service: AsyncRedisService) -> None:
+    assert await service.mget([], UserModel) == []
+
+
+@pytest.mark.asyncio
+async def test_mget_success_and_failures(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    good = UserModel(user_id=1, name="A").model_dump()
+    bad_json = "{not-json}"
+    bad_validation = json.dumps({"user_id": 2})
+    none_value = None
+    async_redis_client.mget = AsyncMock(
+        return_value=[
+            json.dumps(good),
+            bad_json,
+            bad_validation,
+            none_value,
+        ]
+    )
+    keys = ["k1", "k2", "k3", "k4"]
+    results = await service.mget(keys, UserModel)
+
+    assert isinstance(results[0], UserModel)
+    assert isinstance(results[1], FailedValue)
+    assert results[1].key == "k2"
+    assert isinstance(results[2], FailedValue)
+    assert results[2].key == "k3"
+    assert results[3] is None
+
+
+@pytest.mark.asyncio
+async def test_mget_connection_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.mget = AsyncMock(side_effect=aioredis.ConnectionError("down"))
+    with pytest.raises(Exception) as exc:
+        await service.mget(["a"], UserModel)
+    assert "Error connecting to Redis host" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_mget_redis_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.mget = AsyncMock(side_effect=aioredis.RedisError("err"))
+    with pytest.raises(Exception) as exc:
+        await service.mget(["a"], UserModel)
+    assert "Failed to mget keys" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_delete_success(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.delete = AsyncMock(return_value=1)
+    assert await service.delete("k") is True
+    async_redis_client.delete.assert_called_once_with("k")
+
+
+@pytest.mark.asyncio
+async def test_delete_connection_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.delete = AsyncMock(side_effect=aioredis.ConnectionError("down"))
+    with pytest.raises(Exception) as exc:
+        await service.delete("k")
+    assert "Error connecting to Redis host" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_delete_redis_error_maps(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.delete = AsyncMock(side_effect=aioredis.RedisError("err"))
+    with pytest.raises(Exception) as exc:
+        await service.delete("k")
+    assert "Failed to delete key" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_set_plain_string_value(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    async_redis_client.set = AsyncMock(return_value=True)
+    assert await service.set("greeting", "hello") is True
+    value = (
+        async_redis_client.set.call_args.args[1]
+        if async_redis_client.set.call_args.args
+        else async_redis_client.set.call_args[0][1]
+    )
+    assert value == "hello"
+
+
+@pytest.mark.asyncio
+async def test_type_validation_errors(service: AsyncRedisService) -> None:
+    with pytest.raises(ValueError, match="Key must be a string"):
+        await service.set(123, "x")  # type: ignore[arg-type]
+
+    with pytest.raises(ValueError, match="Key must be a string"):
+        await service.get(123, UserModel)  # type: ignore[arg-type]
+
+    with pytest.raises(ValueError, match="Key must be a string"):
+        await service.get_raw(123)  # type: ignore[arg-type]
+
+    with pytest.raises(ValueError, match="Pattern must be a string"):
+        await service.list_keys(123)  # type: ignore[arg-type]
+
+    with pytest.raises(ValueError, match="Keys must be a list"):
+        await service.mget("not-a-list", UserModel)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_close_connection(
+    service: AsyncRedisService, async_redis_client: AsyncMock
+) -> None:
+    await service.close()
+    async_redis_client.aclose.assert_called_once()