wappa 0.1.0__py3-none-any.whl

wappa/persistence/memory/handlers/utils/memory_store.py

@@ -0,0 +1,317 @@
+"""
+Thread-safe in-memory storage with TTL support.
+
+Provides global singleton memory store with namespace isolation
+and automatic expiration cleanup.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timedelta
+from typing import Any, Dict, Optional, Tuple
+
+logger = logging.getLogger("MemoryStore")
+
+
+class MemoryStore:
+    """
+    Thread-safe in-memory store with TTL support.
+    
+    Storage Structure:
+    {
+        "users": {context_key: {key: (data, expires_at)}},
+        "tables": {context_key: {key: (data, expires_at)}},
+        "states": {context_key: {key: (data, expires_at)}}
+    }
+    
+    Where context_key is typically "{tenant_id}_{user_id}" for isolation.
+    """
+    
+    def __init__(self):
+        self._store: Dict[str, Dict[str, Dict[str, Tuple[Any, Optional[datetime]]]]] = {
+            "users": {},
+            "tables": {},
+            "states": {}
+        }
+        self._locks = {
+            "users": asyncio.Lock(),
+            "tables": asyncio.Lock(),
+            "states": asyncio.Lock()
+        }
+        self._cleanup_task: Optional[asyncio.Task] = None
+        self._cleanup_interval = 300  # 5 minutes
+        
+    def start_cleanup_task(self):
+        """Start background TTL cleanup task."""
+        if self._cleanup_task is None or self._cleanup_task.done():
+            self._cleanup_task = asyncio.create_task(self._cleanup_expired_entries())
+            logger.info("Started memory store TTL cleanup task")
+    
+    def stop_cleanup_task(self):
+        """Stop background TTL cleanup task."""
+        if self._cleanup_task and not self._cleanup_task.done():
+            self._cleanup_task.cancel()
+            logger.info("Stopped memory store TTL cleanup task")
+    
+    async def get(self, namespace: str, context_key: str, key: str) -> Any:
+        """
+        Get value with automatic expiration check.
+        
+        Args:
+            namespace: Cache namespace ("users", "tables", "states")
+            context_key: Context identifier (e.g., "{tenant_id}_{user_id}")
+            key: Cache key
+        
+        Returns:
+            Cached value or None if not found/expired
+        """
+        if namespace not in self._locks:
+            raise ValueError(f"Invalid namespace: {namespace}")
+        
+        async with self._locks[namespace]:
+            store = self._store[namespace]
+            context_store = store.get(context_key, {})
+            
+            if key in context_store:
+                data, expires_at = context_store[key]
+                if expires_at and datetime.now() > expires_at:
+                    # Expired, remove and return None
+                    del context_store[key]
+                    return None
+                return data
+            return None
+    
+    async def set(
+        self, 
+        namespace: str, 
+        context_key: str, 
+        key: str, 
+        data: Any, 
+        ttl: Optional[int] = None
+    ) -> bool:
+        """
+        Set value with optional TTL.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            key: Cache key
+            data: Value to store
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        if namespace not in self._locks:
+            raise ValueError(f"Invalid namespace: {namespace}")
+        
+        expires_at = None
+        if ttl:
+            expires_at = datetime.now() + timedelta(seconds=ttl)
+        
+        try:
+            async with self._locks[namespace]:
+                store = self._store[namespace]
+                if context_key not in store:
+                    store[context_key] = {}
+                store[context_key][key] = (data, expires_at)
+                
+                # Start cleanup task if not running
+                self.start_cleanup_task()
+                return True
+        except Exception as e:
+            logger.error(f"Failed to set key '{key}' in {namespace}: {e}")
+            return False
+    
+    async def delete(self, namespace: str, context_key: str, key: str) -> bool:
+        """
+        Delete key from store.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            key: Cache key
+        
+        Returns:
+            True if deleted or didn't exist, False on error
+        """
+        if namespace not in self._locks:
+            raise ValueError(f"Invalid namespace: {namespace}")
+        
+        try:
+            async with self._locks[namespace]:
+                store = self._store[namespace]
+                context_store = store.get(context_key, {})
+                if key in context_store:
+                    del context_store[key]
+                    # Clean up empty context store
+                    if not context_store:
+                        del store[context_key]
+                return True
+        except Exception as e:
+            logger.error(f"Failed to delete key '{key}' from {namespace}: {e}")
+            return False
+    
+    async def exists(self, namespace: str, context_key: str, key: str) -> bool:
+        """
+        Check if key exists and is not expired.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            key: Cache key
+        
+        Returns:
+            True if exists and not expired, False otherwise
+        """
+        value = await self.get(namespace, context_key, key)
+        return value is not None
+    
+    async def get_ttl(self, namespace: str, context_key: str, key: str) -> int:
+        """
+        Get remaining TTL for key.
+        
+        Returns:
+            Remaining TTL in seconds, -1 if no expiry, -2 if doesn't exist
+        """
+        if namespace not in self._locks:
+            return -2
+        
+        async with self._locks[namespace]:
+            store = self._store[namespace]
+            context_store = store.get(context_key, {})
+            
+            if key not in context_store:
+                return -2  # Doesn't exist
+            
+            data, expires_at = context_store[key]
+            
+            if expires_at is None:
+                return -1  # No expiry
+            
+            now = datetime.now()
+            if now >= expires_at:
+                # Already expired, clean up
+                del context_store[key]
+                return -2
+            
+            return int((expires_at - now).total_seconds())
+    
+    async def set_ttl(self, namespace: str, context_key: str, key: str, ttl: int) -> bool:
+        """
+        Set TTL for existing key.
+        
+        Args:
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False if key doesn't exist or error
+        """
+        if namespace not in self._locks:
+            return False
+        
+        try:
+            async with self._locks[namespace]:
+                store = self._store[namespace]
+                context_store = store.get(context_key, {})
+                
+                if key not in context_store:
+                    return False  # Key doesn't exist
+                
+                data, _ = context_store[key]  # Get existing data, ignore old TTL
+                expires_at = datetime.now() + timedelta(seconds=ttl)
+                context_store[key] = (data, expires_at)
+                return True
+        except Exception as e:
+            logger.error(f"Failed to set TTL for key '{key}' in {namespace}: {e}")
+            return False
+    
+    async def get_all_keys(self, namespace: str, context_key: str) -> Dict[str, Any]:
+        """
+        Get all non-expired keys for a context.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+        
+        Returns:
+            Dictionary of all non-expired key-value pairs
+        """
+        if namespace not in self._locks:
+            return {}
+        
+        async with self._locks[namespace]:
+            store = self._store[namespace]
+            context_store = store.get(context_key, {})
+            
+            result = {}
+            now = datetime.now()
+            expired_keys = []
+            
+            for key, (data, expires_at) in context_store.items():
+                if expires_at and now > expires_at:
+                    expired_keys.append(key)
+                else:
+                    result[key] = data
+            
+            # Clean up expired keys
+            for key in expired_keys:
+                del context_store[key]
+            
+            return result
+    
+    async def _cleanup_expired_entries(self):
+        """Background task to clean up expired entries."""
+        while True:
+            try:
+                await asyncio.sleep(self._cleanup_interval)
+                
+                now = datetime.now()
+                total_cleaned = 0
+                
+                for namespace in ["users", "tables", "states"]:
+                    async with self._locks[namespace]:
+                        store = self._store[namespace]
+                        empty_contexts = []
+                        
+                        for context_key, context_store in store.items():
+                            expired_keys = []
+                            
+                            for key, (_, expires_at) in context_store.items():
+                                if expires_at and now > expires_at:
+                                    expired_keys.append(key)
+                            
+                            # Remove expired keys
+                            for key in expired_keys:
+                                del context_store[key]
+                                total_cleaned += 1
+                            
+                            # Mark empty contexts for cleanup
+                            if not context_store:
+                                empty_contexts.append(context_key)
+                        
+                        # Remove empty contexts
+                        for context_key in empty_contexts:
+                            del store[context_key]
+                
+                if total_cleaned > 0:
+                    logger.debug(f"Cleaned up {total_cleaned} expired entries from memory store")
+                    
+            except asyncio.CancelledError:
+                logger.info("Memory store cleanup task cancelled")
+                break
+            except Exception as e:
+                logger.error(f"Error in memory store cleanup task: {e}")
+                # Continue running despite errors
+
+
+# Global singleton memory store instance
+_global_memory_store: Optional[MemoryStore] = None
+
+
+def get_memory_store() -> MemoryStore:
+    """Get or create the global memory store singleton."""
+    global _global_memory_store
+    if _global_memory_store is None:
+        _global_memory_store = MemoryStore()
+    return _global_memory_store

