pfmsoft-api-request 0.1.3__py3-none-any.whl

pfmsoft/api_request/cache/sqlite_cache/query_helpers.py

@@ -0,0 +1,107 @@
+"""SQLite persistence helpers for the cache backend.
+
+This module contains SQL-backed helpers for storing and retrieving
+`CachedResponse` rows in the `WebCache` table.
+"""
+
+import logging
+import sqlite3
+from uuid import UUID
+
+from ..models import CachedResponse
+
+logger = logging.getLogger(__name__)
+
+
+def write_cached_response(
+    connection: sqlite3.Connection, cache_key: str, cached_response: CachedResponse
+) -> None:
+    """Insert or replace a cached response row by key.
+
+    Args:
+        connection: Active SQLite connection.
+        cache_key: Cache key string (UUID text representation).
+        cached_response: Normalized cache model to persist.
+    """
+    query = """
+        INSERT INTO WebCache (
+            cache_key,
+            response_text,
+            response_metadata_json,
+            etag,
+            last_modified,
+            expires_at,
+            cache_timestamp
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(cache_key) DO UPDATE SET
+            response_text = excluded.response_text,
+            response_metadata_json = excluded.response_metadata_json,
+            etag = excluded.etag,
+            last_modified = excluded.last_modified,
+            expires_at = excluded.expires_at,
+            cache_timestamp = excluded.cache_timestamp
+    """
+
+    with connection:
+        connection.execute(
+            query,
+            (
+                cache_key,
+                cached_response.response_text,
+                cached_response.response_metadata_json,
+                cached_response.etag,
+                cached_response.last_modified,
+                cached_response.expires_at,
+                cached_response.cache_timestamp,
+            ),
+        )
+
+
+def query_cached_response(
+    connection: sqlite3.Connection, cache_key: str
+) -> CachedResponse | None:
+    """Query one cached response row by key.
+
+    Args:
+        connection: Active SQLite connection.
+        cache_key: Cache key string (UUID text representation).
+
+    Returns:
+        Matching cached response, or None when no row exists.
+    """
+    query = """
+        SELECT
+            cache_key,
+            response_text,
+            response_metadata_json,
+            etag,
+            last_modified,
+            expires_at,
+            cache_timestamp
+        FROM WebCache
+        WHERE cache_key = ?
+    """
+
+    row = connection.execute(query, (cache_key,)).fetchone()
+    if row is None:
+        return None
+
+    return CachedResponse(
+        cache_key=UUID(row["cache_key"]),
+        response_text=row["response_text"],
+        response_metadata_json=row["response_metadata_json"],
+        etag=row["etag"],
+        last_modified=row["last_modified"],
+        expires_at=row["expires_at"],
+        cache_timestamp=row["cache_timestamp"],
+    )
+
+
+def delete_cached_response(connection: sqlite3.Connection, cache_key: str) -> None:
+    """Delete a cached response row by key.
+
+    This operation is idempotent and does not raise for missing keys.
+    """
+    query = "DELETE FROM WebCache WHERE cache_key = ?"
+    with connection:
+        connection.execute(query, (cache_key,))

pfmsoft/api_request/cache/sqlite_cache/sqlite_cache.py

