@weirdfingers/baseboards 0.2.0

package/templates/api/src/boards/logging.py

@@ -0,0 +1,195 @@
+"""
+Centralized logging configuration using structlog
+"""
+
+import base64
+import logging
+import secrets
+import sys
+import time
+from contextvars import ContextVar
+from typing import Any
+
+import structlog
+from fastapi import Request
+
+# Context variables for request tracking
+request_id_ctx: ContextVar[str | None] = ContextVar("request_id", default=None)
+user_id_ctx: ContextVar[str | None] = ContextVar("user_id", default=None)
+
+
+class RequestContextFilter:
+    """Add request context to log records."""
+
+    def __call__(self, logger: Any, method_name: str, event_dict: dict[str, Any]) -> dict[str, Any]:
+        """Add request context to the event dict."""
+        # Suppress unused parameter warnings - these are required by structlog interface
+        _ = logger, method_name
+
+        request_id = request_id_ctx.get()
+        user_id = user_id_ctx.get()
+
+        if request_id:
+            event_dict["request_id"] = request_id
+
+        if user_id:
+            event_dict["user_id"] = user_id
+
+        return event_dict
+
+
+def configure_logging(debug: bool = False) -> None:
+    """Configure structlog with appropriate processors and formatters.
+
+    Args:
+        debug: If True, use human-readable console output. If False, use JSON.
+    """
+
+    # Determine log level
+    log_level = logging.DEBUG if debug else logging.INFO
+
+    # Configure stdlib logging
+    logging.basicConfig(
+        level=log_level,
+        stream=sys.stdout,
+        format="%(message)s",
+        force=True,
+    )
+
+    # Configure structlog processors
+    processors = [
+        # Filter out keys with underscores (internal)
+        structlog.stdlib.filter_by_level,
+        # Add logger name to event dict
+        structlog.stdlib.add_logger_name,
+        # Add log level to event dict
+        structlog.stdlib.add_log_level,
+        # Add request context
+        RequestContextFilter(),
+        # Add timestamp
+        structlog.processors.TimeStamper(fmt="ISO", utc=True),
+        # Perform %-style string formatting
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        # Stack info processor (for exceptions)
+        structlog.processors.StackInfoRenderer(),
+        # Exception info processor
+        structlog.processors.format_exc_info,
+        # Unicode decoder processor
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    if debug:
+        # Development: human-readable console output
+        processors.append(structlog.dev.ConsoleRenderer(colors=True))
+    else:
+        # Production: JSON output
+        processors.append(structlog.processors.JSONRenderer())
+
+    # Configure structlog
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.stdlib.BoundLogger,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        context_class=dict,
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str) -> structlog.BoundLogger:
+    """Get a structlog logger instance.
+
+    Args:
+        name: Logger name (typically __name__)
+
+    Returns:
+        Configured structlog logger
+    """
+    return structlog.get_logger(name)
+
+
+def generate_request_id() -> str:
+    """Generate a compact, secure request ID with timestamp and randomness.
+
+    Uses microsecond precision timestamp with added randomness for security.
+    Format: 11-character base64 string (e.g., 'Ab3X9mF2xYz')
+
+    Provides high uniqueness probability while preventing predictable enumeration.
+    """
+    # Get microseconds since epoch (8 bytes when encoded as int64)
+    timestamp_us = int(time.time() * 1_000_000)
+
+    # Add 2 bytes of cryptographically secure randomness
+    random_bytes = secrets.token_bytes(2)
+
+    # Convert timestamp to bytes (8 bytes for int64) and combine with random bytes
+    timestamp_bytes = timestamp_us.to_bytes(8, byteorder="big")
+    combined_bytes = timestamp_bytes + random_bytes
+
+    # Encode as base64 and strip padding
+    b64 = base64.urlsafe_b64encode(combined_bytes).decode("ascii").rstrip("=")
+
+    return b64
+
+
+def set_request_context(request_id: str | None = None, user_id: str | None = None) -> None:
+    """Set request context variables.
+
+    Args:
+        request_id: Request ID to set (generates one if None)
+        user_id: User ID to set
+    """
+    if request_id is None:
+        request_id = generate_request_id()
+
+    request_id_ctx.set(request_id)
+    if user_id is not None:
+        user_id_ctx.set(user_id)
+
+
+def clear_request_context() -> None:
+    """Clear request context variables."""
+    request_id_ctx.set(None)
+    user_id_ctx.set(None)
+
+
+def get_request_id() -> str | None:
+    """Get the current request ID."""
+    return request_id_ctx.get()
+
+
+def get_user_id() -> str | None:
+    """Get the current user ID."""
+    return user_id_ctx.get()
+
+
+def extract_user_id_from_request(request: Request) -> str | None:
+    """Extract user ID from FastAPI request.
+
+    This should be customized based on your authentication implementation.
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        User ID if authenticated, None otherwise
+    """
+    # TODO: Implement based on your auth strategy
+    # Examples:
+    # - JWT token in Authorization header
+    # - Session data
+    # - Supabase auth token
+
+    # For now, look for a user ID in headers (customize as needed)
+    auth_header = request.headers.get("authorization")
+    if auth_header:
+        # This is a placeholder - implement actual token parsing
+        # For example, if using Bearer tokens:
+        # if auth_header.startswith("Bearer "):
+        #     token = auth_header[7:]
+        #     # Parse JWT token to extract user_id
+        #     return parsed_user_id
+
+        # For now, return None until auth is implemented
+        return None
+
+    return None

