cuneus 0.2.1__py3-none-any.whl

cuneus/core/application.py

@@ -0,0 +1,230 @@
+"""
+cuneus - The wedge stone that locks the arch together.
+
+Lightweight lifespan management for FastAPI applications.
+"""
+
+from __future__ import annotations
+
+import logging
+import tomllib
+import uuid
+from contextlib import AsyncExitStack, asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncContextManager, AsyncIterator, Protocol, runtime_checkable
+
+import svcs
+from fastapi import FastAPI, Request
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.types import ASGIApp
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TOOL_NAME = "cuneus"
+
+
+def load_pyproject_config(
+    tool_name: str = DEFAULT_TOOL_NAME,
+    path: Path | None = None,
+) -> dict[str, Any]:
+    """Load configuration from pyproject.toml under [tool.{tool_name}]."""
+    if path is None:
+        path = Path.cwd()
+
+    for parent in [path, *path.parents]:
+        pyproject = parent / "pyproject.toml"
+        if pyproject.exists():
+            with open(pyproject, "rb") as f:
+                data = tomllib.load(f)
+            return data.get("tool", {}).get(tool_name, {})
+
+    return {}
+
+
+class Settings(BaseSettings):
+    """
+    Base settings that loads from:
+    1. pyproject.toml [tool.cuneus] (lowest priority)
+    2. .env file
+    3. Environment variables (highest priority)
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    app_name: str = "app"
+    app_module: str = "app.main:app"
+    debug: bool = False
+    version: str | None = None
+
+    # logging
+    log_level: str = "INFO"
+    log_json: bool = False
+    log_server_errors: bool = True
+
+    # health
+    health_enabled: bool = True
+    health_prefix: str = "/healthz"
+
+    @model_validator(mode="before")
+    @classmethod
+    def load_from_pyproject(cls, data: dict[str, Any]) -> dict[str, Any]:
+        pyproject_config = load_pyproject_config()
+        return {**pyproject_config, **data}
+
+
+@runtime_checkable
+class Extension(Protocol):
+    """
+    Protocol for extensions that hook into app lifecycle.
+
+    Extensions can:
+    - Register services with svcs
+    - Add routes via app.include_router()
+    - Add exception handlers via app.add_exception_handler()
+    - Return state to merge into lifespan state
+    """
+
+    def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncContextManager[dict[str, Any]]:
+        """
+        Async context manager for lifecycle.
+
+        - Enter: startup (register services, add routes, etc.)
+        - Yield: dict of state to merge into lifespan state
+        - Exit: shutdown (cleanup resources)
+        """
+        ...
+
+
+class BaseExtension:
+    """
+    Base class for extensions with explicit startup/shutdown hooks.
+
+    For simple extensions, override startup() and shutdown().
+    For full control, override register() directly.
+    """
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        """
+        Override to setup resources during app startup.
+
+        You can call app.include_router(), app.add_exception_handler(), etc.
+        Returns a dict of state to merge into lifespan state.
+        """
+        return {}
+
+    async def shutdown(self, app: FastAPI) -> None:
+        """Override to cleanup resources during app shutdown."""
+        pass
+
+    @asynccontextmanager
+    async def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Wraps startup/shutdown into async context manager."""
+        state = await self.startup(registry, app)
+        try:
+            yield state
+        finally:
+            await self.shutdown(app)
+
+
+def build_lifespan(settings: Settings, *extensions: Extension):
+    """
+    Create a lifespan context manager for FastAPI.
+
+    The returned lifespan has a `.registry` attribute for testing overrides.
+
+    Usage:
+        from cuneus import build_lifespan, Settings
+        from myapp.extensions import DatabaseExtension
+
+        settings = Settings()
+        lifespan = build_lifespan(
+            settings,
+            DatabaseExtension(settings),
+        )
+
+        app = FastAPI(lifespan=lifespan, title="My App")
+
+    Testing:
+        from myapp import app, lifespan
+
+        def test_with_mock_db(client):
+            mock_db = Mock(spec=Database)
+            lifespan.registry.register_value(Database, mock_db)
+            # ...
+    """
+
+    @svcs.fastapi.lifespan
+    @asynccontextmanager
+    async def lifespan(
+        app: FastAPI, registry: svcs.Registry
+    ) -> AsyncIterator[dict[str, Any]]:
+        async with AsyncExitStack() as stack:
+            state: dict[str, Any] = {"settings": settings}
+
+            for ext in extensions:
+                ext_state = await stack.enter_async_context(ext.register(registry, app))
+                if ext_state:
+                    if overlap := state.keys() & ext_state.keys():
+                        raise ValueError(f"Extension state key collision: {overlap}")
+                    state.update(ext_state)
+
+            yield state
+
+    return lifespan
+
+
+class RequestIDMiddleware:
+    """
+    Middleware that adds a unique request_id to each request.
+
+    Access via request.state.request_id
+    """
+
+    def __init__(self, app: ASGIApp, header_name: str = "X-Request-ID"):
+        self.app = app
+        self.header_name = header_name
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # Check for existing request ID in headers, or generate new one
+        headers = dict(scope.get("headers", []))
+        request_id = headers.get(
+            self.header_name.lower().encode(), str(uuid.uuid4())[:8].encode()
+        ).decode()
+
+        # Store in scope state
+        if "state" not in scope:
+            scope["state"] = {}
+        scope["state"]["request_id"] = request_id
+
+        # Add request ID to response headers
+        async def send_with_request_id(message):
+            if message["type"] == "http.response.start":
+                headers = list(message.get("headers", []))
+                headers.append((self.header_name.encode(), request_id.encode()))
+                message["headers"] = headers
+            await send(message)
+
+        await self.app(scope, receive, send_with_request_id)
+
+
+def get_settings(request: Request) -> Settings:
+    """Get settings from request state."""
+    return request.state.settings
+
+
+def get_request_id(request: Request) -> str:
+    """Get the request ID from request state."""
+    return request.state.request_id

