wappa 0.1.0__py3-none-any.whl

wappa/persistence/json/cache_adapters.py

@@ -0,0 +1,271 @@
+"""
+JSON cache adapters that implement the ICache interface.
+
+These adapters wrap JSON handlers to provide a uniform ICache interface
+while preserving all functionality and maintaining API compatibility with Redis.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..domain.interfaces.cache_interface import ICache
+from .handlers.state_handler import JSONStateHandler
+from .handlers.table_handler import JSONTable
+from .handlers.user_handler import JSONUser
+
+
+class JSONStateCacheAdapter(ICache):
+    """Adapter that makes JSONStateHandler implement ICache interface."""
+
+    def __init__(self, tenant_id: str, user_id: str):
+        self._handler = JSONStateHandler(tenant=tenant_id, user_id=user_id)
+        self._default_handler_name = "cache"
+
+    async def get(
+        self, key: str, models: type[BaseModel] | None = None
+    ) -> dict[str, Any] | None:
+        """Get cached data by key."""
+        return await self._handler.get(key, models=models)
+
+    async def set(self, key: str, data: dict[str, Any] | BaseModel, ttl: int | None = None) -> bool:
+        """Set cached data with optional TTL."""
+        return await self._handler.upsert(key, data, ttl=ttl)
+
+    async def delete(self, key: str) -> bool:
+        """Delete cached data by key."""
+        result = await self._handler.delete(key)
+        return result > 0
+
+    async def exists(self, key: str) -> bool:
+        """Check if key exists in cache."""
+        return await self._handler.exists(key)
+
+    async def get_field(self, key: str, field: str) -> Any | None:
+        """Get a specific field from cached hash data."""
+        return await self._handler.get_field(key, field)
+
+    async def set_field(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Set a specific field in cached hash data."""
+        return await self._handler.update_field(key, field, value, ttl=ttl)
+
+    async def increment_field(
+        self, key: str, field: str, increment: int = 1, ttl: int | None = None
+    ) -> int | None:
+        """Atomically increment an integer field."""
+        return await self._handler.increment_field(key, field, increment, ttl=ttl)
+
+    async def append_to_list(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Append value to a list field."""
+        return await self._handler.append_to_list(key, field, value, ttl=ttl)
+
+    async def get_ttl(self, key: str) -> int:
+        """Get remaining time to live for a key."""
+        return await self._handler.get_ttl(key)
+
+    async def set_ttl(self, key: str, ttl: int) -> bool:
+        """Set time to live for a key."""
+        return await self._handler.renew_ttl(key, ttl=ttl)
+
+
+class JSONUserCacheAdapter(ICache):
+    """Adapter that makes JSONUser implement ICache interface."""
+
+    def __init__(self, tenant_id: str, user_id: str):
+        self._handler = JSONUser(tenant=tenant_id, user_id=user_id)
+
+    async def get(
+        self, key: str, models: type[BaseModel] | None = None
+    ) -> dict[str, Any] | None:
+        """Get cached data by key. For user cache, key is ignored as it uses user_id."""
+        return await self._handler.get(models=models)
+
+    async def set(self, key: str, data: dict[str, Any] | BaseModel, ttl: int | None = None) -> bool:
+        """Set cached data with optional TTL."""
+        return await self._handler.upsert(data, ttl=ttl)
+
+    async def delete(self, key: str) -> bool:
+        """Delete cached data by key."""
+        result = await self._handler.delete()
+        return result > 0
+
+    async def exists(self, key: str) -> bool:
+        """Check if key exists in cache."""
+        return await self._handler.exists()
+
+    async def get_field(self, key: str, field: str) -> Any | None:
+        """Get a specific field from cached hash data."""
+        return await self._handler.get_field(field)
+
+    async def set_field(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Set a specific field in cached hash data."""
+        return await self._handler.update_field(field, value, ttl=ttl)
+
+    async def increment_field(
+        self, key: str, field: str, increment: int = 1, ttl: int | None = None
+    ) -> int | None:
+        """Atomically increment an integer field."""
+        return await self._handler.increment_field(field, increment, ttl=ttl)
+
+    async def append_to_list(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Append value to a list field."""
+        return await self._handler.append_to_list(field, value, ttl=ttl)
+
+    async def get_ttl(self, key: str) -> int:
+        """Get remaining time to live for a key."""
+        return await self._handler.get_ttl(key)
+
+    async def set_ttl(self, key: str, ttl: int) -> bool:
+        """Set time to live for a key."""
+        return await self._handler.renew_ttl(key, ttl=ttl)
+
+
+class JSONTableCacheAdapter(ICache):
+    """
+    Adapter that makes JSONTable implement ICache interface.
+    
+    Table Key Format Guide:
+    Use create_table_key(table_name, pkid) to generate proper keys.
+    
+    Examples:
+        # Good - using helper method
+        key = cache.create_table_key("user_profiles", "12345")
+        await cache.set(key, user_data)
+        
+        # Also supported - manual format
+        key = "user_profiles:12345"
+        await cache.set(key, user_data)
+    """
+
+    def __init__(self, tenant_id: str):
+        self._handler = JSONTable(tenant=tenant_id)
+    
+    def create_table_key(self, table_name: str, pkid: str) -> str:
+        """
+        Create a properly formatted table cache key.
+        
+        Args:
+            table_name: Name of the table (e.g., "user_profiles", "message_logs")
+            pkid: Primary key ID (e.g., user_id, message_id)
+            
+        Returns:
+            Formatted key string for use with cache methods
+            
+        Example:
+            key = cache.create_table_key("user_profiles", "12345")
+            # Returns: "user_profiles:12345"
+        """
+        if not table_name or not pkid:
+            raise ValueError("Both table_name and pkid must be provided and non-empty")
+        
+        # Sanitize inputs to avoid conflicts
+        safe_table_name = str(table_name).replace(":", "_")
+        safe_pkid = str(pkid).replace(":", "_")
+        
+        return f"{safe_table_name}:{safe_pkid}"
+
+    async def get(
+        self, key: str, models: type[BaseModel] | None = None
+    ) -> dict[str, Any] | None:
+        """Get cached data by key. Key should be in format 'table_name:pkid'."""
+        table_name, pkid = self._parse_key(key)
+        return await self._handler.get(table_name, pkid, models=models)
+
+    async def set(self, key: str, data: dict[str, Any] | BaseModel, ttl: int | None = None) -> bool:
+        """Set cached data with optional TTL."""
+        table_name, pkid = self._parse_key(key)
+        return await self._handler.upsert(table_name, pkid, data, ttl=ttl)
+
+    async def delete(self, key: str) -> bool:
+        """Delete cached data by key."""
+        table_name, pkid = self._parse_key(key)
+        result = await self._handler.delete(table_name, pkid)
+        return result > 0
+
+    async def exists(self, key: str) -> bool:
+        """Check if key exists in cache."""
+        table_name, pkid = self._parse_key(key)
+        return await self._handler.exists(table_name, pkid)
+
+    async def get_field(self, key: str, field: str) -> Any | None:
+        """Get a specific field from cached hash data."""
+        table_name, pkid = self._parse_key(key)
+        return await self._handler.get_field(table_name, pkid, field)
+
+    async def set_field(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Set a specific field in cached hash data."""
+        table_name, pkid = self._parse_key(key)
+        return await self._handler.update_field(table_name, pkid, field, value, ttl=ttl)
+
+    async def increment_field(
+        self, key: str, field: str, increment: int = 1, ttl: int | None = None
+    ) -> int | None:
+        """Atomically increment an integer field."""
+        table_name, pkid = self._parse_key(key)
+        return await self._handler.increment_field(
+            table_name, pkid, field, increment, ttl=ttl
+        )
+
+    async def append_to_list(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """Append value to a list field."""
+        table_name, pkid = self._parse_key(key)
+        return await self._handler.append_to_list(
+            table_name, pkid, field, value, ttl=ttl
+        )
+
+    async def get_ttl(self, key: str) -> int:
+        """Get remaining time to live for a key."""
+        return await self._handler.get_ttl(key)
+
+    async def set_ttl(self, key: str, ttl: int) -> bool:
+        """Set time to live for a key."""
+        return await self._handler.renew_ttl(key, ttl=ttl)
+
+    def _parse_key(self, key: str) -> tuple[str, str]:
+        """
+        Parse key into table_name and pkid with validation.
+        
+        Args:
+            key: Cache key in format "table_name:pkid"
+            
+        Returns:
+            Tuple of (table_name, pkid)
+            
+        Raises:
+            ValueError: If key format is invalid
+        """
+        if not key:
+            raise ValueError("Key cannot be empty")
+            
+        if ":" not in key:
+            raise ValueError(
+                f"Invalid table cache key format: '{key}'. "
+                f"Expected format: 'table_name:pkid'. "
+                f"Use create_table_key(table_name, pkid) to generate proper keys."
+            )
+        
+        parts = key.split(":", 1)
+        if len(parts) != 2:
+            raise ValueError(f"Invalid table cache key format: '{key}'. Expected exactly one ':' separator.")
+            
+        table_name, pkid = parts
+        
+        if not table_name.strip():
+            raise ValueError(f"Invalid table cache key: '{key}'. Table name cannot be empty.")
+            
+        if not pkid.strip():
+            raise ValueError(f"Invalid table cache key: '{key}'. Primary key ID cannot be empty.")
+            
+        return table_name.strip(), pkid.strip()

wappa/persistence/json/handlers/__init__.py

@@ -0,0 +1 @@
+"""JSON cache handlers package."""

wappa/persistence/json/handlers/state_handler.py

@@ -0,0 +1,250 @@
+"""
+JSON State handler - mirrors Redis state handler functionality.
+
+Provides state cache operations using JSON file storage.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+from ..storage_manager import storage_manager
+from .utils.key_factory import default_key_factory
+
+logger = logging.getLogger("JSONStateHandler")
+
+
+class JSONStateHandler:
+    """
+    JSON-based state cache handler.
+    
+    Mirrors RedisStateHandler functionality using file-based JSON storage.
+    Maintains the same API for seamless cache backend switching.
+    """
+    
+    def __init__(self, tenant: str, user_id: str):
+        """
+        Initialize JSON state handler.
+        
+        Args:
+            tenant: Tenant identifier
+            user_id: User identifier
+        """
+        if not tenant or not user_id:
+            raise ValueError(f"Missing required parameters: tenant={tenant}, user_id={user_id}")
+        
+        self.tenant = tenant
+        self.user_id = user_id
+        self.keys = default_key_factory
+    
+    def _key(self, handler_name: str) -> str:
+        """Build handler key using KeyFactory (same as Redis)."""
+        return self.keys.handler(self.tenant, handler_name, self.user_id)
+    
+    # ---- Public API matching RedisStateHandler ----
+    async def get(
+        self, handler_name: str, models: type[BaseModel] | None = None
+    ) -> dict[str, Any] | None:
+        """
+        Get handler state data.
+        
+        Args:
+            handler_name: Handler name
+            models: Optional BaseModel class for deserialization
+        
+        Returns:
+            Handler state data or None if not found
+        """
+        key = self._key(handler_name)
+        return await storage_manager.get("states", self.tenant, self.user_id, key, models)
+    
+    async def upsert(
+        self,
+        handler_name: str,
+        data: dict[str, Any] | BaseModel,
+        ttl: int | None = None,
+    ) -> bool:
+        """
+        Create or update handler state data.
+        
+        Args:
+            handler_name: Handler name
+            data: State data to store
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        key = self._key(handler_name)
+        return await storage_manager.set("states", self.tenant, self.user_id, key, data, ttl)
+    
+    async def delete(self, handler_name: str) -> int:
+        """
+        Delete handler state data.
+        
+        Args:
+            handler_name: Handler name
+        
+        Returns:
+            1 if deleted, 0 if didn't exist
+        """
+        key = self._key(handler_name)
+        success = await storage_manager.delete("states", self.tenant, self.user_id, key)
+        return 1 if success else 0
+    
+    async def exists(self, handler_name: str) -> bool:
+        """
+        Check if handler state exists.
+        
+        Args:
+            handler_name: Handler name
+        
+        Returns:
+            True if exists, False otherwise
+        """
+        key = self._key(handler_name)
+        return await storage_manager.exists("states", self.tenant, self.user_id, key)
+    
+    async def get_field(self, handler_name: str, field: str) -> Any | None:
+        """
+        Get a specific field from handler state.
+        
+        Args:
+            handler_name: Handler name
+            field: Field name
+        
+        Returns:
+            Field value or None if not found
+        """
+        state_data = await self.get(handler_name)
+        if state_data is None:
+            return None
+        
+        if isinstance(state_data, dict):
+            return state_data.get(field)
+        else:
+            # BaseModel instance
+            return getattr(state_data, field, None)
+    
+    async def update_field(
+        self,
+        handler_name: str,
+        field: str,
+        value: Any,
+        ttl: int | None = None,
+    ) -> bool:
+        """
+        Update a specific field in handler state.
+        
+        Args:
+            handler_name: Handler name
+            field: Field name
+            value: New value
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        state_data = await self.get(handler_name)
+        if state_data is None:
+            state_data = {}
+        
+        if isinstance(state_data, BaseModel):
+            state_data = state_data.model_dump()
+        
+        state_data[field] = value
+        return await self.upsert(handler_name, state_data, ttl)
+    
+    async def increment_field(
+        self,
+        handler_name: str,
+        field: str,
+        increment: int = 1,
+        ttl: int | None = None,
+    ) -> int | None:
+        """
+        Atomically increment an integer field in handler state.
+        
+        Args:
+            handler_name: Handler name
+            field: Field name
+            increment: Amount to increment by
+            ttl: Time to live in seconds
+        
+        Returns:
+            New value after increment or None on error
+        """
+        state_data = await self.get(handler_name)
+        if state_data is None:
+            state_data = {}
+        
+        if isinstance(state_data, BaseModel):
+            state_data = state_data.model_dump()
+        
+        current_value = state_data.get(field, 0)
+        if not isinstance(current_value, (int, float)):
+            logger.warning(f"Cannot increment non-numeric field '{field}': {current_value}")
+            return None
+        
+        new_value = int(current_value) + increment
+        state_data[field] = new_value
+        
+        success = await self.upsert(handler_name, state_data, ttl)
+        return new_value if success else None
+    
+    async def append_to_list(
+        self,
+        handler_name: str,
+        field: str,
+        value: Any,
+        ttl: int | None = None,
+    ) -> bool:
+        """
+        Append value to a list field in handler state.
+        
+        Args:
+            handler_name: Handler name
+            field: Field name containing list
+            value: Value to append
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        state_data = await self.get(handler_name)
+        if state_data is None:
+            state_data = {}
+        
+        if isinstance(state_data, BaseModel):
+            state_data = state_data.model_dump()
+        
+        current_list = state_data.get(field, [])
+        if not isinstance(current_list, list):
+            current_list = []
+        
+        current_list.append(value)
+        state_data[field] = current_list
+        
+        return await self.upsert(handler_name, state_data, ttl)
+    
+    async def get_ttl(self, key: str) -> int:
+        """
+        Get remaining time to live for state cache.
+        
+        Returns:
+            Remaining TTL in seconds, -1 if no expiry, -2 if doesn't exist
+        """
+        return await storage_manager.get_ttl("states", self.tenant, self.user_id)
+    
+    async def renew_ttl(self, key: str, ttl: int) -> bool:
+        """
+        Renew time to live for state cache.
+        
+        Args:
+            ttl: New time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        return await storage_manager.set_ttl("states", self.tenant, self.user_id, ttl)