wappa/persistence/memory/handlers/utils/ttl_manager.py

@@ -0,0 +1,235 @@
+"""
+TTL management utilities for memory cache.
+
+Provides additional TTL management functionality beyond the basic
+memory store implementation.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timedelta
+from typing import Optional
+
+from .memory_store import get_memory_store
+
+logger = logging.getLogger("TTLManager")
+
+
+class TTLManager:
+    """
+    Advanced TTL management for memory cache.
+    
+    Provides utilities for TTL monitoring, batch operations,
+    and advanced expiration handling.
+    """
+    
+    def __init__(self):
+        self.memory_store = get_memory_store()
+    
+    async def get_ttl_info(self, namespace: str, context_key: str, key: str) -> dict:
+        """
+        Get detailed TTL information for a key.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            key: Cache key
+        
+        Returns:
+            Dictionary with TTL details
+        """
+        ttl_seconds = await self.memory_store.get_ttl(namespace, context_key, key)
+        
+        info = {
+            "key": key,
+            "namespace": namespace,
+            "context_key": context_key,
+            "ttl_seconds": ttl_seconds,
+            "status": "unknown"
+        }
+        
+        if ttl_seconds == -2:
+            info["status"] = "not_found"
+            info["message"] = "Key does not exist"
+        elif ttl_seconds == -1:
+            info["status"] = "no_expiry"
+            info["message"] = "Key exists with no expiration"
+        else:
+            info["status"] = "expires"
+            info["expires_at"] = datetime.now() + timedelta(seconds=ttl_seconds)
+            info["message"] = f"Key expires in {ttl_seconds} seconds"
+        
+        return info
+    
+    async def extend_ttl(
+        self, 
+        namespace: str, 
+        context_key: str, 
+        key: str, 
+        additional_seconds: int
+    ) -> bool:
+        """
+        Extend TTL by adding additional seconds to current TTL.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            key: Cache key
+            additional_seconds: Seconds to add to current TTL
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        current_ttl = await self.memory_store.get_ttl(namespace, context_key, key)
+        
+        if current_ttl == -2:
+            # Key doesn't exist
+            return False
+        elif current_ttl == -1:
+            # No current expiry, set new TTL
+            return await self.memory_store.set_ttl(namespace, context_key, key, additional_seconds)
+        else:
+            # Extend current TTL
+            new_ttl = current_ttl + additional_seconds
+            return await self.memory_store.set_ttl(namespace, context_key, key, new_ttl)
+    
+    async def refresh_ttl(
+        self, 
+        namespace: str, 
+        context_key: str, 
+        key: str, 
+        ttl_seconds: int
+    ) -> bool:
+        """
+        Refresh TTL to a new value (reset expiration timer).
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            key: Cache key
+            ttl_seconds: New TTL in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        return await self.memory_store.set_ttl(namespace, context_key, key, ttl_seconds)
+    
+    async def clear_ttl(self, namespace: str, context_key: str, key: str) -> bool:
+        """
+        Remove TTL from key (make it persistent).
+        
+        Note: This is achieved by setting a very long TTL (100 years).
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            key: Cache key
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        # Set TTL to 100 years (effectively no expiry)
+        very_long_ttl = 100 * 365 * 24 * 3600  # 100 years in seconds
+        return await self.memory_store.set_ttl(namespace, context_key, key, very_long_ttl)
+    
+    async def get_expiring_keys(
+        self, 
+        namespace: str, 
+        context_key: str, 
+        within_seconds: int = 300
+    ) -> list[dict]:
+        """
+        Get keys that will expire within specified seconds.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            within_seconds: Time window in seconds (default: 5 minutes)
+        
+        Returns:
+            List of dictionaries with key info for expiring keys
+        """
+        expiring_keys = []
+        
+        # Get all keys for the context
+        all_keys = await self.memory_store.get_all_keys(namespace, context_key)
+        
+        for key in all_keys.keys():
+            ttl_info = await self.get_ttl_info(namespace, context_key, key)
+            if ttl_info["status"] == "expires" and ttl_info["ttl_seconds"] <= within_seconds:
+                expiring_keys.append(ttl_info)
+        
+        return expiring_keys
+    
+    async def batch_refresh_ttl(
+        self, 
+        namespace: str, 
+        context_key: str, 
+        keys: list[str], 
+        ttl_seconds: int
+    ) -> dict[str, bool]:
+        """
+        Refresh TTL for multiple keys in batch.
+        
+        Args:
+            namespace: Cache namespace
+            context_key: Context identifier
+            keys: List of cache keys
+            ttl_seconds: New TTL in seconds
+        
+        Returns:
+            Dictionary mapping key -> success status
+        """
+        results = {}
+        for key in keys:
+            results[key] = await self.refresh_ttl(namespace, context_key, key, ttl_seconds)
+        return results
+    
+    async def get_namespace_stats(self, namespace: str) -> dict:
+        """
+        Get statistics for a namespace.
+        
+        Args:
+            namespace: Cache namespace
+        
+        Returns:
+            Dictionary with namespace statistics
+        """
+        stats = {
+            "namespace": namespace,
+            "total_contexts": 0,
+            "total_keys": 0,
+            "keys_with_ttl": 0,
+            "keys_persistent": 0,
+            "estimated_cleanup_needed": 0
+        }
+        
+        # This would require access to the internal store structure
+        # For now, we'll provide basic stats that can be calculated
+        # without breaking encapsulation
+        
+        try:
+            # Access the store directly for stats (this is a utility function)
+            store = self.memory_store._store[namespace]
+            stats["total_contexts"] = len(store)
+            
+            for context_key, context_store in store.items():
+                stats["total_keys"] += len(context_store)
+                
+                for key in context_store.keys():
+                    ttl = await self.memory_store.get_ttl(namespace, context_key, key)
+                    if ttl == -1:
+                        stats["keys_persistent"] += 1
+                    elif ttl >= 0:
+                        stats["keys_with_ttl"] += 1
+                    else:
+                        stats["estimated_cleanup_needed"] += 1
+        
+        except Exception as e:
+            logger.warning(f"Failed to calculate namespace stats for {namespace}: {e}")
+        
+        return stats
+
+
+# Global TTL manager instance
+ttl_manager = TTLManager()

