wappa 0.1.0__py3-none-any.whl

wappa/persistence/redis/redis_cache_factory.py

@@ -0,0 +1,71 @@
+"""
+Redis cache factory implementation for Wappa framework.
+
+Creates Redis-backed cache instances using the existing Redis handler infrastructure
+with ICache adapters for uniform interface.
+"""
+
+from ...domain.interfaces.cache_factory import ICacheFactory
+from ...domain.interfaces.cache_interface import ICache
+from .cache_adapters import (
+    RedisStateCacheAdapter,
+    RedisTableCacheAdapter,
+    RedisUserCacheAdapter,
+)
+
+
+class RedisCacheFactory(ICacheFactory):
+    """
+    Factory for creating Redis-backed cache instances.
+
+    Uses the existing Redis handler infrastructure with proper pool assignments:
+    - State cache: Uses state_handler pool (db1)
+    - User cache: Uses users pool (db0)
+    - Table cache: Uses table pool (db2)
+
+    All instances implement the ICache interface through adapters.
+
+    Context (tenant_id, user_id) is injected at construction time, eliminating
+    manual parameter passing.
+    """
+
+    def __init__(self, tenant_id: str, user_id: str):
+        """Initialize Redis cache factory with context injection."""
+        super().__init__(tenant_id, user_id)
+
+    def create_state_cache(self) -> ICache:
+        """
+        Create Redis state cache instance.
+
+        Uses context (tenant_id, user_id) injected at construction time.
+
+        Returns:
+            ICache adapter wrapping RedisStateHandler configured for state_handler pool
+        """
+        return RedisStateCacheAdapter(
+            tenant_id=self.tenant_id, user_id=self.user_id, redis_alias="state_handler"
+        )
+
+    def create_user_cache(self) -> ICache:
+        """
+        Create Redis user cache instance.
+
+        Uses context (tenant_id, user_id) injected at construction time.
+
+        Returns:
+            ICache adapter wrapping RedisUser configured for users pool
+        """
+        return RedisUserCacheAdapter(
+            tenant_id=self.tenant_id, user_id=self.user_id, redis_alias="users"
+        )
+
+    def create_table_cache(self) -> ICache:
+        """
+        Create Redis table cache instance.
+
+        Uses context (tenant_id) injected at construction time.
+
+        Returns:
+            ICache adapter wrapping RedisTable configured for table pool
+        """
+        return RedisTableCacheAdapter(tenant_id=self.tenant_id, redis_alias="table")

wappa/persistence/redis/redis_client.py

