cuneus 0.2.6__py3-none-any.whl

cuneus/__init__.py

@@ -0,0 +1,59 @@
+"""
+qtip - A wrapper for FastAPI applications, like the artist.
+
+Example:
+    from qtip import Application, Settings
+    from qtip.ext.database import DatabaseExtension
+
+    class AppSettings(Settings):
+        database_url: str
+
+    settings = AppSettings()
+    app = Application(settings)
+    app.add_extension(DatabaseExtension(settings))
+
+    fastapi_app = app.build()
+"""
+
+from .core.application import build_app
+from .core.execptions import (
+    AppException,
+    BadRequest,
+    Unauthorized,
+    Forbidden,
+    NotFound,
+    Conflict,
+    RateLimited,
+    ServiceUnavailable,
+    DatabaseError,
+    RedisError,
+    ExternalServiceError,
+    ExceptionExtension,
+)
+from .core.extensions import BaseExtension, Extension
+from .core.settings import Settings
+
+__version__ = "0.2.1"
+__all__ = [
+    # Core exported functions
+    # Application
+    "build_app",
+    # Extension
+    "BaseExtension",
+    "Extension",
+    # Settings
+    "Settings",
+    # Exceptions
+    "AppException",
+    "BadRequest",
+    "Unauthorized",
+    "Forbidden",
+    "NotFound",
+    "Conflict",
+    "RateLimited",
+    "ServiceUnavailable",
+    "DatabaseError",
+    "RedisError",
+    "ExternalServiceError",
+    "ExceptionExtension",
+]

cuneus/cli.py

