truthound-dashboard 1.0.0__py3-none-any.whl

truthound_dashboard/db/repository.py

@@ -0,0 +1,237 @@
+"""Generic repository pattern for database operations.
+
+This module provides a generic repository base class that implements
+common CRUD operations, reducing boilerplate in API endpoints.
+
+Example:
+    class SourceRepository(BaseRepository[Source]):
+        pass
+
+    async with get_session() as session:
+        repo = SourceRepository(session)
+        source = await repo.get_by_id("uuid-here")
+        sources = await repo.list(limit=10)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Generic, TypeVar
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql import Select
+
+from .base import Base
+
+# Type variable for model classes
+ModelT = TypeVar("ModelT", bound=Base)
+
+
+class BaseRepository(Generic[ModelT]):
+    """Generic repository providing common CRUD operations.
+
+    This class implements the repository pattern for database access,
+    providing a clean abstraction over SQLAlchemy operations.
+
+    Type Parameters:
+        ModelT: The SQLAlchemy model class this repository manages.
+
+    Attributes:
+        session: The async database session.
+        model: The model class for this repository.
+    """
+
+    model: type[ModelT]
+
+    def __init__(self, session: AsyncSession) -> None:
+        """Initialize repository with database session.
+
+        Args:
+            session: Async database session for operations.
+        """
+        self.session = session
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Set model class from generic type argument."""
+        super().__init_subclass__(**kwargs)
+        # Get the model type from Generic parameters
+        for base in cls.__orig_bases__:  # type: ignore
+            if hasattr(base, "__args__"):
+                cls.model = base.__args__[0]
+                break
+
+    async def get_by_id(self, id: str) -> ModelT | None:
+        """Get a single record by ID.
+
+        Args:
+            id: The record's primary key.
+
+        Returns:
+            The model instance or None if not found.
+        """
+        result = await self.session.execute(
+            select(self.model).where(self.model.id == id)
+        )
+        return result.scalar_one_or_none()
+
+    async def get_by_id_or_raise(self, id: str) -> ModelT:
+        """Get a single record by ID, raising if not found.
+
+        Args:
+            id: The record's primary key.
+
+        Returns:
+            The model instance.
+
+        Raises:
+            ValueError: If record not found.
+        """
+        record = await self.get_by_id(id)
+        if record is None:
+            raise ValueError(f"{self.model.__name__} with id '{id}' not found")
+        return record
+
+    async def list(
+        self,
+        *,
+        offset: int = 0,
+        limit: int = 100,
+        order_by: Any = None,
+        filters: list[Any] | None = None,
+    ) -> Sequence[ModelT]:
+        """List records with pagination and filtering.
+
+        Args:
+            offset: Number of records to skip.
+            limit: Maximum records to return.
+            order_by: Column(s) to order by.
+            filters: List of SQLAlchemy filter conditions.
+
+        Returns:
+            Sequence of model instances.
+        """
+        query = self._build_query(filters)
+
+        if order_by is not None:
+            query = query.order_by(order_by)
+        elif hasattr(self.model, "created_at"):
+            query = query.order_by(self.model.created_at.desc())
+
+        query = query.offset(offset).limit(limit)
+        result = await self.session.execute(query)
+        return result.scalars().all()
+
+    async def count(self, filters: list[Any] | None = None) -> int:
+        """Count records matching filters.
+
+        Args:
+            filters: List of SQLAlchemy filter conditions.
+
+        Returns:
+            Total count of matching records.
+        """
+        query = select(func.count()).select_from(self.model)
+        if filters:
+            for f in filters:
+                query = query.where(f)
+        result = await self.session.execute(query)
+        return result.scalar_one()
+
+    async def create(self, **kwargs: Any) -> ModelT:
+        """Create a new record.
+
+        Args:
+            **kwargs: Field values for the new record.
+
+        Returns:
+            The created model instance.
+        """
+        instance = self.model(**kwargs)
+        self.session.add(instance)
+        await self.session.flush()
+        await self.session.refresh(instance)
+        return instance
+
+    async def update(self, id: str, **kwargs: Any) -> ModelT | None:
+        """Update a record by ID.
+
+        Args:
+            id: The record's primary key.
+            **kwargs: Field values to update.
+
+        Returns:
+            The updated model instance or None if not found.
+        """
+        instance = await self.get_by_id(id)
+        if instance is None:
+            return None
+
+        for key, value in kwargs.items():
+            if hasattr(instance, key):
+                setattr(instance, key, value)
+
+        await self.session.flush()
+        await self.session.refresh(instance)
+        return instance
+
+    async def delete(self, id: str) -> bool:
+        """Delete a record by ID.
+
+        Args:
+            id: The record's primary key.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        instance = await self.get_by_id(id)
+        if instance is None:
+            return False
+
+        await self.session.delete(instance)
+        await self.session.flush()
+        return True
+
+    async def bulk_create(self, items: list[dict[str, Any]]) -> list[ModelT]:
+        """Create multiple records at once.
+
+        Args:
+            items: List of dictionaries with field values.
+
+        Returns:
+            List of created model instances.
+        """
+        instances = [self.model(**item) for item in items]
+        self.session.add_all(instances)
+        await self.session.flush()
+        for instance in instances:
+            await self.session.refresh(instance)
+        return instances
+
+    async def exists(self, id: str) -> bool:
+        """Check if a record exists.
+
+        Args:
+            id: The record's primary key.
+
+        Returns:
+            True if exists, False otherwise.
+        """
+        query = select(func.count()).select_from(self.model).where(self.model.id == id)
+        result = await self.session.execute(query)
+        return result.scalar_one() > 0
+
+    def _build_query(self, filters: list[Any] | None = None) -> Select:
+        """Build base query with filters.
+
+        Args:
+            filters: List of SQLAlchemy filter conditions.
+
+        Returns:
+            Select query with filters applied.
+        """
+        query = select(self.model)
+        if filters:
+            for f in filters:
+                query = query.where(f)
+        return query

truthound_dashboard/main.py

@@ -0,0 +1,309 @@
+"""FastAPI application entry point.
+
+This module defines the main FastAPI application with all middleware,
+routers, and lifecycle management.
+
+The application serves both the API and the React SPA static files.
+
+Features:
+- Phase 4 production-ready components:
+  - Rate limiting and security headers
+  - Structured logging
+  - Error handling with localization
+  - Database maintenance scheduling
+  - Cache management
+
+Example:
+    # Run with uvicorn
+    uvicorn truthound_dashboard.main:app --reload
+
+    # Or via CLI
+    truthound serve --reload
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from truthound_dashboard import __version__
+from truthound_dashboard.api.error_handlers import setup_error_handlers
+from truthound_dashboard.api.middleware import (
+    RateLimitConfig,
+    RateLimitMiddleware,
+    RequestLoggingMiddleware,
+    SecurityHeadersMiddleware,
+)
+from truthound_dashboard.api.router import api_router
+from truthound_dashboard.config import get_settings
+from truthound_dashboard.core.cache import get_cache
+from truthound_dashboard.core.logging import setup_logging
+from truthound_dashboard.core.maintenance import get_maintenance_manager
+from truthound_dashboard.core.scheduler import get_scheduler
+from truthound_dashboard.db import init_db
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]:
+    """Application lifespan manager.
+
+    Handles startup and shutdown events:
+    - Startup:
+        - Configure logging
+        - Initialize database tables
+        - Start cache cleanup task
+        - Start validation scheduler
+        - Schedule maintenance tasks
+    - Shutdown:
+        - Stop scheduler
+        - Stop cache cleanup
+        - Cleanup resources
+
+    Args:
+        app: FastAPI application instance.
+
+    Yields:
+        None during application runtime.
+    """
+    settings = get_settings()
+
+    # Configure logging
+    setup_logging(level=settings.log_level)
+    logger.info(f"Starting Truthound Dashboard v{__version__}")
+
+    # Initialize database
+    await init_db()
+    logger.info("Database initialized")
+
+    # Start cache cleanup
+    cache = get_cache()
+    await cache.start_cleanup_task()
+    logger.info("Cache cleanup task started")
+
+    # Start scheduler
+    scheduler = get_scheduler()
+    await scheduler.start()
+    logger.info("Validation scheduler started")
+
+    # Register maintenance tasks with scheduler
+    _register_maintenance_tasks()
+
+    yield
+
+    # Shutdown
+    logger.info("Shutting down Truthound Dashboard")
+
+    # Stop scheduler
+    await scheduler.stop()
+    logger.info("Scheduler stopped")
+
+    # Stop cache cleanup
+    await cache.stop_cleanup_task()
+    logger.info("Cache cleanup stopped")
+
+
+def _register_maintenance_tasks() -> None:
+    """Register maintenance tasks with the scheduler.
+
+    Schedules daily cleanup at 3 AM and weekly vacuum on Sunday at 4 AM.
+    """
+    from apscheduler.triggers.cron import CronTrigger
+
+    from truthound_dashboard.core.maintenance import (
+        cleanup_notification_logs,
+        cleanup_old_profiles,
+        cleanup_old_validations,
+        vacuum_database,
+    )
+
+    scheduler = get_scheduler()
+
+    # Daily cleanup at 3 AM
+    scheduler._scheduler.add_job(
+        cleanup_old_validations,
+        trigger=CronTrigger.from_crontab("0 3 * * *"),
+        id="maintenance_validations",
+        replace_existing=True,
+        name="Cleanup old validations",
+    )
+
+    scheduler._scheduler.add_job(
+        cleanup_old_profiles,
+        trigger=CronTrigger.from_crontab("0 3 * * *"),
+        id="maintenance_profiles",
+        replace_existing=True,
+        name="Cleanup old profiles",
+    )
+
+    scheduler._scheduler.add_job(
+        cleanup_notification_logs,
+        trigger=CronTrigger.from_crontab("0 3 * * *"),
+        id="maintenance_notification_logs",
+        replace_existing=True,
+        name="Cleanup notification logs",
+    )
+
+    # Weekly vacuum on Sunday at 4 AM
+    scheduler._scheduler.add_job(
+        vacuum_database,
+        trigger=CronTrigger.from_crontab("0 4 * * 0"),
+        id="maintenance_vacuum",
+        replace_existing=True,
+        name="Database vacuum",
+    )
+
+    logger.info("Maintenance tasks registered")
+
+
+def create_app() -> FastAPI:
+    """Create and configure FastAPI application.
+
+    This factory function creates a fully configured FastAPI app
+    with all middleware, routes, and static file handling.
+
+    Returns:
+        Configured FastAPI application.
+    """
+    app = FastAPI(
+        title="Truthound Dashboard",
+        description="Open-source data quality dashboard - GX Cloud alternative",
+        version=__version__,
+        lifespan=lifespan,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/api/openapi.json",
+    )
+
+    # Configure CORS (must be first middleware)
+    configure_cors(app)
+
+    # Add security middleware
+    configure_middleware(app)
+
+    # Register exception handlers
+    setup_error_handlers(app)
+
+    # Include API routes
+    app.include_router(api_router, prefix="/api/v1")
+
+    # Mount static files for React SPA
+    mount_static_files(app)
+
+    return app
+
+
+def configure_cors(app: FastAPI) -> None:
+    """Configure CORS middleware.
+
+    Allows requests from the Vite dev server during development.
+
+    Args:
+        app: FastAPI application.
+    """
+    settings = get_settings()
+
+    origins = [
+        "http://localhost:5173",  # Vite dev server
+        "http://127.0.0.1:5173",
+        f"http://localhost:{settings.port}",  # Dashboard server
+        f"http://127.0.0.1:{settings.port}",
+    ]
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+def configure_middleware(app: FastAPI) -> None:
+    """Configure security and logging middleware.
+
+    Adds:
+    - Request logging
+    - Rate limiting
+    - Security headers
+
+    Args:
+        app: FastAPI application.
+    """
+    # Request logging (last added = first executed)
+    app.add_middleware(RequestLoggingMiddleware)
+
+    # Rate limiting
+    rate_limit_config = RateLimitConfig(
+        requests_per_minute=120,
+        exclude_paths=[
+            "/health",
+            "/docs",
+            "/redoc",
+            "/openapi.json",
+            "/api/openapi.json",
+        ],
+    )
+    app.add_middleware(RateLimitMiddleware, config=rate_limit_config)
+
+    # Security headers
+    app.add_middleware(SecurityHeadersMiddleware)
+
+
+def mount_static_files(app: FastAPI) -> None:
+    """Mount static files for React SPA.
+
+    Serves the built React application from the static directory.
+    Falls back to index.html for SPA routing.
+
+    Args:
+        app: FastAPI application.
+    """
+    static_dir = Path(__file__).parent / "static"
+
+    if not static_dir.exists():
+        return
+
+    index_file = static_dir / "index.html"
+    if not index_file.exists():
+        return
+
+    # Mount assets directory
+    assets_dir = static_dir / "assets"
+    if assets_dir.exists():
+        app.mount(
+            "/assets",
+            StaticFiles(directory=assets_dir),
+            name="assets",
+        )
+
+    # SPA fallback route - must be last
+    @app.get("/{full_path:path}", include_in_schema=False)
+    async def serve_spa(full_path: str) -> FileResponse:
+        """Serve SPA for all non-API routes.
+
+        Args:
+            full_path: Requested path.
+
+        Returns:
+            Static file or index.html for SPA routing.
+        """
+        # Check if it's a static file
+        file_path = static_dir / full_path
+        if file_path.exists() and file_path.is_file():
+            return FileResponse(file_path)
+
+        # Fall back to index.html for SPA routing
+        return FileResponse(index_file)
+
+
+# Create app instance
+app = create_app()