@@ -0,0 +1,231 @@
+# wappa/persistence/redis/redis_client.py
+
+"""
+Redis helper that is **fork-safe** and asyncio-native for Wappa framework caching.
+
+Why so elaborate?
+-----------------
+• Gunicorn / Uvicorn workers often `fork()` after import time.
+  Re-using a parent-process connection in the child silently breaks
+  pub/sub and can leak file descriptors.
+
+• Each worker therefore needs its *own* connection-pool.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import ClassVar, Literal, cast
+
+from redis.asyncio import ConnectionPool, Redis
+
+log = logging.getLogger("RedisClient")
+
+# Predefined Redis pool aliases with their database numbers for Wappa cache
+PoolAlias = Literal["users", "state_handler", "table"]
+
+POOL_DB_MAPPING = {
+    "users": 0,  # User-specific cache operations
+    "state_handler": 1,  # Handler state cache operations
+    "table": 2,  # Table/data cache operations
+}
+
+
+class RedisClient:
+    """
+    Fork-safe, asyncio-native **multi-pool** Redis manager for Wappa cache.
+
+    Supports exactly 3 predefined pools:
+    - "users" (db 0): User-specific cache operations
+    - "state_handler" (db 1): Handler state cache operations
+    - "table" (db 2): Table/data cache operations
+
+    Every worker process keeps its own pools to avoid post-fork descriptor reuse.
+    """
+
+    _pools: ClassVar[dict[PoolAlias, ConnectionPool]] = {}
+    _clients: ClassVar[dict[PoolAlias, Redis]] = {}
+    _pid: ClassVar[int | None] = None
+
+    # ---------- life-cycle --------------------------------------------------
+
+    @classmethod
+    def setup_single_url(cls, base_url: str, *, max_connections: int = 64) -> None:
+        """
+        Set up all 3 Redis pools from a single base URL by appending database numbers.
+
+        Args:
+            base_url: Base Redis URL (e.g., "redis://localhost:6379")
+            max_connections: Max connections per pool
+
+        Example:
+            RedisClient.setup_single_url("redis://localhost:6379")
+            # Creates:
+            # - users: redis://localhost:6379/0
+            # - state_handler: redis://localhost:6379/1
+            # - table: redis://localhost:6379/2
+        """
+        # Ensure base URL doesn't already have a database
+        if base_url.rstrip("/").split("/")[-1].isdigit():
+            log.warning(
+                f"Base URL '{base_url}' appears to contain a database number. Using as-is for base."
+            )
+            base_url = "/".join(base_url.rstrip("/").split("/")[:-1])
+
+        for alias, db_num in POOL_DB_MAPPING.items():
+            url = f"{base_url.rstrip('/')}/{db_num}"
+            cls._setup_pool(cast(PoolAlias, alias), url, max_connections)
+
+    @classmethod
+    def setup_multiple_urls(
+        cls, urls: dict[PoolAlias, str], *, max_connections: int = 64
+    ) -> None:
+        """
+        Set up Redis pools from explicit URLs for each pool.
+
+        Args:
+            urls: Mapping of pool alias to Redis URL
+            max_connections: Max connections per pool
+
+        Example:
+            RedisClient.setup_multiple_urls({
+                "users": "redis://localhost:6379/0",
+                "state_handler": "redis://cache:6379/1",
+                "table": "redis://localhost:6379/2"
+            })
+        """
+        # Validate all required aliases are provided
+        missing = set(POOL_DB_MAPPING.keys()) - set(urls.keys())
+        if missing:
+            raise ValueError(f"Missing required pool aliases: {missing}")
+
+        extra = set(str(k) for k in urls) - set(
+            str(k) for k in POOL_DB_MAPPING
+        )
+        if extra:
+            raise ValueError(
+                f"Unknown pool aliases: {extra}. Only {list(POOL_DB_MAPPING.keys())} are allowed."
+            )
+
+        for alias, url in urls.items():
+            cls._setup_pool(cast(PoolAlias, alias), url, max_connections)
+
+    @classmethod
+    def _setup_pool(cls, alias: PoolAlias, url: str, max_connections: int) -> None:
+        """Internal helper to set up a single pool."""
+        pid = os.getpid()
+        if cls._pid is None:
+            cls._pid = pid
+        elif cls._pid != pid:
+            # process forked – discard inherited pools
+            cls._pools.clear()
+            cls._clients.clear()
+            cls._pid = pid
+
+        if alias in cls._pools:
+            log.debug(f"Redis pool '{alias}' already exists in PID {pid}")
+            return
+
+        log.info(f"Initialising Redis pool '{alias}' in PID {pid} ({url})")
+        pool = ConnectionPool.from_url(
+            url,
+            decode_responses=True,
+            encoding="utf-8",
+            max_connections=max_connections,
+        )
+        client = Redis(connection_pool=pool)
+        cls._pools[alias] = pool
+        cls._clients[alias] = client
+
+    @classmethod
+    async def close(cls, alias: PoolAlias | None = None) -> None:
+        """Close one or all Redis pools for this process."""
+        pid = os.getpid()
+        if cls._pid != pid:
+            log.debug("No Redis pool to close for PID %s", pid)
+            return
+
+        aliases = [alias] if alias else list(cls._pools.keys())
+        for a in aliases:
+            pool = cls._pools.pop(cast(PoolAlias, a), None)
+            if pool:
+                log.info("Closing Redis pool '%s' in PID %s", a, pid)
+                await pool.disconnect()
+                cls._clients.pop(cast(PoolAlias, a), None)
+        if not cls._pools:
+            cls._pid = None
+
+    # ---------- access helpers ---------------------------------------------
+
+    @classmethod
+    async def get(cls, alias: PoolAlias = "users") -> Redis:
+        """Return the Redis client for the given alias."""
+        client = cls._clients.get(alias)
+        if client is None or cls._pid != os.getpid():
+            log.error("RedisClient.get() called before setup() in this process.")
+            raise RuntimeError(f"RedisClient must be set up for alias '{alias}' first.")
+        # quick health check – keep it cheap
+        try:
+            await client.ping()
+            log.debug("Redis PING successful for '%s'.", alias)
+        except Exception as exc:
+            log.error("Redis ping failed for '%s': %s", alias, exc, exc_info=True)
+            raise
+        return client
+
+    @classmethod
+    @asynccontextmanager
+    async def connection(cls, alias: PoolAlias = "users") -> AsyncIterator[Redis]:
+        """
+        Async context manager for Redis connection.
+
+        Usage::
+
+            async with RedisClient.connection("state_handler") as r:
+                await r.set("key", "value")
+        """
+        client = await cls.get(alias)
+        try:
+            yield client
+        finally:
+            # Nothing to close – pool handles connections
+            pass
+
+
+"""
+# RedisClient 🔌
+
+A fork-safe, asyncio-native helper with **3 predefined Redis pools** for Wappa cache:
+
+| Pool         | Database | Purpose                    |
+|--------------|----------|----------------------------|
+| users        | 0        | User-specific cache data   |  
+| state_handler| 1        | Handler state cache data   |
+| table        | 2        | Table/data cache           |
+
+```python
+from wappa.persistence.redis.redis_client import RedisClient
+
+# Option 1: Single URL (creates all 3 pools automatically)
+RedisClient.setup_single_url("redis://localhost:6379")
+
+# Option 2: Explicit URLs per pool
+RedisClient.setup_multiple_urls({
+    "users": "redis://localhost:6379/0",
+    "state_handler": "redis://cache:6379/1", 
+    "table": "redis://localhost:6379/2"
+})
+
+# Usage
+async with RedisClient.connection("state_handler") as r:
+    await r.set("key", "value")
+    
+redis = await RedisClient.get("users")
+await redis.hset("user:123", "name", "Alice")
+```
+
+All pools are fork-safe and isolated per worker process.
+"""

wappa/persistence/redis/redis_handler/__init__.py

@@ -0,0 +1,26 @@
+"""
+Redis Handler Module for Wappa Cache
+
+Repository classes for Redis cache operations with clean separation of concerns.
+Each class handles a specific cache domain: users, state handlers, and tables.
+"""
+
+# Core cache handlers
+from .state_handler import RedisStateHandler
+from .table import RedisTable
+from .user import RedisUser
+
+# Utils
+from .utils import KeyFactory, TenantCache, dumps, loads
+
+__all__ = [
+    # Infrastructure
+    "KeyFactory",
+    "dumps",
+    "loads",
+    "TenantCache",
+    # Cache Repositories
+    "RedisUser",
+    "RedisStateHandler",
+    "RedisTable",
+]

wappa/persistence/redis/redis_handler/state_handler.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ..ops import hget, hincrby_with_expire, hset
+from .utils.serde import dumps
+from .utils.tenant_cache import TenantCache
+
+logger = logging.getLogger("RedisStateHandler")
+
+
+class RedisStateHandler(TenantCache):
+    """
+    Repository for handler state management.
+
+    Extracted from RedisHandler SECTION: Handler State Management:
+    - set_handler_state() -> upsert()
+    - get_handler_state() -> get()
+    - get_handler_state_field() -> get_field()
+    - update_handler_state_field() -> update_field()
+    - increment_handler_state_field() -> increment_field()
+    - append_to_handler_state_list_field() -> append_to_list()
+    - handler_exists() -> exists()
+    - delete_handler_state() -> delete()
+    - create_or_update_handler() -> merge()
+
+    Single Responsibility: Handler state management only
+
+    Example usage:
+        handler = RedisStateHandler(tenant="mimeia", user_id="user123")
+        await handler.upsert("chat_handler", {"step": 1, "context": "greeting"})
+        state = await handler.get("chat_handler")
+    """
+
+    user_id: str = Field(..., min_length=1)
+    redis_alias: str = "handlers"
+
+    def _key(self, handler_name: str) -> str:
+        """Build handler key using KeyFactory"""
+        return self.keys.handler(self.tenant, handler_name, self.user_id)
+
+    # ---- Public API extracted from RedisHandler Handler methods -------------
+    async def get(
+        self, handler_name: str, models: type[BaseModel] | None = None
+    ) -> dict[str, Any] | None:
+        """
+        Get full handler state hash (was get_handler_state)
+
+        Args:
+            handler_name: Name of the handler
+            models: Optional BaseModel class for full object reconstruction
+                   e.g., HandlerState (will automatically handle nested HandlerContext, HandlerMetadata)
+        """
+        key = self._key(handler_name)
+        result = await self._get_hash(key, models=models)
+        if not result:
+            logger.debug(
+                f"Handler state not found for '{handler_name}' (user: '{self.user_id}')"
+            )
+        return result
+
+    async def upsert(
+        self, handler_name: str, state_data: dict[str, Any], ttl: int | None = None
+    ) -> bool:
+        """Set handler state, overwriting existing (Redis HSET upsert behavior)"""
+        key = self._key(handler_name)
+        return await self._hset_with_ttl(key, state_data, ttl)
+
+    async def get_field(self, handler_name: str, field: str) -> Any | None:
+        """Get specific field from handler state (was get_handler_state_field)"""
+        key = self._key(handler_name)
+        return await hget(key, field, alias=self.redis_alias)
+
+    async def update_field(
+        self, handler_name: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Update single field in handler state"""
+        key = self._key(handler_name)
+
+        if ttl:
+            # Use inherited method with TTL renewal
+            return await self._hset_with_ttl(key, {field: value}, ttl)
+        else:
+            # Use simple hset without TTL renewal
+            serialized_value = dumps(value)
+            result = await hset(
+                key, field=field, value=serialized_value, alias=self.redis_alias
+            )
+            return result >= 0
+
+    async def increment_field(
+        self, handler_name: str, field: str, increment: int = 1, ttl: int | None = None
+    ) -> int | None:
+        """Atomically increment integer field (was increment_handler_state_field)"""
+        key = self._key(handler_name)
+
+        new_value, expire_res = await hincrby_with_expire(
+            key=key,
+            field=field,
+            increment=increment,
+            ttl=ttl or self.ttl_default,
+            alias=self.redis_alias,
+        )
+
+        if new_value is not None and expire_res:
+            return new_value
+        else:
+            logger.warning(
+                f"Failed to increment handler field '{field}' for '{handler_name}' (user: '{self.user_id}')"
+            )
+            return None
+
+    async def append_to_list(
+        self, handler_name: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Append value to list field (was append_to_handler_state_list_field)"""
+        key = self._key(handler_name)
+        return await self._append_to_list_field(key, field, value, ttl)
+
+    async def exists(self, handler_name: str) -> bool:
+        """Check if handler state exists (was handler_exists)"""
+        key = self._key(handler_name)
+        return await self.key_exists(key)
+
+    async def delete(self, handler_name: str) -> int:
+        """Delete handler state (was delete_handler_state)"""
+        key = self._key(handler_name)
+        return await self.delete_key(key)
+
+    async def merge(
+        self,
+        handler_name: str,
+        state_data: dict[str, Any],
+        ttl: int | None = None,
+        models: type[BaseModel] | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Merge new data with existing state and save (was create_or_update_handler)
+        Returns the final merged state or None on failure
+
+        Args:
+            handler_name: Name of the handler
+            state_data: New state data to merge
+            ttl: Optional TTL override
+            models: Optional mapping for BaseModel deserialization when reading existing state
+        """
+        logger.debug(f"Upsert handler '{handler_name}' for user '{self.user_id}'")
+
+        # Get existing state with optional BaseModel deserialization
+        existing_state = await self.get(handler_name, models=models) or {}
+
+        # Merge new data with existing
+        new_state = {
+            **existing_state,
+            **state_data,
+            "handler_type": handler_name,
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+
+        # Save merged state
+        success = await self.upsert(handler_name, new_state, ttl)
+
+        if success:
+            logger.debug(
+                f"Successfully upserted handler '{handler_name}' for user '{self.user_id}'"
+            )
+            return new_state
+        else:
+            logger.error(
+                f"Failed to upsert handler '{handler_name}' for user '{self.user_id}'"
+            )
+            return None

wappa/persistence/redis/redis_handler/table.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..ops import hget, hincrby_with_expire
+from .utils.serde import loads
+from .utils.tenant_cache import TenantCache
+
+logger = logging.getLogger("RedisTable")
+
+
+class RedisTable(TenantCache):
+    """
+    Repository for table data management (generic DataFrames/rows).
+
+    Extracted from RedisHandler SECTION: Table Data Management:
+    - set_table_data() -> upsert()
+    - get_table_data() -> get()
+    - get_field() -> get_field()
+    - increment_table_data_field() -> increment_field()
+    - append_to_table_data_list_field() -> append_to_list()
+    - table_data_exists() -> exists()
+    - delete_table_data() -> delete()
+    - create_or_update_table_field() -> update_field()
+    - find_table_by_field() -> find_by_field()
+    - delete_all_tables_by_pkid() -> delete_all_by_pkid()
+
+    Single Responsibility: Table/DataFrame data management only
+    """
+
+    redis_alias: str = "handlers"
+
+    def _key(self, table_name: str, pkid: str) -> str:
+        """Build table key using KeyFactory"""
+        return self.keys.table(self.tenant, table_name, pkid)
+
+    # ---- Public API extracted from RedisHandler Table methods ---------------
+    async def get(
+        self,
+        table_name: str,
+        pkid: str,
+        models: type[BaseModel] | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Get full table row data (was get_table_data)
+
+        Args:
+            table_name: Name of the table
+            pkid: Primary key identifier
+            models: Optional BaseModel class for full object reconstruction
+                   e.g., TableRow (will automatically handle nested RowMetadata, RowConfig)
+        """
+        key = self._key(table_name, pkid)
+        result = await self._get_hash(key, models=models)
+        if not result:
+            logger.debug(f"Table data not found for '{table_name}:{pkid}'")
+        return result
+
+    async def upsert(
+        self, table_name: str, pkid: str, data: dict[str, Any], ttl: int | None = None
+    ) -> bool:
+        """Set table row data (Redis HSET upsert behavior)"""
+        key = self._key(table_name, pkid)
+        return await self._hset_with_ttl(key, data, ttl)
+
+    async def get_field(self, table_name: str, pkid: str, field: str) -> Any | None:
+        """Get a specific field from table row data"""
+        key = self._key(table_name, pkid)
+        raw_value = await hget(key, field, alias=self.redis_alias)
+        return loads(raw_value) if raw_value is not None else None
+
+    async def update_field(
+        self, table_name: str, pkid: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Update single field in table row"""
+        key = self._key(table_name, pkid)
+        return await self._hset_with_ttl(key, {field: value}, ttl)
+
+    async def increment_field(
+        self,
+        table_name: str,
+        pkid: str,
+        field: str,
+        increment: int = 1,
+        ttl: int | None = None,
+    ) -> int | None:
+        """Atomically increment integer field (was increment_table_data_field)"""
+        key = self._key(table_name, pkid)
+
+        new_value, expire_res = await hincrby_with_expire(
+            key=key,
+            field=field,
+            increment=increment,
+            ttl=ttl or self.ttl_default,
+            alias=self.redis_alias,
+        )
+
+        if new_value is not None and expire_res:
+            return new_value
+        else:
+            logger.warning(
+                f"Failed to increment table field '{field}' for '{table_name}:{pkid}'"
+            )
+            return None
+
+    async def append_to_list(
+        self, table_name: str, pkid: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Append value to list field (was append_to_table_data_list_field)"""
+        key = self._key(table_name, pkid)
+        return await self._append_to_list_field(key, field, value, ttl)
+
+    async def exists(self, table_name: str, pkid: str) -> bool:
+        """Check if table row exists (was table_data_exists)"""
+        key = self._key(table_name, pkid)
+        return await self.key_exists(key)
+
+    async def delete(self, table_name: str, pkid: str) -> int:
+        """Delete table row (was delete_table_data)"""
+        key = self._key(table_name, pkid)
+        return await self.delete_key(key)
+
+    async def find_by_field(
+        self,
+        table_name: str,
+        field: str,
+        value: Any,
+        models: type[BaseModel] | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Find first row in table where field matches value (was find_table_by_field)
+
+        Args:
+            table_name: Name of the table
+            field: Field name to search
+            value: Value to match
+            models: Optional BaseModel class for full object reconstruction
+        """
+        pattern = self.keys.table(self.tenant, table_name, "*")
+        return await self._find_by_field(pattern, field, value, models=models)
+
+    async def delete_all_by_pkid(self, pkid: str) -> int:
+        """
+        Delete all table rows across all tables with same pkid (was delete_all_tables_by_pkid)
+
+        This creates a pattern that matches any table with the given pkid:
+        tenant:df:*:pkid:safe_pkid
+        """
+        safe_pkid = pkid.replace(":", "_")
+        pattern = f"{self.tenant}:{self.keys.table_prefix}:*:{self.keys.pk_marker}:{safe_pkid}"
+
+        logger.info(
+            f"Deleting all table data with pkid '{pkid}' (pattern: '{pattern}')"
+        )
+        return await self._delete_by_pattern(pattern)