cuneus/core/execptions.py

@@ -0,0 +1,214 @@
+"""
+Exception handling with consistent API responses.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+import svcs
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from cuneus.core.application import BaseExtension, Settings
+
+log = structlog.get_logger()
+
+
+class ErrorDetails(BaseModel):
+    status: int
+    code: str
+    message: str
+    request_id: str | None = None
+    details: Any = None
+
+
+class ErrorResponse(BaseModel):
+    error: ErrorDetails
+
+
+class AppException(Exception):
+    """
+    Base exception for application errors.
+
+    Subclass this for domain-specific errors.
+    """
+
+    status_code: int = 500
+    error_code: str = "internal_error"
+    message: str = "An unexpected error occurred"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        error_code: str | None = None,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message or self.message
+        self.error_code = error_code or self.error_code
+        self.status_code = status_code or self.status_code
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def to_response(self, request_id: str | None = None) -> ErrorResponse:
+        error_detail = ErrorDetails(
+            status=self.status_code,
+            code=self.error_code,
+            message=self.message,
+            request_id=request_id,
+            details=self.details,
+        )
+        return ErrorResponse(error=error_detail)
+
+
+# === Common HTTP Exceptions ===
+
+
+class BadRequest(AppException):
+    status_code = 400
+    error_code = "bad_request"
+    message = "Invalid request"
+
+
+class Unauthorized(AppException):
+    status_code = 401
+    error_code = "unauthorized"
+    message = "Authentication required"
+
+
+class Forbidden(AppException):
+    status_code = 403
+    error_code = "forbidden"
+    message = "Access denied"
+
+
+class NotFound(AppException):
+    status_code = 404
+    error_code = "not_found"
+    message = "Resource not found"
+
+
+class Conflict(AppException):
+    status_code = 409
+    error_code = "conflict"
+    message = "Resource conflict"
+
+
+class RateLimited(AppException):
+    status_code = 429
+    error_code = "rate_limited"
+    message = "Too many requests"
+
+    def __init__(self, retry_after: int | None = None, **kwargs):
+        super().__init__(**kwargs)
+        self.retry_after = retry_after
+
+
+class ServiceUnavailable(AppException):
+    status_code = 503
+    error_code = "service_unavailable"
+    message = "Service temporarily unavailable"
+
+
+# === Infrastructure Exceptions ===
+
+
+class DatabaseError(AppException):
+    status_code = 503
+    error_code = "database_error"
+    message = "Database operation failed"
+
+
+class RedisError(AppException):
+    status_code = 503
+    error_code = "cache_error"
+    message = "Cache operation failed"
+
+
+class ExternalServiceError(AppException):
+    status_code = 502
+    error_code = "external_service_error"
+    message = "External service request failed"
+
+
+def error_responses(*excptions: AppException) -> dict[int, dict[str, Any]]:
+    responses: dict[int, dict[str, Any]] = {}
+    for exception in excptions:
+        responses[exception.status_code] = {
+            "model": ErrorResponse,
+            "description": exception.message,
+        }
+    return responses
+
+
+class ExceptionExtension(BaseExtension):
+    """
+    Exception handling extension.
+
+    Catches AppException subclasses and converts to JSON responses.
+    Catches unexpected exceptions and returns generic 500s.
+
+    Usage:
+        from qtip import build_app
+        from qtip.core.exceptions import ExceptionExtension, ExceptionSettings
+
+        app = build_app(
+            settings,
+            extensions=[ExceptionExtension(settings)],
+        )
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        app.add_exception_handler(AppException, self._handle_app_exception)  # type: ignore[]
+        app.add_exception_handler(Exception, self._handle_unexpected_exception)
+        return {}
+
+    def _handle_app_exception(
+        self, request: Request, exc: AppException
+    ) -> JSONResponse:
+        if exc.status_code >= 500 and self.settings.log_server_errors:
+            log.exception("server_error", error_code=exc.error_code)
+        else:
+            log.warning("client_error", error_code=exc.error_code, message=exc.message)
+
+        response = exc.to_response(request.state.get("request_id", None))
+
+        headers = {}
+        if isinstance(exc, RateLimited) and exc.retry_after:
+            headers["Retry-After"] = str(exc.retry_after)
+
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=response.model_dump(exclude_none=True, mode="json"),
+            headers=headers,
+        )
+
+    def _handle_unexpected_exception(
+        self, request: Request, exc: Exception
+    ) -> JSONResponse:
+        log.exception("unexpected_error")
+
+        response: dict[str, Any] = {
+            "error": {
+                "code": "internal_error",
+                "message": "An unexpected error occurred",
+            }
+        }
+
+        if hasattr(request.state, "request_id"):
+            response["error"]["request_id"] = request.state.request_id
+
+        if self.settings.debug:
+            response["error"]["details"] = {
+                "exception": type(exc).__name__,
+                "message": str(exc),
+            }
+
+        return JSONResponse(status_code=500, content=response)