@@ -0,0 +1,233 @@
+"""SQLite-backed cache provider for request orchestration.
+
+This module provides a `CacheProtocol` implementation backed by a `WebCache`
+table and a small factory for dependency injection.
+"""
+
+import sqlite3
+from pathlib import Path
+from types import TracebackType
+from typing import Self
+from uuid import UUID
+
+from whenever import Instant
+
+from ...request.models import ResponseMetadata
+from ..metadata_helpers import merge_cached_revalidation_metadata
+from ..models import CachedResponse, CacheInfo
+from ..protocols import CacheFactoryProtocol, CacheProtocol
+from . import query_helpers
+from .connection_helpers import create_read_write_connection
+
+
+class SqliteCache(CacheProtocol):
+    """SQLite-backed cache implementation.
+
+    This cache persists entries in the `WebCache` table and maps CRUD operations
+    to SQL statements through query helpers.
+    """
+
+    def __init__(
+        self,
+        db: str | Path | sqlite3.Connection,
+    ) -> None:
+        """Initialize cache with a database path or active SQLite connection.
+
+        Args:
+            db: Either a filesystem path to the SQLite database or an existing
+                sqlite3 connection.
+
+        Notes:
+            When initialized with a path, a read-write connection is created and
+            closed automatically via the context manager.
+
+            When initialized with an existing connection, that connection is never
+            closed by this class.
+        """
+        self._connection: sqlite3.Connection | None = None
+        self._close_connection_on_exit: bool = False
+        if isinstance(db, sqlite3.Connection):
+            self._connection = db
+            self._close_connection_on_exit = False
+            self._connection_path: Path | None = None
+        else:
+            self._connection_path = Path(db)
+
+    async def __aenter__(self) -> Self:
+        """Enter context and open path-owned connections when needed."""
+        if self._connection_path is not None:
+            self._connection = create_read_write_connection(self._connection_path)
+            self._close_connection_on_exit = True
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Exit context and close only connections owned by this instance."""
+        _ = exc_type, exc_value, traceback
+        if self._connection is not None:
+            if self._close_connection_on_exit:
+                self._connection.close()
+
+    def _ensure_connection(self) -> sqlite3.Connection:
+        """Ensure an active SQLite connection is present."""
+        if self._connection is None:
+            raise RuntimeError("No active SQLite connection")
+        return self._connection
+
+    async def get(self, cache_key: UUID) -> CachedResponse | None:
+        """Get a cached response by key, or None when missing."""
+        connection = self._ensure_connection()
+        return query_helpers.query_cached_response(connection, str(cache_key))
+
+    @staticmethod
+    def _ensure_validators(metadata: ResponseMetadata) -> None:
+        """Ensure at least one cache validator is present."""
+        if metadata.etag is None and metadata.last_modified is None:
+            raise ValueError("Cached responses require etag or last_modified")
+
+    @staticmethod
+    def _build_cached_response(
+        *,
+        cache_key: UUID,
+        text: str,
+        metadata: ResponseMetadata,
+    ) -> CachedResponse:
+        """Build a CachedResponse from response text and metadata."""
+        SqliteCache._ensure_validators(metadata)
+        return CachedResponse(
+            cache_key=cache_key,
+            response_text=text,
+            response_metadata_json=metadata.serialize(),
+            etag=metadata.etag,
+            last_modified=metadata.last_modified,
+            expires_at=metadata.expires_at,
+            cache_timestamp=Instant.now().timestamp_nanos(),
+        )
+
+    async def set(
+        self, cache_key: UUID, text: str, metadata: ResponseMetadata
+    ) -> CachedResponse:
+        """Create or replace a cached response entry.
+
+        Raises:
+            ValueError: If both metadata validators are absent.
+        """
+        cached_response = self._build_cached_response(
+            cache_key=cache_key,
+            text=text,
+            metadata=metadata,
+        )
+        connection = self._ensure_connection()
+        query_helpers.write_cached_response(
+            connection,
+            str(cache_key),
+            cached_response,
+        )
+        return cached_response
+
+    async def update_304(
+        self, cache_key: UUID, metadata: ResponseMetadata
+    ) -> CachedResponse:
+        """Refresh a stale entry from 304 metadata while preserving body text.
+
+        Raises:
+            KeyError: If no existing entry is present.
+            ValueError: If merged metadata lacks both validators.
+        """
+        existing = await self.get(cache_key)
+        if existing is None:
+            raise KeyError(f"No cached response found for key {cache_key}")
+
+        existing_metadata = ResponseMetadata.deserialize(
+            existing.response_metadata_json
+        )
+        merged_metadata = merge_cached_revalidation_metadata(
+            cached=existing_metadata,
+            refreshed=metadata,
+        )
+
+        cached_response = self._build_cached_response(
+            cache_key=cache_key,
+            text=existing.response_text,
+            metadata=merged_metadata,
+        )
+        connection = self._ensure_connection()
+        query_helpers.write_cached_response(
+            connection,
+            str(cache_key),
+            cached_response,
+        )
+        return cached_response
+
+    async def delete(self, cache_key: UUID) -> None:
+        """Delete a cached response from the cache.
+
+        This operation is idempotent and does not raise for missing keys.
+        """
+        connection = self._ensure_connection()
+        query_helpers.delete_cached_response(connection, str(cache_key))
+
+    async def clear(
+        self, only_expired: bool = False, age_limit: int | None = None
+    ) -> None:
+        """Clear cached entries matching the requested filters.
+
+        Args:
+            only_expired: When true, remove only expired entries.
+            age_limit: When provided, remove entries with `cache_age` greater
+                than or equal to this nanosecond threshold.
+
+        Notes:
+            When both filters are provided, entries must satisfy both.
+        """
+        connection = self._ensure_connection()
+        if not only_expired and age_limit is None:
+            with connection:
+                connection.execute("DELETE FROM WebCache")
+            return
+
+        clauses: list[str] = []
+        params: list[int] = []
+
+        if only_expired:
+            clauses.append("(expires_at IS NOT NULL AND expires_at <= ?)")
+            params.append(Instant.now().timestamp())
+
+        if age_limit is not None:
+            cutoff = Instant.now().timestamp_nanos() - age_limit
+            clauses.append("cache_timestamp <= ?")
+            params.append(cutoff)
+
+        where_clause = " AND ".join(clauses)
+        query = f"DELETE FROM WebCache WHERE {where_clause}"
+        connection = self._ensure_connection()
+        with connection:
+            connection.execute(query, tuple(params))
+
+    async def flush(self) -> None:
+        """Commit pending writes on the active SQLite connection."""
+        # hot cache not yet implememnted
+        pass
+
+    async def cache_info(self) -> CacheInfo:
+        """Get summary information about the cache."""
+        connection = self._ensure_connection()
+        row = connection.execute("SELECT COUNT(*) AS size FROM WebCache").fetchone()
+        size = 0 if row is None else int(row["size"])
+        return CacheInfo(size=size)
+
+
+class SqliteCacheFactory(CacheFactoryProtocol):
+    """Factory for creating `SqliteCache` instances backed by a DB path."""
+
+    def __init__(self, db_path: str | Path) -> None:
+        """Initialize with the SQLite database path."""
+        self._db_path = db_path
+
+    def __call__(self) -> CacheProtocol:
+        """Create and return a new SQLite-backed cache instance."""
+        return SqliteCache(self._db_path)

pfmsoft/api_request/cache/sqlite_cache/table_definitions.sql

@@ -0,0 +1,23 @@
+-- Table definitions for the api-request web cache SQLite database.
+-- JSON payload columns are stored as TEXT.
+-- Timestamps are stored as integers; units vary by column.
+
+
+-- The WebCache table stores one row per cached response key.
+-- cache_key: unique key identifying a cache entry.
+-- response_text: serialized response body text.
+-- response_metadata_json: JSON-encoded response metadata.
+-- etag: ETag validator, if present.
+-- last_modified: Last-Modified validator, if present.
+-- expires_at: Unix timestamp in seconds when the entry becomes stale.
+-- cache_timestamp: Unix timestamp in nanoseconds for write/update time.
+CREATE TABLE IF NOT EXISTS WebCache (
+    ID INTEGER PRIMARY KEY AUTOINCREMENT,
+    cache_key TEXT NOT NULL UNIQUE,
+    response_text TEXT NOT NULL,
+    response_metadata_json TEXT NOT NULL,
+    etag TEXT,
+    last_modified TEXT,
+    expires_at INTEGER,
+    cache_timestamp INTEGER NOT NULL
+);

pfmsoft/api_request/cli/__init__.py

@@ -0,0 +1,17 @@
+"""CLI command modules for api-request.
+
+This package contains Typer applications and helper functions used by the
+`eve-auth`/`api-request` command-line entrypoints.
+"""
+
+import typer
+
+from .cache import app as cache_app
+from .request import app as request_app
+
+app = typer.Typer(no_args_is_help=True)
+
+app.add_typer(
+    cache_app, name="cache", help="Commands for working with the cache database."
+)
+app.add_typer(request_app, name="request", help="Commands for making API requests.")

pfmsoft/api_request/cli/cache/__init__.py

@@ -0,0 +1,12 @@
+"""Commands for working with the cache database."""
+
+import typer
+
+from .info import app as info_app
+
+app = typer.Typer(
+    no_args_is_help=True,
+    name="cache",
+    help="Commands for working with the cache database.",
+)
+app.add_typer(info_app)

pfmsoft/api_request/cli/cache/info.py

@@ -0,0 +1,11 @@
+import typer
+
+app = typer.Typer(no_args_is_help=True)
+
+
+app.command()
+
+
+def info(ctx: typer.Context) -> None:
+    """Display information about the cache database."""
+    typer.echo("Cache Info Placeholder...")

pfmsoft/api_request/cli/helpers.py

@@ -0,0 +1,41 @@
+"""Helper functions for the api-request CLI."""
+
+import sys
+from typing import cast
+
+from typer import Context
+
+from pfmsoft.api_request.settings import SETTINGS_KEY, ApiRequestSettings
+
+
+def get_api_request_settings_from_context(ctx: Context) -> ApiRequestSettings:
+    """Return ApiRequestSettings stored in the Typer context.
+
+    Args:
+        ctx: Typer command context whose obj mapping should contain the
+            initialized ApiRequestSettings.
+
+    Returns:
+        ApiRequestSettings stored under the `settings.SETTINGS_KEY` key.
+
+    Raises:
+        ValueError: If the context does not contain initialized ApiRequestSettings.
+    """
+    if ctx.obj is None or SETTINGS_KEY not in ctx.obj:
+        raise ValueError("ApiRequestSettings not found in context.")
+    return cast(ApiRequestSettings, ctx.obj[SETTINGS_KEY])
+
+
+def get_stdin() -> str:
+    """Read piped or redirected stdin content until EOF.
+
+    Returns:
+        Full stdin content as a string.
+
+    Raises:
+        ValueError: If stdin is attached to an interactive terminal instead
+            of a pipe or redirected input source.
+    """
+    if sys.stdin.isatty():
+        raise ValueError("Error: provide a file path or pipe data via stdin.")
+    return sys.stdin.read()

pfmsoft/api_request/cli/main_typer.py

@@ -0,0 +1,52 @@
+"""Main entry point for the api-request CLI.
+
+NOTE: This is not currently the entry point, as so far there is only one command.
+If additional commands are added, this module will be the entry point and will
+dispatch to subcommands.
+"""
+
+import logging
+from dataclasses import asdict
+
+import typer
+
+from pfmsoft.api_request import __app_name__, __version__
+from pfmsoft.api_request.cli import app as api_request_app
+from pfmsoft.api_request.cli.helpers import get_api_request_settings_from_context
+from pfmsoft.api_request.logging_config import setup_logging
+from pfmsoft.api_request.settings import SETTINGS_KEY, get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def default_options(ctx: typer.Context) -> None:
+    """Initialize settings and logging for standalone CLI execution.
+
+    Args:
+        ctx: Typer command context used to store shared application settings
+            for downstream subcommands.
+
+    Notes:
+        The resolved ApiRequestSettings object is stored in ctx.obj under the
+        `api-request-settings` key.
+    """
+    settings = get_settings()
+    setup_logging(log_dir=settings.logging_directory)
+    ctx.obj = {SETTINGS_KEY: settings}
+    logger.info(
+        f"Starting {__app_name__} v{__version__} with settings: {asdict(settings)!r}"
+    )
+
+
+app = typer.Typer(callback=default_options, no_args_is_help=True)
+
+
+@app.command()
+def version(ctx: typer.Context) -> None:
+    """Print the version of the api-request CLI."""
+    settings = get_api_request_settings_from_context(ctx)
+    typer.echo(f"{__app_name__} v{__version__}")
+    typer.echo(f"Settings: {asdict(settings)!r}")
+
+
+app.add_typer(api_request_app)

pfmsoft/api_request/cli/request/__init__.py

@@ -0,0 +1,11 @@
+"""Commands for working with requests."""
+
+import typer
+
+from .request import app as request_app
+from .validate import app as validate_app
+
+app = typer.Typer(no_args_is_help=True)
+
+app.add_typer(request_app)
+app.add_typer(validate_app)