package/templates/api/src/boards/middleware.py

@@ -0,0 +1,339 @@
+"""
+Middleware for request context and logging
+"""
+
+import json
+import re
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from .config import settings
+from .logging import (
+    clear_request_context,
+    extract_user_id_from_request,
+    get_logger,
+    set_request_context,
+)
+
+logger = get_logger(__name__)
+
+
+def sanitize_query_params(params: dict[str, Any]) -> dict[str, Any]:
+    """Remove sensitive query parameters from logging.
+
+    Args:
+        params: Dictionary of query parameters
+
+    Returns:
+        Dictionary with sensitive parameters redacted
+    """
+    sensitive_keys = {
+        "password",
+        "token",
+        "api_key",
+        "secret",
+        "auth",
+        "authorization",
+        "access_token",
+        "refresh_token",
+        "key",
+        "private_key",
+        "jwt",
+        "session",
+        "session_id",
+        "cookie",
+        "credentials",
+    }
+
+    sanitized = {}
+    for key, value in params.items():
+        # Check if any sensitive keyword is in the parameter name (case insensitive)
+        if any(sensitive in key.lower() for sensitive in sensitive_keys):
+            sanitized[key] = "[REDACTED]"
+        else:
+            sanitized[key] = value
+
+    return sanitized
+
+
+# 1) Extend extractor to support GET /graphql as well
+async def extract_graphql_operation_name(request: Request) -> str | None:
+    if request.url.path != "/graphql":
+        return None
+
+    # Handle GET /graphql (operationName in query params, or parse from query)
+    if request.method == "GET":
+        params = dict(request.query_params)
+        op = params.get("operationName")
+        if isinstance(op, str) and op:
+            return op
+
+        q = params.get("query", "")
+        if not isinstance(q, str) or not q:
+            return None
+        if "__schema" in q or "IntrospectionQuery" in q:
+            return "__introspection"
+
+        match = re.search(r"\bquery\s+(\w+)", q) or re.search(r"\bmutation\s+(\w+)", q)
+        if match:
+            kind = "mutation:" if q.lstrip().startswith("mutation") else ""
+            return f"{kind}{match.group(1)}"
+        return "unnamed_operation"
+
+    # Existing POST /graphql logic
+    if request.method == "POST":
+        try:
+            body = await request.body()
+            if not body:
+                return None
+            data = json.loads(body)
+            op = data.get("operationName")
+            if isinstance(op, str) and op:
+                return op
+            q = data.get("query", "")
+            if not isinstance(q, str) or not q:
+                return None
+            if "__schema" in q or "IntrospectionQuery" in q:
+                return "__introspection"
+            m = re.search(r"\bquery\s+(\w+)", q) or re.search(r"\bmutation\s+(\w+)", q)
+            if m:
+                kind = "mutation:" if q.lstrip().startswith("mutation") else ""
+                return f"{kind}{m.group(1)}"
+            return "unnamed_operation"
+        except (json.JSONDecodeError, TypeError):
+            return None
+
+    return None
+
+
+class LoggingContextMiddleware(BaseHTTPMiddleware):
+    """Middleware to set logging context for each request."""
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process request and set logging context."""
+
+        # Extract user ID from request (implement based on your auth)
+        user_id = extract_user_id_from_request(request)
+
+        # Set request context
+        set_request_context(user_id=user_id)
+
+        try:
+            # Sanitize query parameters for logging
+            sanitized_params = None
+            if request.query_params:
+                sanitized_params = sanitize_query_params(dict(request.query_params))
+                # If hitting /graphql, never log raw GraphQL payload in query string
+                # Comment this out to see the raw GraphQL payload in the query string
+                if request.url.path == "/graphql" and isinstance(sanitized_params, dict):
+                    for k in ("query", "variables", "extensions"):
+                        if k in sanitized_params:
+                            sanitized_params[k] = "[REDACTED]"
+
+            # Extract GraphQL operation name if applicable
+            graphql_operation = await extract_graphql_operation_name(request)
+
+            # Log request start
+            log_data = {
+                "method": request.method,
+                "path": request.url.path,
+                "query_params": sanitized_params,
+                "user_agent": request.headers.get("user-agent"),
+                "remote_addr": request.client.host if request.client else None,
+            }
+
+            # Add GraphQL operation name if available
+            if graphql_operation:
+                log_data["graphql_operation"] = graphql_operation
+
+            logger.info("Request started", **log_data)
+
+            # Process request
+            response = await call_next(request)
+
+            # Log request completion
+            logger.info(
+                "Request completed",
+                status_code=response.status_code,
+                method=request.method,
+                path=request.url.path,
+                graphql_operation=graphql_operation,  # Include in completion log too
+            )
+
+            return response
+
+        except Exception as e:
+            # Log request error
+            logger.error(
+                "Request failed",
+                method=request.method,
+                path=request.url.path,
+                error=str(e),
+            )
+            raise
+
+        finally:
+            # Clear context
+            clear_request_context()
+
+
+class TenantRoutingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware for tenant-aware request routing and validation.
+
+    This middleware:
+    1. Validates X-Tenant headers in multi-tenant mode
+    2. Enforces tenant isolation rules
+    3. Sets up request context for tenant-scoped operations
+    4. Provides early tenant validation before auth processing
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process request with tenant routing and validation."""
+
+        # Extract tenant information from headers
+        x_tenant = request.headers.get("X-Tenant")
+
+        # Log incoming request with tenant info
+        logger.debug(
+            "Processing request with tenant context",
+            method=request.method,
+            path=request.url.path,
+            x_tenant=x_tenant,
+            multi_tenant_mode=settings.multi_tenant_mode,
+        )
+
+        # Validate tenant header in multi-tenant mode
+        if settings.multi_tenant_mode:
+            tenant_validation_result = await self._validate_tenant_header(x_tenant, request)
+            if tenant_validation_result is not None:
+                return tenant_validation_result
+
+        # Add tenant context to request state for downstream use
+        request.state.tenant_slug = x_tenant or settings.default_tenant_slug
+        request.state.multi_tenant_mode = settings.multi_tenant_mode
+
+        try:
+            response = await call_next(request)
+
+            # Add tenant information to response headers for debugging
+            if settings.debug:
+                response.headers["X-Tenant-Resolved"] = request.state.tenant_slug
+                if settings.multi_tenant_mode:
+                    response.headers["X-Multi-Tenant-Mode"] = "true"
+
+            return response
+
+        except Exception as e:
+            logger.error(
+                "Request processing failed",
+                error=str(e),
+                tenant_slug=getattr(request.state, "tenant_slug", "unknown"),
+                path=request.url.path,
+            )
+            raise
+
+    async def _validate_tenant_header(
+        self, x_tenant: str | None, request: Request
+    ) -> Response | None:
+        """
+        Validate X-Tenant header in multi-tenant mode.
+
+        Returns:
+            Response if validation fails (error response), None if validation passes
+        """
+        from fastapi.responses import JSONResponse
+
+        # In multi-tenant mode, some endpoints may require X-Tenant header
+        if self._requires_tenant_header(request):
+            if not x_tenant:
+                logger.warning(
+                    "Missing required X-Tenant header in multi-tenant mode",
+                    path=request.url.path,
+                    method=request.method,
+                )
+                return JSONResponse(
+                    status_code=400,
+                    content={
+                        "error": "Missing X-Tenant header",
+                        "detail": (
+                            "X-Tenant header is required in multi-tenant mode " "for this endpoint"
+                        ),
+                        "multi_tenant_mode": True,
+                    },
+                )
+
+        # Validate tenant slug format if provided
+        if x_tenant:
+            validation_error = self._validate_tenant_slug_format(x_tenant)
+            if validation_error:
+                logger.warning(
+                    "Invalid X-Tenant header format",
+                    x_tenant=x_tenant,
+                    error=validation_error,
+                )
+                return JSONResponse(
+                    status_code=400,
+                    content={
+                        "error": "Invalid X-Tenant header format",
+                        "detail": validation_error,
+                        "provided_tenant": x_tenant,
+                    },
+                )
+
+        return None  # Validation passed
+
+    def _requires_tenant_header(self, request: Request) -> bool:
+        """
+        Determine if the request requires an X-Tenant header.
+
+        In multi-tenant mode, most API endpoints require tenant specification,
+        except for certain system endpoints like health checks.
+        """
+        path = request.url.path
+
+        # System endpoints that don't require tenant specification
+        system_endpoints = {
+            "/health",
+            "/api/setup/status",
+            "/docs",
+            "/redoc",
+            "/openapi.json",
+        }
+
+        if path in system_endpoints:
+            return False
+
+        # Setup endpoints are special - they help create tenants
+        if path.startswith("/api/setup/"):
+            return False
+
+        # All other API endpoints require tenant in multi-tenant mode
+        if path.startswith("/api/") or path.startswith("/graphql"):
+            return True
+
+        return False
+
+    def _validate_tenant_slug_format(self, tenant_slug: str) -> str | None:
+        """
+        Validate tenant slug format.
+
+        Returns:
+            Error message if invalid, None if valid
+        """
+        if not tenant_slug:
+            return "Tenant slug cannot be empty"
+
+        if len(tenant_slug) > 255:
+            return "Tenant slug too long (max 255 characters)"
+
+        if not re.match(r"^[a-z0-9-]+$", tenant_slug):
+            return "Tenant slug must contain only lowercase letters, numbers, and hyphens"
+
+        if tenant_slug.startswith("-") or tenant_slug.endswith("-"):
+            return "Tenant slug cannot start or end with hyphen"
+
+        return None  # Valid