cuneus/ext/health.py

@@ -0,0 +1,128 @@
+"""
+Health check endpoints using svcs ping capabilities.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+import structlog
+import svcs
+from fastapi import APIRouter, FastAPI, Request
+from pydantic import BaseModel
+
+from cuneus.core.application import BaseExtension, Settings
+
+log = structlog.get_logger()
+
+
+class HealthStatus(str, Enum):
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+
+
+class ServiceHealth(BaseModel):
+    name: str
+    status: HealthStatus
+    message: str | None = None
+
+
+class HealthResponse(BaseModel):
+    status: HealthStatus
+    version: str | None = None
+    services: list[ServiceHealth] = []
+
+
+class HealthExtension(BaseExtension):
+    """
+    Health check extension using svcs pings.
+
+    Adds:
+        GET /health       - Full health check using svcs pings
+        GET /health/live  - Liveness probe (always 200)
+        GET /health/ready - Readiness probe (503 if unhealthy)
+
+    Usage:
+        from qtip import build_app
+        from qtip.ext.health import HealthExtension, HealthSettings
+
+        app = build_app(
+            settings,
+            extensions=[HealthExtension(settings)],
+        )
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        if not self.settings.health_enabled:
+            return {}
+
+        router = APIRouter(prefix=self.settings.health_prefix, tags=["health"])
+        version = self.settings.version
+
+        @router.get("", response_model=HealthResponse)
+        async def health(services: svcs.fastapi.DepContainer) -> HealthResponse:
+            """Full health check - pings all registered services."""
+            pings = services.get_pings()
+
+            _services: list[ServiceHealth] = []
+            overall_healthy = True
+
+            for ping in pings:
+                try:
+                    await ping.aping()
+                    _services.append(
+                        ServiceHealth(
+                            name=ping.name,
+                            status=HealthStatus.HEALTHY,
+                        )
+                    )
+                except Exception as e:
+                    log.warning("health_check_failed", service=ping.name, error=str(e))
+                    _services.append(
+                        ServiceHealth(
+                            name=ping.name,
+                            status=HealthStatus.UNHEALTHY,
+                            message=str(e),
+                        )
+                    )
+                    overall_healthy = False
+
+            return HealthResponse(
+                status=(
+                    HealthStatus.HEALTHY if overall_healthy else HealthStatus.UNHEALTHY
+                ),
+                version=version,
+                services=_services,
+            )
+
+        @router.get("/live")
+        async def liveness() -> dict[str, str]:
+            """Liveness probe - is the process running?"""
+            return {"status": "ok"}
+
+        @router.get("/ready")
+        async def readiness(services: svcs.fastapi.DepContainer) -> dict[str, str]:
+            """Readiness probe - can we serve traffic?"""
+            from fastapi import HTTPException
+
+            pings = services.get_pings()
+
+            for ping in pings:
+                try:
+                    await ping.aping()
+                except Exception as e:
+                    log.warning(
+                        "readiness_check_failed", service=ping.name, error=str(e)
+                    )
+                    raise HTTPException(
+                        status_code=503, detail=f"{ping.name} unhealthy"
+                    )
+
+            return {"status": "ok"}
+
+        app.include_router(router)
+        return {}