@@ -0,0 +1,143 @@
+"""Base CLI that cuneus provides."""
+
+from pathlib import Path
+
+import importlib
+import sys
+from typing import Any, cast
+
+import click
+
+from .core.settings import Settings
+
+
+def import_from_string(import_str: str) -> Any:
+    """Import an object from a module:attribute string."""
+    # Ensure cwd is in path for local imports
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+
+    module_path, _, attr = import_str.partition(":")
+    if not attr:
+        raise ValueError(
+            f"module_path missing function {import_str} expecting 'module.path:name'"
+        )
+
+    module = importlib.import_module(module_path)
+    return getattr(module, attr)
+
+
+def get_user_cli() -> click.Group | None:
+    """Attempt to load user's CLI from config."""
+    config = Settings()
+
+    try:
+        return cast(click.Group, import_from_string(config.cli_module))
+    except (ImportError, AttributeError) as e:
+        click.echo(
+            f"Warning: Could not load CLI from {config.cli_module}: {e}", err=True
+        )
+
+    return None
+
+
+@click.group()
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """Cuneus CLI - FastAPI application framework."""
+    ctx.ensure_object(dict)
+
+
+@cli.command()
+@click.option("--host", default="0.0.0.0", help="Bind host")
+@click.option("--port", default=8000, type=int, help="Bind port")
+def dev(host: str, port: int) -> None:
+    """Run the application server."""
+    import uvicorn
+
+    config = Settings()
+
+    uvicorn.run(
+        config.app_module,
+        host=host,
+        port=port,
+        reload=True,
+        log_config=None,
+        server_header=False,
+    )
+
+
+@cli.command()
+@click.option("--host", default="0.0.0.0", help="Bind host")
+@click.option("--port", default=8000, type=int, help="Bind port")
+@click.option("--workers", default=1, type=int, help="Number of workers")
+def prod(host: str, port: int, workers: int) -> None:
+    """Run the application server."""
+    import uvicorn
+
+    config = Settings()
+
+    uvicorn.run(
+        config.app_module,
+        host=host,
+        port=port,
+        workers=workers,
+        log_config=None,
+        server_header=False,
+    )
+
+
+@cli.command()
+def routes() -> None:
+    """List all registered routes."""
+    config = Settings()
+    app = import_from_string(config.app_module)
+
+    for route in app.routes:
+        if hasattr(route, "methods"):
+            methods = ",".join(route.methods - {"HEAD", "OPTIONS"})
+            click.echo(f"{methods:8} {route.path}")
+
+
+class CuneusCLI(click.Group):
+    """Merges base cuneus commands with user's app CLI."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._user_cli: click.Group | None = None
+        self._user_cli_loaded = False
+
+        # Register base commands directly
+        self.add_command(dev)
+        self.add_command(prod)
+        self.add_command(routes)
+
+    @property
+    def user_cli(self) -> click.Group | None:
+        if not self._user_cli_loaded:
+            self._user_cli = get_user_cli()
+            self._user_cli_loaded = True
+        return self._user_cli
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        commands = set(super().list_commands(ctx))
+        if self.user_cli:
+            commands.update(self.user_cli.list_commands(ctx))
+        return sorted(commands)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        # User CLI takes priority
+        if self.user_cli:
+            cmd = self.user_cli.get_command(ctx, cmd_name)
+            if cmd:
+                return cmd
+        return super().get_command(ctx, cmd_name)
+
+
+# This is the actual entry point
+main = CuneusCLI(help="Cuneus CLI - FastAPI application framework")
+
+
+if __name__ == "__main__":
+    main()

cuneus/core/application.py

@@ -0,0 +1,140 @@
+"""
+cuneus - The wedge stone that locks the arch together.
+
+Lightweight lifespan management for FastAPI applications.
+"""
+
+from __future__ import annotations
+
+import inspect
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import Any, AsyncIterator, Callable
+
+import click
+import structlog
+import svcs
+from fastapi import FastAPI
+from starlette.middleware import Middleware
+
+from .settings import Settings
+from .execptions import ExceptionExtension
+from .logging import LoggingExtension
+from .extensions import Extension, HasCLI, HasMiddleware
+from ..ext.health import HealthExtension
+
+logger = structlog.stdlib.get_logger("cuneus")
+
+type ExtensionInput = Extension | Callable[..., Extension]
+
+DEFAULT_EXTENSIONS = (
+    LoggingExtension,
+    HealthExtension,
+    ExceptionExtension,
+)
+
+
+def _instantiate_extension(
+    ext: ExtensionInput, settings: Settings | None = None
+) -> Extension:
+    if isinstance(ext, type) or callable(ext):
+        sig = inspect.signature(ext)
+
+        # Check if it accepts a 'settings' parameter
+        if "settings" in sig.parameters:
+            return ext(settings=settings)
+
+        # Check if it accepts **kwargs
+        has_var_keyword = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+        if has_var_keyword:
+            return ext(settings=settings)
+
+        return ext()
+    return ext
+
+
+def build_app(
+    *extensions: ExtensionInput,
+    settings: Settings | None = None,
+    include_defaults: bool = True,
+    **fastapi_kwargs: Any,
+) -> tuple[FastAPI, click.Group]:
+    """
+    Build a FastAPI with extensions preconfigured.
+
+    The returned lifespan has a `.registry` attribute for testing overrides.
+
+    Usage:
+        from cuneus import build_app, Settings, SettingsExtension
+        from myapp.extensions import DatabaseExtension
+
+        settings = Settings()
+        app, cli = build_app(
+            SettingsExtension(settings),
+            DatabaseExtension(settings),
+            title="Args are passed to FastAPI",
+        )
+
+        __all__ = ["app", "cli"]
+
+    Testing:
+        from myapp import app, lifespan
+
+        def test_with_mock_db(client):
+            mock_db = Mock(spec=Database)
+            lifespan.registry.register_value(Database, mock_db)
+    """
+    if "lifespan" in fastapi_kwargs:
+        raise AttributeError("cannot set lifespan with build_app")
+    if "middleware" in fastapi_kwargs:
+        raise AttributeError("cannot set middleware with build_app")
+
+    settings = settings or Settings()
+
+    if include_defaults:
+        # Allow users to override a default extension
+        user_types = {type(ext) for ext in extensions}
+        defaults = [ext for ext in DEFAULT_EXTENSIONS if type(ext) not in user_types]
+        all_inputs = (*defaults, *extensions)
+    else:
+        all_inputs = extensions
+
+    all_extensions = [_instantiate_extension(ext, settings) for ext in all_inputs]
+
+    @click.group()
+    @click.pass_context
+    def app_cli(ctx: click.Context) -> None:
+        """Application CLI."""
+        ctx.ensure_object(dict)
+
+    @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] = {}
+
+            for ext in all_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
+
+    # Parse extensions for middleware and cli commands
+    middleware: list[Middleware] = []
+
+    for ext in all_extensions:
+        if isinstance(ext, HasMiddleware):
+            logger.debug(f"Loading middleware from {ext.__class__.__name__}")
+            middleware.extend(ext.middleware())
+        if isinstance(ext, HasCLI):
+            logger.debug(f"Adding cli commands from {ext.__class__.__name__}")
+            ext.register_cli(app_cli)
+
+    app = FastAPI(lifespan=lifespan, middleware=middleware, **fastapi_kwargs)
+    return app, app_cli

cuneus/core/execptions.py

@@ -0,0 +1,215 @@
+"""
+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 .extensions import BaseExtension
+from .settings import 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: Any) -> None:
+        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 = None) -> None:
+        self.settings = settings or Settings()
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        app.add_exception_handler(AppException, self._handle_app_exception)  # type: ignore[arg-type]
+        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/core/extensions.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import logging
+
+from contextlib import asynccontextmanager
+from typing import (
+    Any,
+    AsyncContextManager,
+    AsyncIterator,
+    Protocol,
+    runtime_checkable,
+)
+
+import svcs
+from click import Group
+from fastapi import FastAPI
+from starlette.middleware import Middleware
+
+from .settings import Settings
+
+logger = logging.getLogger(__name__)
+
+
+@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)
+        """
+        ...
+
+
+@runtime_checkable
+class HasMiddleware(Protocol):
+    """Extension that provides middleware."""
+
+    def middleware(self) -> list[Middleware]: ...
+
+
+@runtime_checkable
+class HasCLI(Protocol):
+    """Extension that provides CLI commands."""
+
+    def register_cli(self, cli_group: Group) -> None: ...
+
+
+class BaseExtension:
+    """
+    Base class for extensions with explicit startup/shutdown hooks.
+
+    For simple extensions, override startup() and shutdown().
+    For full control, override register() directly.
+    """
+
+    def __init__(self, settings: Settings | None = None):
+        self.settings = settings or Settings()
+
+    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)

cuneus/core/logging.py

@@ -0,0 +1,230 @@
+"""
+Structured logging with structlog and request context.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+import logging
+import time
+import uuid
+from typing import Any, Awaitable, Callable, MutableMapping
+
+import structlog
+import svcs
+from fastapi import FastAPI, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.middleware import Middleware
+from starlette.types import ASGIApp, Scope, Send, Receive
+
+from .extensions import BaseExtension
+from .settings import Settings
+
+logger = structlog.stdlib.get_logger("cuneus")
+
+
+def configure_structlog(settings: Settings | None = None) -> None:
+    log_settings = settings or Settings()
+
+    # Shared processors
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer(colors=True)
+    if log_settings.log_json:
+        renderer = structlog.processors.JSONRenderer()
+
+    # Configure structlog
+    structlog.configure(
+        processors=shared_processors
+        + [
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    # Create formatter for stdlib
+    formatter = structlog.stdlib.ProcessorFormatter(
+        foreign_pre_chain=shared_processors,
+        processors=[
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            renderer,
+        ],
+    )
+
+    # Configure root logger
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+
+    root_logger = logging.getLogger()
+    root_logger.handlers.clear()
+    root_logger.addHandler(handler)
+    root_logger.setLevel(log_settings.log_level.upper())
+
+    # Quiet noisy loggers
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+
+
+class LoggingExtension(BaseExtension):
+    """
+    Structured logging extension using structlog.
+
+    Integrates with stdlib logging so uvicorn and other libraries
+    also output through structlog.
+
+    Usage:
+        from qtip import build_app
+        from qtip.middleware.logging import LoggingExtension, LoggingSettings
+
+        app = build_app(
+            settings,
+            extensions=[LoggingExtension(settings)],
+        )
+    """
+
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or Settings()
+        configure_structlog(settings)
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        # app.add_middleware(RequestLoggingMiddleware)
+        return {}
+
+    def middleware(self) -> list[Middleware]:
+        return [
+            Middleware(
+                LoggingMiddleware,
+                header_name=self.settings.request_id_header,
+            ),
+        ]
+
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that:
+    - Generates request_id
+    - Binds it to structlog context
+    - Logs request start/end
+    - Adds request_id to response headers
+    """
+
+    def __init__(self, app: ASGIApp, header_name: str = "X-Request-ID") -> None:
+        self.header_name = header_name
+        super().__init__(app)
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[..., Awaitable[Response]]
+    ) -> Response:
+        path = request.url.path
+        # Exclude health routes as these are just noise
+        # TODO(rmyers): make this configurable
+        if path.startswith("/health"):
+            return await call_next(request)
+
+        request_id = request.headers.get(self.header_name) or str(uuid.uuid4())[:8]
+
+        structlog.contextvars.clear_contextvars()
+        structlog.contextvars.bind_contextvars(
+            request_id=request_id,
+            method=request.method,
+            path=path,
+        )
+
+        request.state.request_id = request_id
+
+        log = structlog.stdlib.get_logger("cuneus")
+        start_time = time.perf_counter()
+
+        try:
+            response = await call_next(request)
+
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            log.info(
+                f"{request.method} {request.url.path} {response.status_code}",
+                status_code=response.status_code,
+                duration_ms=round(duration_ms, 2),
+            )
+
+            response.headers[self.header_name] = request_id
+            return response
+
+        except Exception:
+            raise
+        finally:
+            structlog.contextvars.clear_contextvars()
+
+
+# Used by httpx for request ID propagation
+request_id_ctx: ContextVar[str | None] = ContextVar("request_id", default=None)
+
+
+class RequestIDMiddleware:
+    def __init__(self, app: ASGIApp, header_name: str = "X-Request-ID") -> None:
+        self.app = app
+        self.header_name = header_name
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = dict(scope.get("headers", []))
+        request_id = headers.get(
+            self.header_name.lower().encode(), str(uuid.uuid4())[:8].encode()
+        ).decode()
+
+        if "state" not in scope:
+            scope["state"] = {}
+        scope["state"]["request_id"] = request_id
+
+        # Set contextvar for use in HTTP clients
+        token = request_id_ctx.set(request_id)
+
+        async def send_with_request_id(message: MutableMapping[str, Any]) -> None:
+            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)
+
+        try:
+            await self.app(scope, receive, send_with_request_id)
+        finally:
+            request_id_ctx.reset(token)
+
+
+# === Public API ===
+
+
+def get_logger(**initial_context: Any) -> structlog.stdlib.BoundLogger:
+    """
+    Get a logger with optional initial context.
+
+    Usage:
+        log = get_logger()
+        log.info("user logged in", user_id=123)
+    """
+    log = structlog.stdlib.get_logger()
+    if initial_context:
+        log = log.bind(**initial_context)
+    return log
+
+
+def bind_contextvars(**context: Any) -> None:
+    """
+    Bind additional context that will appear in all subsequent logs.
+    """
+    structlog.contextvars.bind_contextvars(**context)
+
+
+def get_request_id(request: Request) -> str:
+    """Get request ID from request state."""
+    return getattr(request.state, "request_id", "-")

cuneus/core/settings.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import logging
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    PyprojectTomlConfigSettingsSource,
+    SettingsConfigDict,
+)
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TOOL_NAME = "cuneus"
+
+
+class CuneusBaseSettings(BaseSettings):
+    """
+    Base settings that loads from:
+    1. pyproject.toml [tool.cuneus] (lowest priority)
+    2. .env file
+    3. Environment variables (highest priority)
+    """
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            init_settings,
+            PyprojectTomlConfigSettingsSource(settings_cls),
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+
+class Settings(CuneusBaseSettings):
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="allow",
+        pyproject_toml_depth=2,
+        pyproject_toml_table_header=("tool", DEFAULT_TOOL_NAME),
+    )
+
+    app_name: str = "app"
+    app_module: str = "app.main:app"
+    cli_module: str = "app.main:cli"
+    debug: bool = False
+    version: str | None = None
+
+    # logging
+    log_level: str = "INFO"
+    log_json: bool = False
+    log_server_errors: bool = True
+    request_id_header: str = "X-Request-ID"
+
+    # health
+    health_enabled: bool = True
+    health_prefix: str = "/healthz"

cuneus/ext/health.py

@@ -0,0 +1,129 @@
+"""
+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
+from pydantic import BaseModel
+
+from ..core.extensions import BaseExtension
+from ..core.settings import 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 = None) -> None:
+        self.settings = settings or 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 {}

cuneus-0.2.6.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: cuneus
+Version: 0.2.6
+Summary: ASGI application wrapper
+Project-URL: Homepage, https://github.com/rmyers/cuneus
+Project-URL: Documentation, https://github.com/rmyers/cuneus#readme
+Project-URL: Repository, https://github.com/rmyers/cuneus
+Author-email: Robert Myers <robert@julython.org>
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: svcs>=24.1.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: all
+Requires-Dist: alembic>=1.13.0; extra == 'all'
+Requires-Dist: asyncpg>=0.29.0; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
+Provides-Extra: database
+Requires-Dist: alembic>=1.13.0; extra == 'database'
+Requires-Dist: asyncpg>=0.29.0; extra == 'database'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'database'
+Provides-Extra: dev
+Requires-Dist: alembic>=1.13.0; extra == 'dev'
+Requires-Dist: asgi-lifespan>=2.1.0; extra == 'dev'
+Requires-Dist: asyncpg>=0.29.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# cuneus
+
+> _The wedge stone that locks the arch together_
+
+**cuneus** is a lightweight lifespan manager for FastAPI applications. It provides a simple pattern for composing extensions that handle startup/shutdown and service registration.
+
+The name comes from Roman architecture: a _cuneus_ is the wedge-shaped stone in a Roman arch. Each stone is simple on its own, but together they lock under pressure to create structures that have stood for millennia—no rebar required.
+
+## Installation
+
+```bash
+uv add cuneus
+```
+
+or
+
+```bash
+pip install cuneus
+```
+
+## Quick Start
+
+```python
+# app/main.py
+from fastapi import FastAPI
+from cuneus import build_app, Settings
+
+from myapp.extensions import DatabaseExtension
+
+class MyAppSettings(Settings):
+    my_mood: str = "extatic"
+
+app, cli = build_app(
+    DatabaseExtension,
+    settings=MyAppSettings(),
+)
+
+app.include_router(my_router)
+
+__all__ = ["app", "cli"]
+```
+
+That's it. Extensions handle their lifecycle, registration, and middleware.
+
+## Creating Extensions
+
+Use `BaseExtension` for simple cases:
+
+```python
+from cuneus import BaseExtension
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncEngine
+import svcs
+
+class DatabaseExtension(BaseExtension):
+    def __init__(self, settings):
+        self.settings = settings
+        self.engine: AsyncEngine | None = None
+
+    async def startup(self, registry: svcs.Registry, app: FastAPI) -> dict[str, Any]:
+        self.engine = create_async_engine(self.settings.database_url)
+
+        # Register with svcs for dependency injection
+        registry.register_value(AsyncEngine, self.engine)
+
+        # Add routes
+        app.include_router(health_router, prefix="/health")
+
+        # Add exception handlers
+        app.add_exception_handler(DBError, self.handle_db_error)
+
+        # Return state (accessible via request.state.db)
+        return {"db": self.engine}
+
+    async def shutdown(self, app: FastAPI) -> None:
+        if self.engine:
+            await self.engine.dispose()
+
+    def middleware(self) -> list[Middleware]:
+        return [Middleware(DatabaseLoggingMiddleware, level=INFO)]
+
+    def register_cli(self, app_cli: click.Group) -> None:
+        @app_cli.command()
+        @click.option("--workers", default=1, type=int, help="Number of workers")
+        def blow_up_db(workers: int): ...
+```
+
+For full control, override `register()` directly:
+
+```python
+from contextlib import asynccontextmanager
+
+class RedisExtension(BaseExtension):
+    def __init__(self, settings):
+        self.settings = settings
+
+    @asynccontextmanager
+    async def register(self, registry: svcs.Registry, app: FastAPI):
+        redis = await aioredis.from_url(self.settings.redis_url)
+        registry.register_value(Redis, redis)
+
+        try:
+            yield {"redis": redis}
+        finally:
+            await redis.close()
+```
+
+## Testing
+
+The lifespan exposes a `.registry` attribute for test overrides:
+
+```python
+# test_app.py
+from unittest.mock import Mock
+from starlette.testclient import TestClient
+from myapp import app, lifespan, Database
+
+def test_db_error_handling():
+    with TestClient(app) as client:
+        # Override after app startup
+        mock_db = Mock(spec=Database)
+        mock_db.get_user.side_effect = Exception("boom")
+        lifespan.registry.register_value(Database, mock_db)
+
+        resp = client.get("/users/42")
+        assert resp.status_code == 500
+```
+
+## Settings
+
+cuneus includes a base `Settings` class that loads from multiple sources:
+
+```python
+from cuneus import Settings
+
+class AppSettings(Settings):
+    database_url: str = "sqlite+aiosqlite:///./app.db"
+    redis_url: str = "redis://localhost"
+
+    model_config = SettingsConfigDict(env_prefix="APP_")
+```
+
+Load priority (highest wins):
+
+1. Environment variables
+2. `.env` file
+3. `pyproject.toml` under `[tool.cuneus]`
+
+## API Reference
+
+### `build_lifespan(settings, *extensions)`
+
+Creates a lifespan context manager for FastAPI.
+
+- `settings`: Your settings instance (subclass of `Settings`)
+- `*extensions`: Extension instances to register
+
+Returns a lifespan with a `.registry` attribute for testing.
+
+### `BaseExtension`
+
+Base class with `startup()` and `shutdown()` hooks:
+
+- `startup(registry, app) -> dict[str, Any]`: Setup resources, return state
+- `shutdown(app) -> None`: Cleanup resources
+- `middleware() -> list[Middleware]`: Optional middleware to configure
+- `register_cli(group) -> None`: Optional hook to add click commands
+
+### `Extension` Protocol
+
+For full control, implement the protocol directly:
+
+```python
+def register(self, registry: svcs.Registry, app: FastAPI) -> AsyncContextManager[dict[str, Any]]
+```
+
+### Accessors
+
+- `aget(request, *types)` - Async get services from svcs
+- `get(request, *types)` - Sync get services from svcs
+- `get_settings(request)` - Get settings from request state
+- `get_request_id(request)` - Get request ID from request state
+
+## Why cuneus?
+
+- **Simple** — one function, `build_app()`, does what you need
+- **Testable** — registry exposed via `lifespan.registry`
+- **Composable** — extensions are just async context managers
+- **Built on svcs** — proper dependency injection, not global state
+
+## License
+
+MIT

cuneus-0.2.6.dist-info/RECORD

@@ -0,0 +1,15 @@
+cuneus/__init__.py,sha256=JJ3nZ4757GU9KKuurxP1FfJSdSVrcO-xaorLFSvUJ5E,1211
+cuneus/cli.py,sha256=EYrQBBrBJVibGVGjrAgkJ5S4YAukub16HHkm-GaE4UY,3823
+cuneus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/core/application.py,sha256=5nHe3y8FNV1-IKVcdx0Agnoy73xAcdUGjlEzLVNF7tA,4279
+cuneus/core/execptions.py,sha256=beQE3gD-14BUK4Se6yE2J2U92xgr0yarVmVeibkudxs,5753
+cuneus/core/extensions.py,sha256=qqBnAD_wN6wTTun7C2hfVqxHhA3WgScNSrgRTMsYa04,2515
+cuneus/core/logging.py,sha256=m9qRXAJ4uqcT-NbLn1W3SpSY8DystRRpH9N8jENcyX4,6945
+cuneus/core/settings.py,sha256=PaYXQ_ubeSt3AFpxNNErii-h1_ehHYPrajFWRT42mTI,1703
+cuneus/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/ext/health.py,sha256=5dWVVEPFL1tWFBhQwZv8C-IvZRzg28V-4sk_g1jJ0vc,3854
+cuneus-0.2.6.dist-info/METADATA,sha256=Px89iKewk0sRhpZmde9snrTzuMsNkaID7NDU4XHatm8,6794
+cuneus-0.2.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cuneus-0.2.6.dist-info/entry_points.txt,sha256=tzPgom-_UkpP_uLKv3V_XyoIsKg84FBAc9ddjYl0W0Y,43
+cuneus-0.2.6.dist-info/RECORD,,

cuneus-0.2.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cuneus-0.2.6.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cuneus = cuneus.cli:main