package/templates/api/src/boards/progress/__init__.py

@@ -0,0 +1,4 @@
+"""Progress publishing and models for generation jobs."""
+
+from .models import ArtifactInfo, ProgressUpdate  # noqa: F401
+from .publisher import ProgressPublisher  # noqa: F401

package/templates/api/src/boards/progress/models.py

@@ -0,0 +1,25 @@
+"""Pydantic models for progress updates."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ArtifactInfo(BaseModel):
+    url: str
+    type: str
+    metadata: dict = {}
+
+
+class ProgressUpdate(BaseModel):
+    job_id: str
+    status: str  # Use string to avoid tight coupling to GraphQL enums
+    progress: float
+    phase: Literal["queued", "initializing", "processing", "finalizing"]
+    message: str | None = None
+    estimated_completion: datetime | None = None
+    artifacts: list[ArtifactInfo] = []
+    timestamp: datetime = datetime.now(UTC)

package/templates/api/src/boards/progress/publisher.py

@@ -0,0 +1,64 @@
+"""Publisher for progress updates via Redis pub/sub with DB persistence."""
+
+from __future__ import annotations
+
+from ..config import Settings
+from ..database.connection import get_async_session
+from ..jobs import repository as jobs_repo
+from ..logging import get_logger
+from ..redis_pool import get_redis_client
+from .models import ProgressUpdate
+
+logger = get_logger(__name__)
+
+
+class ProgressPublisher:
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or Settings()
+        # Use the shared Redis connection pool
+        self._redis = get_redis_client()
+
+    async def publish_progress(self, job_id: str, update: ProgressUpdate) -> None:
+        """Publish progress update to Redis and persist to database."""
+        channel = f"job:{job_id}:progress"
+        await self._persist_update(job_id, update)
+        json_data = update.model_dump_json()
+        logger.info(
+            "Publishing progress update to Redis",
+            job_id=job_id,
+            channel=channel,
+            status=update.status,
+            progress=update.progress,
+            data_length=len(json_data),
+        )
+        await self._redis.publish(channel, json_data)
+        logger.debug("Progress update published successfully", job_id=job_id)
+
+    async def publish_only(self, job_id: str, update: ProgressUpdate) -> None:
+        """Publish progress update to Redis without persisting to database.
+
+        Use this when the database has already been updated separately,
+        e.g., after calling finalize_success in the repository.
+        """
+        channel = f"job:{job_id}:progress"
+        json_data = update.model_dump_json()
+        logger.info(
+            "Publishing progress update to Redis (no DB persist)",
+            job_id=job_id,
+            channel=channel,
+            status=update.status,
+            progress=update.progress,
+            data_length=len(json_data),
+        )
+        await self._redis.publish(channel, json_data)
+        logger.debug("Progress update published successfully", job_id=job_id)
+
+    async def _persist_update(self, job_id: str, update: ProgressUpdate) -> None:
+        async with get_async_session() as session:
+            await jobs_repo.update_progress(
+                session,
+                generation_id=job_id,
+                status=update.status,
+                progress=(update.progress * 100 if update.progress <= 1.0 else update.progress),
+                error_message=update.message if update.status == "failed" else None,
+            )