wappa/persistence/memory/memory_cache_factory.py

@@ -0,0 +1,76 @@
+"""
+Memory cache factory implementation for Wappa framework.
+
+Creates memory-backed cache instances using in-memory storage
+with ICache adapters for uniform interface.
+"""
+
+from ..domain.interfaces.cache_factory import ICacheFactory
+from ..domain.interfaces.cache_interface import ICache
+from .cache_adapters import (
+    MemoryStateCacheAdapter,
+    MemoryTableCacheAdapter,
+    MemoryUserCacheAdapter,
+)
+
+
+class MemoryCacheFactory(ICacheFactory):
+    """
+    Factory for creating memory-backed cache instances.
+
+    Uses thread-safe in-memory storage with TTL support:
+    - State cache: Uses states namespace with automatic TTL cleanup
+    - User cache: Uses users namespace with context isolation
+    - Table cache: Uses tables namespace with tenant isolation
+
+    All instances implement the ICache interface through adapters.
+
+    Context (tenant_id, user_id) is injected at construction time, eliminating
+    manual parameter passing.
+
+    Cache data is stored in memory with automatic background cleanup of expired entries.
+    """
+
+    def __init__(self, tenant_id: str, user_id: str):
+        """Initialize Memory cache factory with context injection."""
+        super().__init__(tenant_id, user_id)
+
+    def create_state_cache(self) -> ICache:
+        """
+        Create Memory state cache instance.
+
+        Uses context (tenant_id, user_id) injected at construction time.
+        Stores data in memory with namespace isolation and automatic TTL cleanup.
+
+        Returns:
+            ICache adapter wrapping MemoryStateHandler
+        """
+        return MemoryStateCacheAdapter(
+            tenant_id=self.tenant_id, user_id=self.user_id
+        )
+
+    def create_user_cache(self) -> ICache:
+        """
+        Create Memory user cache instance.
+
+        Uses context (tenant_id, user_id) injected at construction time.
+        Stores data in memory with namespace isolation and automatic TTL cleanup.
+
+        Returns:
+            ICache adapter wrapping MemoryUser
+        """
+        return MemoryUserCacheAdapter(
+            tenant_id=self.tenant_id, user_id=self.user_id
+        )
+
+    def create_table_cache(self) -> ICache:
+        """
+        Create Memory table cache instance.
+
+        Uses context (tenant_id) injected at construction time.
+        Stores data in memory with namespace isolation and automatic TTL cleanup.
+
+        Returns:
+            ICache adapter wrapping MemoryTable
+        """
+        return MemoryTableCacheAdapter(tenant_id=self.tenant_id)