truthound_dashboard/schemas/__init__.py

@@ -0,0 +1,150 @@
+"""Pydantic schemas for API request/response validation.
+
+This module exports all schemas used in the API layer.
+Schemas follow consistent naming conventions:
+- *Base: Common fields
+- *Create: POST request bodies
+- *Update: PUT/PATCH request bodies
+- *Response: Response bodies
+- *ListResponse: Paginated list responses
+"""
+
+from .base import (
+    BaseSchema,
+    ErrorResponse,
+    IDMixin,
+    ListResponseWrapper,
+    MessageResponse,
+    ResponseWrapper,
+    TimestampMixin,
+)
+from .drift import (
+    ColumnDriftResult,
+    DriftCompareRequest,
+    DriftComparisonListItem,
+    DriftComparisonListResponse,
+    DriftComparisonResponse,
+    DriftResult,
+    DriftSourceSummary,
+)
+from .history import (
+    FailureFrequencyItem,
+    HistoryQueryParams,
+    HistoryResponse,
+    HistorySummary,
+    RecentValidation,
+    TrendDataPoint,
+)
+from .profile import ColumnProfile, ProfileResponse
+from .rule import (
+    RuleBase,
+    RuleCreate,
+    RuleListItem,
+    RuleListResponse,
+    RuleResponse,
+    RuleSummary,
+    RuleUpdate,
+)
+from .schedule import (
+    ScheduleActionResponse,
+    ScheduleBase,
+    ScheduleCreate,
+    ScheduleListItem,
+    ScheduleListResponse,
+    ScheduleResponse,
+    ScheduleUpdate,
+)
+from .schema import (
+    ColumnSchema,
+    SchemaLearnRequest,
+    SchemaResponse,
+    SchemaSummary,
+    SchemaUpdateRequest,
+)
+from .source import (
+    SourceBase,
+    SourceCreate,
+    SourceListResponse,
+    SourceResponse,
+    SourceSummary,
+    SourceType,
+    SourceUpdate,
+)
+from .validation import (
+    IssueSeverity,
+    ValidationIssue,
+    ValidationListItem,
+    ValidationListResponse,
+    ValidationResponse,
+    ValidationRunRequest,
+    ValidationStatus,
+    ValidationSummary,
+)
+
+__all__ = [
+    # Base
+    "BaseSchema",
+    "IDMixin",
+    "TimestampMixin",
+    "ResponseWrapper",
+    "ListResponseWrapper",
+    "ErrorResponse",
+    "MessageResponse",
+    # Source
+    "SourceType",
+    "SourceBase",
+    "SourceCreate",
+    "SourceUpdate",
+    "SourceResponse",
+    "SourceListResponse",
+    "SourceSummary",
+    # Rule
+    "RuleBase",
+    "RuleCreate",
+    "RuleUpdate",
+    "RuleResponse",
+    "RuleListItem",
+    "RuleListResponse",
+    "RuleSummary",
+    # Validation
+    "ValidationStatus",
+    "IssueSeverity",
+    "ValidationIssue",
+    "ValidationRunRequest",
+    "ValidationSummary",
+    "ValidationResponse",
+    "ValidationListItem",
+    "ValidationListResponse",
+    # Schema
+    "ColumnSchema",
+    "SchemaLearnRequest",
+    "SchemaUpdateRequest",
+    "SchemaResponse",
+    "SchemaSummary",
+    # Profile
+    "ColumnProfile",
+    "ProfileResponse",
+    # History
+    "TrendDataPoint",
+    "FailureFrequencyItem",
+    "RecentValidation",
+    "HistorySummary",
+    "HistoryResponse",
+    "HistoryQueryParams",
+    # Drift
+    "DriftCompareRequest",
+    "ColumnDriftResult",
+    "DriftResult",
+    "DriftSourceSummary",
+    "DriftComparisonResponse",
+    "DriftComparisonListItem",
+    "DriftComparisonListResponse",
+    # Schedule
+    "ScheduleBase",
+    "ScheduleCreate",
+    "ScheduleUpdate",
+    "ScheduleResponse",
+    "ScheduleListItem",
+    "ScheduleListResponse",
+    "ScheduleActionResponse",
+]