gtg 0.4.0__py3-none-any.whl

goodtogo/adapters/cache_memory.py

@@ -0,0 +1,208 @@
+"""In-memory cache adapter for testing.
+
+This module provides a simple dict-based cache implementation that implements
+the CachePort interface. It is primarily intended for testing and development
+scenarios where persistence is not required.
+
+The cache stores entries with expiration timestamps and tracks hit/miss
+statistics for performance monitoring.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from typing import Optional
+
+from goodtogo.adapters.time_provider import SystemTimeProvider
+from goodtogo.core.interfaces import CachePort, TimeProvider
+from goodtogo.core.models import CacheStats
+
+
+@dataclass
+class CacheEntry:
+    """A single cache entry with value and expiration.
+
+    Attributes:
+        value: The cached string value.
+        expires_at: Unix timestamp when this entry expires.
+    """
+
+    value: str
+    expires_at: float
+
+
+class InMemoryCacheAdapter(CachePort):
+    """Simple dict-based cache implementation for testing.
+
+    This adapter provides an in-memory cache that:
+    - Stores entries with expiration timestamps
+    - Tracks cache hit/miss statistics
+    - Supports glob-style pattern matching for invalidation
+    - Automatically excludes expired entries from get operations
+
+    The cache is not thread-safe and is intended for single-threaded
+    test scenarios. For production use, consider SqliteCacheAdapter
+    or RedisCacheAdapter.
+
+    Example:
+        cache = InMemoryCacheAdapter()
+        cache.set("key", "value", ttl_seconds=300)
+        value = cache.get("key")  # Returns "value"
+        cache.invalidate_pattern("key:*")  # Invalidate matching keys
+
+    Attributes:
+        _store: Internal dictionary storing CacheEntry objects.
+        _hits: Counter for cache hits.
+        _misses: Counter for cache misses.
+    """
+
+    def __init__(self, time_provider: Optional[TimeProvider] = None) -> None:
+        """Initialize an empty in-memory cache.
+
+        Args:
+            time_provider: TimeProvider for getting current time.
+                          Defaults to SystemTimeProvider if not provided.
+        """
+        self._store: dict[str, CacheEntry] = {}
+        self._hits: int = 0
+        self._misses: int = 0
+        self._time_provider: TimeProvider = time_provider or SystemTimeProvider()
+
+    def get(self, key: str) -> Optional[str]:
+        """Get cached value if it exists and has not expired.
+
+        Retrieves a value from the cache. If the entry exists but has
+        expired, it is treated as a cache miss and the entry is removed.
+
+        This method updates hit/miss statistics.
+
+        Args:
+            key: Cache key to retrieve.
+
+        Returns:
+            The cached string value if found and not expired, None otherwise.
+        """
+        entry = self._store.get(key)
+
+        if entry is None:
+            self._misses += 1
+            return None
+
+        # Check if entry has expired
+        if entry.expires_at <= self._time_provider.now():
+            # Remove expired entry
+            del self._store[key]
+            self._misses += 1
+            return None
+
+        self._hits += 1
+        return entry.value
+
+    def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        """Set cached value with TTL.
+
+        Stores a value in the cache with an expiration time. If an entry
+        with the same key already exists, it is overwritten.
+
+        Args:
+            key: Cache key to store under.
+            value: String value to cache.
+            ttl_seconds: Time to live in seconds. The entry will be
+                        considered expired after this duration.
+        """
+        expires_at = self._time_provider.now() + ttl_seconds
+        self._store[key] = CacheEntry(value=value, expires_at=expires_at)
+
+    def delete(self, key: str) -> None:
+        """Delete cached value.
+
+        Removes a specific entry from the cache. If the key does not
+        exist, this is a no-op.
+
+        Args:
+            key: Cache key to delete.
+        """
+        self._store.pop(key, None)
+
+    def invalidate_pattern(self, pattern: str) -> None:
+        """Invalidate all keys matching pattern.
+
+        Removes all cache entries whose keys match the given glob-style
+        pattern. Uses fnmatch for pattern matching, which supports:
+        - * matches everything
+        - ? matches any single character
+        - [seq] matches any character in seq
+        - [!seq] matches any character not in seq
+
+        Args:
+            pattern: Glob-style pattern to match keys against.
+                    Example: 'pr:myorg:myrepo:123:*' matches all keys
+                    starting with 'pr:myorg:myrepo:123:'.
+        """
+        # Collect keys to delete (avoid modifying dict during iteration)
+        keys_to_delete = [key for key in self._store if fnmatch(key, pattern)]
+
+        for key in keys_to_delete:
+            del self._store[key]
+
+    def cleanup_expired(self) -> None:
+        """Remove all expired entries.
+
+        Scans the entire cache and removes any entries whose TTL has
+        expired. This should be called periodically to prevent unbounded
+        memory growth from accumulated expired entries.
+        """
+        current_time = self._time_provider.now()
+
+        # Collect expired keys (avoid modifying dict during iteration)
+        expired_keys = [
+            key for key, entry in self._store.items() if entry.expires_at <= current_time
+        ]
+
+        for key in expired_keys:
+            del self._store[key]
+
+    def get_stats(self) -> CacheStats:
+        """Get cache hit/miss statistics.
+
+        Returns metrics about cache performance. The hit rate is calculated
+        as hits / (hits + misses). If no operations have been performed,
+        the hit rate is 0.0.
+
+        Returns:
+            CacheStats object containing hits, misses, and hit_rate.
+        """
+        total = self._hits + self._misses
+        hit_rate = self._hits / total if total > 0 else 0.0
+
+        return CacheStats(hits=self._hits, misses=self._misses, hit_rate=hit_rate)
+
+    def clear(self) -> None:
+        """Clear all entries and reset statistics.
+
+        Removes all cached entries and resets hit/miss counters to zero.
+        This is useful for test setup/teardown.
+        """
+        self._store.clear()
+        self._hits = 0
+        self._misses = 0
+
+    def __len__(self) -> int:
+        """Return the number of entries in the cache.
+
+        Note that this includes potentially expired entries that have
+        not yet been cleaned up.
+
+        Returns:
+            Number of entries currently in the cache.
+        """
+        return len(self._store)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the cache.
+
+        Returns:
+            String showing cache type and entry count.
+        """
+        return f"InMemoryCacheAdapter(entries={len(self._store)})"

goodtogo/adapters/cache_sqlite.py

@@ -0,0 +1,305 @@
+"""SQLite cache adapter for GoodToMerge.
+
+This module provides a SQLite-based implementation of the CachePort interface.
+It offers zero-configuration local caching with automatic TTL expiration,
+secure file permissions, and pattern-based invalidation.
+
+Security features:
+- Cache directory created with 0700 permissions (owner only)
+- Cache file created with 0600 permissions (owner read/write only)
+- Existing permissive permissions are fixed with a warning
+- All inputs validated before use
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import stat
+import warnings
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from goodtogo.adapters.time_provider import SystemTimeProvider
+from goodtogo.core.interfaces import CachePort, TimeProvider
+
+if TYPE_CHECKING:
+    from goodtogo.core.models import CacheStats
+
+
+# SQL statements for schema creation and operations
+_CREATE_TABLES_SQL = """
+CREATE TABLE IF NOT EXISTS pr_cache (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    expires_at INTEGER NOT NULL,
+    created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_expires_at ON pr_cache(expires_at);
+
+CREATE TABLE IF NOT EXISTS cache_stats (
+    key_prefix TEXT PRIMARY KEY,
+    hits INTEGER DEFAULT 0,
+    misses INTEGER DEFAULT 0
+);
+
+-- Initialize global stats if not exists
+INSERT OR IGNORE INTO cache_stats (key_prefix, hits, misses) VALUES ('global', 0, 0);
+"""
+
+
+class SqliteCacheAdapter(CachePort):
+    """SQLite-based cache adapter implementing the CachePort interface.
+
+    This adapter provides persistent local caching using SQLite with:
+    - Automatic TTL-based expiration
+    - Pattern-based key invalidation using SQL LIKE
+    - Hit/miss statistics tracking
+    - Secure file permissions
+
+    The cache database is created automatically on first use with
+    appropriate file permissions to protect cached data.
+
+    Example:
+        >>> cache = SqliteCacheAdapter(".goodtogo/cache.db")
+        >>> cache.set("pr:myorg:myrepo:123:meta", '{"title": "My PR"}', ttl_seconds=300)
+        >>> value = cache.get("pr:myorg:myrepo:123:meta")
+        >>> cache.invalidate_pattern("pr:myorg:myrepo:123:%")
+
+    Attributes:
+        db_path: Path to the SQLite database file.
+    """
+
+    def __init__(self, db_path: str, time_provider: Optional[TimeProvider] = None) -> None:
+        """Initialize the SQLite cache adapter.
+
+        Creates the cache directory and database file with secure permissions
+        if they don't exist. If the file exists with permissive permissions,
+        they are tightened and a warning is issued.
+
+        Args:
+            db_path: Path to the SQLite database file. Parent directories
+                    will be created if they don't exist.
+            time_provider: Optional TimeProvider for time operations.
+                          Defaults to SystemTimeProvider if not provided.
+
+        Raises:
+            OSError: If unable to create directory or set permissions.
+        """
+        self.db_path = db_path
+        self._time_provider = time_provider or SystemTimeProvider()
+        self._connection: Optional[sqlite3.Connection] = None
+        self._ensure_secure_path()
+        self._init_database()
+
+    def _ensure_secure_path(self) -> None:
+        """Ensure cache directory and file have secure permissions.
+
+        Creates the directory with 0700 permissions and ensures the file
+        (if it exists) has 0600 permissions. Issues a warning if existing
+        permissions were too permissive.
+        """
+        path = Path(self.db_path)
+        cache_dir = path.parent
+
+        # Create directory with secure permissions if needed
+        if cache_dir and not cache_dir.exists():
+            cache_dir.mkdir(parents=True, mode=0o700, exist_ok=True)
+        elif cache_dir and cache_dir.exists():
+            # Ensure existing directory has correct permissions
+            current_mode = stat.S_IMODE(cache_dir.stat().st_mode)
+            if current_mode != 0o700:
+                cache_dir.chmod(0o700)
+
+        # Check existing file permissions and fix if necessary
+        if path.exists():
+            current_mode = stat.S_IMODE(path.stat().st_mode)
+            # Check if group or others have any permissions
+            if current_mode & (stat.S_IRWXG | stat.S_IRWXO):
+                warnings.warn(
+                    f"Cache file {self.db_path} had permissive permissions "
+                    f"({oct(current_mode)}). Fixing to 0600.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+                path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+    def _init_database(self) -> None:
+        """Initialize the database schema.
+
+        Creates the pr_cache and cache_stats tables if they don't exist.
+        Sets file permissions to 0600 after creation.
+        """
+        conn = self._get_connection()
+        conn.executescript(_CREATE_TABLES_SQL)
+        conn.commit()
+
+        # Ensure file has correct permissions after creation
+        path = Path(self.db_path)
+        if path.exists():
+            path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get or create a database connection.
+
+        Returns:
+            Active SQLite connection with row factory set to sqlite3.Row.
+        """
+        if self._connection is None:
+            self._connection = sqlite3.connect(self.db_path)
+            self._connection.row_factory = sqlite3.Row
+        return self._connection
+
+    def get(self, key: str) -> Optional[str]:
+        """Get cached value.
+
+        Retrieves a value from the cache if it exists and has not expired.
+        Updates hit/miss statistics accordingly.
+
+        Args:
+            key: Cache key (e.g., 'pr:myorg:myrepo:123:meta').
+
+        Returns:
+            Cached value as string if found and not expired, None otherwise.
+        """
+        conn = self._get_connection()
+        current_time = self._time_provider.now_int()
+
+        cursor = conn.execute(
+            "SELECT value FROM pr_cache WHERE key = ? AND expires_at > ?",
+            (key, current_time),
+        )
+        row = cursor.fetchone()
+
+        if row is not None:
+            # Cache hit
+            conn.execute("UPDATE cache_stats SET hits = hits + 1 WHERE key_prefix = 'global'")
+            conn.commit()
+            return str(row["value"])
+        else:
+            # Cache miss
+            conn.execute("UPDATE cache_stats SET misses = misses + 1 WHERE key_prefix = 'global'")
+            conn.commit()
+            return None
+
+    def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        """Set cached value with TTL.
+
+        Stores a value in the cache with an expiration time. If a value
+        already exists for the key, it is replaced.
+
+        Args:
+            key: Cache key (e.g., 'pr:myorg:myrepo:123:meta').
+            value: Value to cache (typically JSON string).
+            ttl_seconds: Time to live in seconds. After this duration,
+                        the entry is considered expired.
+        """
+        conn = self._get_connection()
+        current_time = self._time_provider.now_int()
+        expires_at = current_time + ttl_seconds
+
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO pr_cache (key, value, expires_at, created_at)
+            VALUES (?, ?, ?, ?)
+            """,
+            (key, value, expires_at, current_time),
+        )
+        conn.commit()
+
+    def delete(self, key: str) -> None:
+        """Delete cached value.
+
+        Removes a specific entry from the cache.
+
+        Args:
+            key: Cache key to delete.
+        """
+        conn = self._get_connection()
+        conn.execute("DELETE FROM pr_cache WHERE key = ?", (key,))
+        conn.commit()
+
+    def invalidate_pattern(self, pattern: str) -> None:
+        """Invalidate all keys matching pattern.
+
+        Removes all cache entries whose keys match the given pattern.
+        Uses SQL LIKE pattern matching where '%' matches any sequence
+        of characters and '_' matches any single character.
+
+        For glob-style patterns using '*', convert to SQL LIKE:
+        - 'pr:myorg:myrepo:123:*' -> 'pr:myorg:myrepo:123:%'
+
+        Args:
+            pattern: Pattern to match keys against. Use '%' as wildcard
+                    for SQL LIKE matching (e.g., 'pr:myorg:myrepo:123:%').
+
+        Note:
+            The pattern is converted from glob-style to SQL LIKE:
+            - '*' is converted to '%'
+            - '?' is converted to '_'
+        """
+        conn = self._get_connection()
+
+        # Convert glob-style wildcards to SQL LIKE pattern
+        sql_pattern = pattern.replace("*", "%").replace("?", "_")
+
+        conn.execute("DELETE FROM pr_cache WHERE key LIKE ?", (sql_pattern,))
+        conn.commit()
+
+    def cleanup_expired(self) -> None:
+        """Remove expired entries.
+
+        Deletes all entries whose TTL has expired. This should be called
+        periodically to prevent unbounded cache growth.
+        """
+        conn = self._get_connection()
+        current_time = self._time_provider.now_int()
+        conn.execute("DELETE FROM pr_cache WHERE expires_at <= ?", (current_time,))
+        conn.commit()
+
+    def get_stats(self) -> CacheStats:
+        """Get cache hit/miss statistics.
+
+        Returns metrics about cache performance for monitoring and
+        debugging purposes.
+
+        Returns:
+            CacheStats object containing:
+            - hits: Number of successful cache lookups
+            - misses: Number of cache misses
+            - hit_rate: Ratio of hits to total lookups (0.0 to 1.0)
+        """
+        # Import here to avoid circular imports
+        from goodtogo.core.models import CacheStats
+
+        conn = self._get_connection()
+        cursor = conn.execute("SELECT hits, misses FROM cache_stats WHERE key_prefix = 'global'")
+        row = cursor.fetchone()
+
+        if row is None:
+            return CacheStats(hits=0, misses=0, hit_rate=0.0)
+
+        hits = row["hits"]
+        misses = row["misses"]
+        total = hits + misses
+        hit_rate = hits / total if total > 0 else 0.0
+
+        return CacheStats(hits=hits, misses=misses, hit_rate=hit_rate)
+
+    def close(self) -> None:
+        """Close the database connection.
+
+        Should be called when the cache is no longer needed to release
+        database resources.
+        """
+        if self._connection is not None:
+            self._connection.close()
+            self._connection = None
+
+    def __del__(self) -> None:
+        """Ensure connection is closed on garbage collection."""
+        self.close()
+
+    def __repr__(self) -> str:
+        """Return string representation of the adapter."""
+        return f"SqliteCacheAdapter(db_path={self.db_path!r})"