cuneus 0.2.8__py3-none-any.whl → 0.2.10__py3-none-any.whl

cuneus/cli.py

@@ -1,118 +1,30 @@
-"""Base CLI that cuneus provides."""
+"""Cuneus CLI entry point."""
 
-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)
-
+from .core.settings import Settings, ensure_project_in_path
+from .utils import import_from_string
 
-def get_user_cli() -> click.Group | None:
-    """Attempt to load user's CLI from config."""
-    config = Settings()
 
+def get_user_cli(config: Settings = Settings()) -> click.Group | None:
+    """Load CLI from config."""
     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:  # pragma: no cover
-    """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"):  # pragma: no branch
-            methods = ",".join(route.methods - {"HEAD", "OPTIONS"})
-            click.echo(f"{methods:8} {route.path}")
+        click.echo(f"Warning: Could not load CLI from {config.cli_module}: {e}", err=True)
+        return None
 
 
 class CuneusCLI(click.Group):
-    """Merges base cuneus commands with user's app CLI."""
+    """Delegates to the app's CLI from config."""
 
     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:
@@ -121,21 +33,17 @@ class CuneusCLI(click.Group):
         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)
+            return self.user_cli.list_commands(ctx)
+        return []
 
     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)
+            return self.user_cli.get_command(ctx, cmd_name)
+        return None
 
 
-# This is the actual entry point
+ensure_project_in_path()
 main = CuneusCLI(help="Cuneus CLI - FastAPI application framework")
 
 

cuneus/core/application.py

@@ -19,8 +19,9 @@ from starlette.middleware import Middleware
 from .settings import Settings
 from .exceptions import ExceptionExtension
 from .logging import LoggingExtension
-from .extensions import Extension, HasCLI, HasExceptionHandler, HasMiddleware
+from .extensions import Extension, HasCLI, HasExceptionHandler, HasMiddleware, HasRoutes
 from ..ext.health import HealthExtension
+from ..ext.server import ServerExtension
 
 logger = structlog.stdlib.get_logger("cuneus")
 
@@ -30,6 +31,7 @@ DEFAULTS = (
     LoggingExtension,
     HealthExtension,
     ExceptionExtension,
+    ServerExtension,
 )
 
 
@@ -39,9 +41,7 @@ class ExtensionConflictError(Exception):
     pass
 
 
-def _instantiate_extension(
-    ext: ExtensionInput, settings: Settings | None = None
-) -> Extension:
+def _instantiate_extension(ext: ExtensionInput, settings: Settings | None = None) -> Extension:
     if isinstance(ext, type) or callable(ext):
         try:
             return ext(settings=settings)
@@ -56,7 +56,7 @@ def build_app(
     settings: Settings | None = None,
     include_defaults: bool = True,
     **fastapi_kwargs: Any,
-) -> tuple[FastAPI, click.Group]:
+) -> tuple[FastAPI, click.Group, svcs.fastapi.lifespan]:
     """
     Build a FastAPI with extensions preconfigured.
 
@@ -93,17 +93,9 @@ def build_app(
 
     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 def lifespan(app: FastAPI, registry: svcs.Registry) -> AsyncIterator[dict[str, Any]]:
         async with AsyncExitStack() as stack:
             state: dict[str, Any] = {}
 
@@ -121,6 +113,7 @@ def build_app(
 
     # Parse extensions for middleware and cli commands
     middleware: list[Middleware] = []
+    app_cli = click.Group()
 
     for ext in all_extensions:
         ext_name = ext.__class__.__name__
@@ -139,5 +132,8 @@ def build_app(
         if isinstance(ext, HasExceptionHandler):
             logger.debug(f"Loading exception handlers from {ext_name}")
             ext.add_exception_handler(app)
+        if isinstance(ext, HasRoutes):
+            logger.debug(f"Loading routes from {ext_name}")
+            ext.add_routes(app)
 
-    return app, app_cli
+    return app, app_cli, lifespan

cuneus/core/exceptions.py

@@ -160,9 +160,7 @@ class ExceptionExtension(BaseExtension):
         app.add_exception_handler(AppException, self._handle_app_exception)  # type: ignore[arg-type]
         app.add_exception_handler(Exception, self._handle_unexpected_exception)
 
-    def _handle_app_exception(
-        self, request: Request, exc: AppException
-    ) -> JSONResponse:
+    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:
@@ -180,9 +178,7 @@ class ExceptionExtension(BaseExtension):
             headers=headers,
         )
 
-    def _handle_unexpected_exception(
-        self, request: Request, exc: Exception
-    ) -> JSONResponse:
+    def _handle_unexpected_exception(self, request: Request, exc: Exception) -> JSONResponse:
         log.exception("unexpected_error", exc_info=exc)
         response: dict[str, Any] = {
             "error": {

cuneus/core/extensions.py

@@ -67,6 +67,13 @@ class HasExceptionHandler(Protocol):
     def add_exception_handler(self, app: FastAPI) -> None: ...  # pragma: no cover
 
 
+@runtime_checkable
+class HasRoutes(Protocol):
+    """Extension that provides routes."""
+
+    def add_routes(self, app: FastAPI) -> None: ...  # pragma: no cover
+
+
 class BaseExtension:
     """
     Base class for extensions with explicit startup/shutdown hooks.

cuneus/core/logging.py

@@ -43,7 +43,7 @@ def configure_structlog(settings: Settings | None = None) -> None:
         term_width = shutil.get_terminal_size().columns
         pad_event = term_width - 36
         renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer(
-            colors=True, pad_event=pad_event
+            colors=True, pad_event_to=pad_event
         )
 
     # Configure structlog

cuneus/core/settings.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-import logging
+import pathlib
+import sys
 from pydantic_settings import (
     BaseSettings,
     PydanticBaseSettingsSource,
@@ -8,8 +9,6 @@ from pydantic_settings import (
     SettingsConfigDict,
 )
 
-logger = logging.getLogger(__name__)
-
 DEFAULT_TOOL_NAME = "cuneus"
 
 
@@ -40,7 +39,6 @@ class CuneusBaseSettings(BaseSettings):
 
 
 class Settings(CuneusBaseSettings):
-
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",
@@ -64,3 +62,21 @@ class Settings(CuneusBaseSettings):
     # health
     health_enabled: bool = True
     health_prefix: str = "/healthz"
+
+    @classmethod
+    def get_project_root(cls) -> pathlib.Path:
+        """
+        Get the project root by inspecting where pydantic-settings
+        found the pyproject.toml file.
+        """
+        source = PyprojectTomlConfigSettingsSource(
+            cls,
+        )
+        return source.toml_file_path.parent
+
+
+def ensure_project_in_path() -> None:
+    """Add project root to sys.path if not already present."""
+    project_root = str(Settings.get_project_root())
+    if project_root not in sys.path:  # pragma: no branch
+        sys.path.insert(0, project_root)

cuneus/dependencies.py

@@ -0,0 +1,79 @@
+# cuneus/core/dependencies.py
+from __future__ import annotations
+
+import importlib
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Dependency:
+    """A required dependency with install hint."""
+
+    import_name: str
+    package_name: str | None = None  # pip package name if different from import
+
+    @property
+    def pip_name(self) -> str:
+        return self.package_name or self.import_name
+
+
+class MissingDependencyError(ImportError):
+    """Raised when required dependencies are not installed."""
+
+    def __init__(self, extension: str, missing: list[Dependency]):
+        self.extension = extension
+        self.missing = missing
+        packages = " ".join(d.pip_name for d in missing)
+        super().__init__(
+            f"{extension} requires additional dependencies. Install with: uv add {packages}"
+        )
+
+
+def check_dependencies(extension: str, *deps: Dependency) -> None:
+    """
+    Check that dependencies are installed, raise helpful error if not.
+
+    Usage:
+        from cuneus.core.dependencies import check_dependencies, Dependency
+
+        check_dependencies(
+            "DatabaseExtension",
+            Dependency("sqlalchemy"),
+            Dependency("asyncpg"),
+        )
+    """
+    missing = []
+    for dep in deps:
+        try:
+            importlib.import_module(dep.import_name)
+        except ImportError:
+            missing.append(dep)
+
+    if missing:
+        raise MissingDependencyError(extension, missing)
+
+
+def warn_missing(extension: str, *deps: Dependency) -> list[Dependency]:
+    """
+    Check dependencies but only warn, don't raise. Returns list of missing.
+
+    Useful for optional features within an extension.
+    """
+    missing = []
+    for dep in deps:
+        try:
+            importlib.import_module(dep.import_name)
+        except ImportError:
+            missing.append(dep)
+
+    if missing:
+        packages = " ".join(d.pip_name for d in missing)
+        logger.warning(
+            f"{extension}: optional dependencies not installed. "
+            f"Some features disabled. Install with: uv add {packages}"
+        )
+
+    return missing

cuneus/ext/database.py

@@ -0,0 +1,278 @@
+# cuneus/ext/database.py
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncIterator
+
+import click
+import svcs
+from fastapi import FastAPI
+from pydantic import Field, SecretStr, computed_field
+from pydantic_settings import SettingsConfigDict
+from structlog.stdlib import get_logger
+
+from ..core.extensions import BaseExtension, HasCLI
+from ..core.settings import CuneusBaseSettings, DEFAULT_TOOL_NAME
+from ..dependencies import Dependency, check_dependencies
+
+check_dependencies(
+    "cuneus.ext.database",
+    Dependency("sqlalchemy"),
+)
+
+from sqlalchemy import URL, make_url, text
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+logger = get_logger(__name__)
+
+
+class DatabaseSettings(CuneusBaseSettings):
+    """Database configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="DATABASE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        pyproject_toml_depth=2,
+        pyproject_toml_table_header=("tool", DEFAULT_TOOL_NAME, "database"),
+    )
+
+    # Option 1: Full URL (takes precedence if set)
+    url: str | None = None
+
+    # Option 2: Individual parts
+    driver: str = "postgresql+asyncpg"
+    host: str = "localhost"
+    port: int = 5432
+    name: str = "app"
+    username: str | None = None
+    password: SecretStr | None = None
+
+    # Pool settings
+    pool_size: int = 5
+    pool_max_overflow: int = 10
+    pool_recycle: int = 3600
+    echo: bool = False
+
+    # Alembic
+    alembic_config: Path = Path("alembic.ini")
+
+    @computed_field
+    @property
+    def url_parsed(self) -> URL:
+        """Get SQLAlchemy URL, either from url string or constructed from parts."""
+        if self.url:
+            return make_url(self.url)
+
+        needs_opts = "sqlite" not in self.driver
+        password_value = self.password.get_secret_value() if self.password else None
+        password = password_value if needs_opts else None
+
+        return URL.create(
+            drivername=self.driver,
+            username=self.username if needs_opts else None,
+            password=password,
+            host=self.host if needs_opts else None,
+            port=self.port if needs_opts else None,
+            database=self.name,
+        )
+
+    @computed_field
+    @property
+    def url_redacted(self) -> str:
+        """URL safe for logging (password hidden)."""
+        return self.url_parsed.render_as_string(hide_password=True)
+
+
+class DatabaseExtension(BaseExtension, HasCLI):
+    """
+    Database extension providing AsyncSession via svcs.
+
+    Registers:
+        - AsyncEngine: The SQLAlchemy async engine
+        - async_sessionmaker: Factory for creating sessions
+        - AsyncSession: Request-scoped session (via factory)
+
+    CLI Commands:
+        - db upgrade [revision]: Run migrations
+        - db downgrade [revision]: Rollback migrations
+        - db revision -m "message": Create new migration
+        - db current: Show current revision
+        - db history: Show migration history
+        - db check: Check database connectivity
+
+    Configuration (env or pyproject.toml [tool.cuneus.database]):
+        DATABASE_URL: Connection string
+        DATABASE_POOL_SIZE: Connection pool size (default: 5)
+        DATABASE_POOL_MAX_OVERFLOW: Max overflow connections (default: 10)
+        DATABASE_POOL_RECYCLE: Connection recycle time in seconds (default: 3600)
+        DATABASE_ECHO: Echo SQL statements (default: false)
+        DATABASE_ALEMBIC_CONFIG: Path to alembic.ini (default: alembic.ini)
+    """
+
+    _session_factory: async_sessionmaker[AsyncSession]
+    _engine: AsyncEngine
+
+    def __init__(self, settings: DatabaseSettings | None = None):
+        self.settings = settings or DatabaseSettings()
+
+    @asynccontextmanager
+    async def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncIterator[dict[str, Any]]:
+        self._engine = create_async_engine(
+            self.settings.url_parsed,
+            # pool_size=self.settings.pool_size,
+            # max_overflow=self.settings.pool_max_overflow,
+            pool_recycle=self.settings.pool_recycle,
+            echo=self.settings.echo,
+        )
+
+        self._session_factory = async_sessionmaker(
+            self._engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+        )
+
+        registry.register_value(AsyncEngine, self._engine, ping=self._check)
+        registry.register_value(async_sessionmaker, self._session_factory)
+
+        @asynccontextmanager
+        async def session_factory() -> AsyncIterator[AsyncSession]:
+            async with self._session_factory() as session:
+                try:
+                    yield session
+                    await session.commit()
+                except Exception:
+                    await session.rollback()
+                    raise
+
+        registry.register_factory(AsyncSession, session_factory)
+
+        logger.info("Database started", extra={"url": self.settings.url_redacted})
+
+        try:
+            yield {
+                "db_engine": self._engine,
+                "db_session_factory": self._session_factory,
+            }
+        finally:
+            await self._engine.dispose()
+            logger.info("Database shutdown")
+
+    async def _check(self):
+        engine = create_async_engine(self.settings.url_parsed)
+        try:
+            async with engine.connect() as conn:
+                await conn.execute(text("SELECT 1"))
+        finally:
+            await engine.dispose()
+
+    def register_cli(self, cli_group: click.Group) -> None:
+        settings = self.settings
+
+        @cli_group.group()
+        def db():
+            """Database management commands."""
+            pass
+
+        @db.command()
+        @click.argument("revision", default="head")
+        def upgrade(revision: str):
+            """Upgrade database to revision (default: head)."""
+            _run_alembic_cmd("upgrade", settings.alembic_config, revision=revision)
+
+        @db.command()
+        @click.argument("revision", default="-1")
+        def downgrade(revision: str):
+            """Downgrade database to revision (default: -1)."""
+            _run_alembic_cmd("downgrade", settings.alembic_config, revision=revision)
+
+        @db.command()
+        @click.option("-m", "--message", required=True, help="Migration message")
+        @click.option("--autogenerate/--no-autogenerate", default=True)
+        def revision(message: str, autogenerate: bool):
+            """Create a new migration revision."""
+            _run_alembic_cmd(
+                "revision",
+                settings.alembic_config,
+                message=message,
+                autogenerate=autogenerate,
+            )
+
+        @db.command()
+        def current():
+            """Show current database revision."""
+            _run_alembic_cmd("current", settings.alembic_config)
+
+        @db.command()
+        def history():
+            """Show migration history."""
+            _run_alembic_cmd("history", settings.alembic_config)
+
+        @db.command()
+        @click.argument("template", default="async")
+        def init():
+            """
+            Create a new alembic setup by default this will use the async template
+            """
+
+        @db.command()
+        @click.pass_context
+        def check(ctx: click.Context):
+            """Check database connectivity."""
+            import asyncio
+
+            async def _check():
+                engine = create_async_engine(settings.url_parsed)
+                try:
+                    async with engine.connect() as conn:
+                        await conn.execute(text("SELECT 1"))
+                    click.echo("✓ Database connection OK")
+                except Exception as e:
+                    print(e)
+                    click.echo(f"✗ Database connection failed: {e}", err=True)
+                    ctx.exit(1)
+                finally:
+                    await engine.dispose()
+
+            asyncio.run(_check())
+
+
+def _run_alembic_cmd(
+    cmd: str,
+    config_path: Path,
+    revision: str | None = None,
+    message: str | None = None,
+    autogenerate: bool = False,
+) -> None:
+    """Run an alembic command."""
+    from alembic import command
+    from alembic.config import Config
+
+    if not config_path.exists():
+        raise click.ClickException(f"Alembic config not found: {config_path}")
+
+    cfg = Config(str(config_path))
+
+    match cmd:
+        case "upgrade":
+            command.upgrade(cfg, revision or "head")
+        case "downgrade":
+            command.downgrade(cfg, revision or "-1")
+        case "revision":
+            command.revision(cfg, message=message, autogenerate=autogenerate)
+        case "current":
+            command.current(cfg)
+        case "history":
+            command.history(cfg)
+        case _:
+            raise click.ClickException(f"Unknown command: {cmd}")

cuneus/ext/health.py

@@ -9,13 +9,14 @@ from typing import Any
 
 import structlog
 import svcs
-from fastapi import APIRouter, FastAPI
+from fastapi import APIRouter, FastAPI, Request
 from pydantic import BaseModel
 
 from ..core.extensions import BaseExtension
 from ..core.settings import Settings
 
 log = structlog.get_logger()
+health_router = APIRouter()
 
 
 class HealthStatus(str, Enum):
@@ -35,95 +36,91 @@ class HealthResponse(BaseModel):
     services: list[ServiceHealth] = []
 
 
+@health_router.get("", response_model=HealthResponse)
+async def health(services: svcs.fastapi.DepContainer, request: Request) -> 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=getattr(request.state, "version", "NA"),
+        services=_services,
+    )
+
+
+@health_router.get("/live")
+async def liveness() -> dict[str, str]:
+    """Liveness probe - is the process running?"""
+    return {"status": "ok"}
+
+
+@health_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"}
+
+
 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)],
-        )
+        GET /healthz       - Full health check using svcs pings
+        GET /healthz/live  - Liveness probe (always 200)
+        GET /healthz/ready - Readiness probe (503 if unhealthy)
+
+    Settings:
+        - `health_enabled`: bool to disable health routes, default True
+        - `health_prefix`: prefix to include routes default: '/healthz'
+        - `version`: used to display in the response
     """
 
     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,
+        state = await super().startup(registry, app)
+        state["version"] = self.settings.version
+        return state
+
+    def add_routes(self, app: FastAPI) -> None:
+        if self.settings.health_enabled:
+            app.include_router(
+                health_router,
+                prefix=self.settings.health_prefix,
+                tags=["health"],
             )
-
-        @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/ext/otel.py

@@ -0,0 +1,279 @@
+# cuneus/ext/otel.py
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Callable
+
+import structlog
+import svcs
+from fastapi import FastAPI, Request, Response
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from ..core.extensions import BaseExtension, HasMiddleware
+from ..core.settings import CuneusBaseSettings, DEFAULT_TOOL_NAME
+from ..dependencies import Dependency, check_dependencies
+
+check_dependencies(
+    "cuneus.ext.otel",
+    Dependency("opentelemetry.sdk", "opentelemetry-sdk"),
+    Dependency("opentelemetry.trace", "opentelemetry-api"),
+)
+
+from opentelemetry import trace, metrics
+from opentelemetry.sdk.trace import TracerProvider, SpanProcessor
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.resources import Resource, SERVICE_NAME, SERVICE_VERSION
+from opentelemetry.trace import Tracer, Status, StatusCode
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from opentelemetry.propagate import set_global_textmap
+
+logger = structlog.stdlib.get_logger(__name__)
+
+
+class OTelSettings(CuneusBaseSettings):
+    """OpenTelemetry configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="OTEL_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        pyproject_toml_depth=2,
+        pyproject_toml_table_header=("tool", DEFAULT_TOOL_NAME, "otel"),
+    )
+
+    # Service identity
+    service_name: str = "unknown-service"
+    service_version: str = "0.0.0"
+    environment: str = "development"
+
+    # Feature flags
+    enabled: bool = True
+    traces_enabled: bool = True
+    metrics_enabled: bool = True
+
+    # Auto-instrumentation
+    instrument_fastapi: bool = True
+    instrument_sqlalchemy: bool = True
+    instrument_httpx: bool = True
+    instrument_redis: bool = True
+    instrument_logging: bool = True
+
+    # Exporter
+    exporter_otlp_endpoint: str | None = None
+
+    # Sampling
+    sample_rate: float = 1.0
+
+    # Excluded paths
+    excluded_paths: list[str] = Field(
+        default_factory=lambda: ["/health", "/ready", "/metrics", "/favicon.ico"]
+    )
+
+
+class OTelExtension(BaseExtension, HasMiddleware):
+    """
+    OpenTelemetry extension providing distributed tracing and metrics.
+
+    Registers:
+        - TracerProvider: The global tracer provider
+        - Tracer: A tracer instance for the service
+        - MeterProvider: The global meter provider (if metrics enabled)
+
+    Auto-instrumentation (configurable):
+        - FastAPI/Starlette
+        - SQLAlchemy
+        - HTTPX
+        - Redis
+        - Logging
+
+    Configuration (env with OTEL_ prefix or pyproject.toml [tool.cuneus.otel]):
+        service_name: Service name for traces
+        service_version: Service version
+        environment: Deployment environment
+        enabled: Enable/disable OTel entirely (default: true)
+        traces_enabled: Enable tracing (default: true)
+        metrics_enabled: Enable metrics (default: true)
+        instrument_*: Enable specific auto-instrumentation
+        exporter_otlp_endpoint: OTLP exporter endpoint
+        sample_rate: Sampling rate 0.0-1.0 (default: 1.0)
+        excluded_paths: Paths to exclude from tracing
+    """
+
+    _tracer_provider: TracerProvider
+
+    def __init__(
+        self,
+        settings: OTelSettings | None = None,
+        span_exporters: list[SpanExporter] | None = None,
+        span_processors: list[SpanProcessor] | None = None,
+    ):
+        self.settings = settings or OTelSettings()
+        self._span_exporters = span_exporters or []
+        self._span_processors = span_processors or []
+
+    @asynccontextmanager
+    async def register(
+        self, registry: svcs.Registry, app: FastAPI
+    ) -> AsyncIterator[dict[str, Any]]:
+        if not self.settings.enabled:
+            logger.info("OpenTelemetry disabled")
+            yield {}
+            return
+
+        resource = Resource.create(
+            {
+                SERVICE_NAME: self.settings.service_name,
+                SERVICE_VERSION: self.settings.service_version,
+                "deployment.environment": self.settings.environment,
+            }
+        )
+
+        if self.settings.traces_enabled:
+            self._tracer_provider = TracerProvider(resource=resource)
+
+            for processor in self._span_processors:
+                self._tracer_provider.add_span_processor(processor)
+
+            for exporter in self._span_exporters:
+                self._tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
+
+            trace.set_tracer_provider(self._tracer_provider)
+            set_global_textmap(TraceContextTextMapPropagator())
+
+            registry.register_value(TracerProvider, self._tracer_provider)
+            registry.register_value(
+                Tracer,
+                self._tracer_provider.get_tracer(self.settings.service_name),
+            )
+
+            self._setup_auto_instrumentation()
+
+            logger.info(
+                "OpenTelemetry tracing started",
+                extra={
+                    "service": self.settings.service_name,
+                    "exporters": len(self._span_exporters),
+                },
+            )
+
+        if self.settings.metrics_enabled:
+            meter_provider = MeterProvider(resource=resource)
+            metrics.set_meter_provider(meter_provider)
+            registry.register_value(MeterProvider, meter_provider)
+
+        try:
+            yield {"tracer_provider": self._tracer_provider}
+        finally:
+            if self._tracer_provider:
+                self._tracer_provider.shutdown()
+                logger.info("OpenTelemetry shutdown")
+
+    def middleware(self) -> list[Middleware]:
+        if not self.settings.enabled or not self.settings.traces_enabled:
+            return []
+
+        return [
+            Middleware(
+                OTelMiddleware,
+                excluded_paths=set(self.settings.excluded_paths),
+            )
+        ]
+
+    def _setup_auto_instrumentation(self) -> None:
+        """Setup auto-instrumentation based on settings."""
+        instrumentors = [
+            (
+                self.settings.instrument_fastapi,
+                "opentelemetry.instrumentation.fastapi",
+                "FastAPIInstrumentor",
+            ),
+            (
+                self.settings.instrument_sqlalchemy,
+                "opentelemetry.instrumentation.sqlalchemy",
+                "SQLAlchemyInstrumentor",
+            ),
+            (
+                self.settings.instrument_httpx,
+                "opentelemetry.instrumentation.httpx",
+                "HTTPXClientInstrumentor",
+            ),
+            (
+                self.settings.instrument_redis,
+                "opentelemetry.instrumentation.redis",
+                "RedisInstrumentor",
+            ),
+        ]
+
+        for enabled, module, class_name in instrumentors:
+            if enabled:
+                self._try_instrument(module, class_name)
+
+    def _try_instrument(self, module: str, class_name: str) -> None:
+        try:
+            import importlib
+
+            mod = importlib.import_module(module)
+            instrumentor = getattr(mod, class_name)()
+            instrumentor.instrument()
+            logger.debug(f"{class_name} auto-instrumentation enabled")
+        except ImportError:
+            logger.debug(f"{class_name} instrumentation not available")
+        except Exception as e:
+            logger.warning(f"{class_name} instrumentation failed: {e}")
+
+
+class OTelMiddleware(BaseHTTPMiddleware):
+    """Middleware to enrich spans and logs with trace context."""
+
+    def __init__(self, app, excluded_paths: set[str] | None = None):
+        super().__init__(app)
+        self.excluded_paths = excluded_paths or set()
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        if request.url.path in self.excluded_paths:
+            return await call_next(request)
+
+        span = trace.get_current_span()
+        ctx = span.get_span_context()
+
+        # Bind trace context to structlog for this request
+        if ctx.is_valid:
+            structlog.contextvars.bind_contextvars(
+                trace_id=format(ctx.trace_id, "032x"),
+                span_id=format(ctx.span_id, "016x"),
+            )
+
+        if span.is_recording():
+            # span.set_attribute("http.client_ip", _get_client_ip(request))
+            span.set_attribute("http.user_agent", request.headers.get("user-agent", ""))
+
+            if request.url.query:
+                span.set_attribute("http.query_string", str(request.url.query))
+
+            if request_id := request.headers.get("x-request-id"):
+                span.set_attribute("http.request_id", request_id)
+
+        try:
+            response = await call_next(request)
+
+            if span.is_recording():
+                if content_length := response.headers.get("content-length"):
+                    span.set_attribute(
+                        "http.response_content_length", int(content_length)
+                    )
+
+            return response
+
+        except Exception as exc:
+            if span.is_recording():
+                span.set_status(Status(StatusCode.ERROR, str(exc)))
+                span.record_exception(exc)
+            raise
+
+        finally:
+            structlog.contextvars.unbind_contextvars("trace_id", "span_id")

cuneus/ext/server.py

@@ -0,0 +1,54 @@
+import click
+
+from ..core.extensions import BaseExtension
+from ..utils import import_from_string
+
+
+class ServerExtension(BaseExtension):
+    """Provides dev/prod/routes CLI commands."""
+
+    def register_cli(self, cli_group: click.Group) -> None:
+        settings = self.settings
+
+        @cli_group.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 in development mode with reload."""
+            import uvicorn
+
+            uvicorn.run(
+                settings.app_module,
+                host=host,
+                port=port,
+                reload=True,
+                log_config=None,
+                server_header=False,
+            )
+
+        @cli_group.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 in production mode."""
+            import uvicorn
+
+            uvicorn.run(
+                settings.app_module,
+                host=host,
+                port=port,
+                workers=workers,
+                log_config=None,
+                server_header=False,
+            )
+
+        @cli_group.command()
+        def routes() -> None:
+            """List all registered routes."""
+            app = import_from_string(settings.app_module)
+
+            for route in app.routes:
+                if hasattr(route, "methods"):  # pragma: no branch
+                    methods = ",".join(route.methods - {"HEAD", "OPTIONS"})
+                    click.echo(f"{methods:8} {route.path}")

cuneus/utils.py

@@ -0,0 +1,12 @@
+import importlib
+import typing
+
+
+def import_from_string(import_str: str) -> typing.Any:
+    """Import an object from a module:attribute string."""
+    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)

{cuneus-0.2.8.dist-info → cuneus-0.2.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuneus
-Version: 0.2.8
+Version: 0.2.10
 Summary: ASGI application wrapper
 Project-URL: Homepage, https://github.com/rmyers/cuneus
 Project-URL: Documentation, https://github.com/rmyers/cuneus#readme
@@ -24,11 +24,15 @@ 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: aiosqlite[dev]>=0.22.1; 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: opentelemetry-api; extra == 'dev'
+Requires-Dist: opentelemetry-instrumentation; extra == 'dev'
+Requires-Dist: opentelemetry-sdk; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest-mock; extra == 'dev'

cuneus-0.2.10.dist-info/RECORD

@@ -0,0 +1,20 @@
+cuneus/__init__.py,sha256=AJXN9dnXIWn0Eg6JxWOgOf0C386EqBNdHiQG2akTpKc,1295
+cuneus/cli.py,sha256=Me84yXEWpsa5QMDcESKQPZhBgZnFJ3iKBshAXtlj2AM,1490
+cuneus/dependencies.py,sha256=97VAZKdL7MmP-wKAmwQ-AzADYeG4gYAnys_ru-PaqVg,2160
+cuneus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/utils.py,sha256=A2GN2gWjf3MdJi3bcFRxFWWDEy2t8bQOYdu8N0ZhqAE,401
+cuneus/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/core/application.py,sha256=AFBzaAMX-jJZvapSe-5prvIeaRf2ynJwrKk9Tvk1nkc,4469
+cuneus/core/exceptions.py,sha256=GRtMz4tZZzpA2-Zwx4nBEc5SGcWrrFf0OWFYeHCpU0I,5468
+cuneus/core/extensions.py,sha256=fO9RaJ00Bw9s0VsnCQAAdo-zR9N8573uO3YP2fYUQc4,2934
+cuneus/core/logging.py,sha256=Ql2VDQesZaDRdhua2HLYzvNhkIPVsTGUqxwYBkUI2dc,4581
+cuneus/core/settings.py,sha256=75NRttKkLpT6AxVd6dj3boYq05j5td32-c7fAlTjLsg,2247
+cuneus/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cuneus/ext/database.py,sha256=BED5A73U-yVVPxUJe1nuzOBee7D0QnMvcmk8V_3hUNI,8987
+cuneus/ext/health.py,sha256=l561FKnOhlsuCxJF2lSxwiEagdakixoaD78MGz4SL1s,3590
+cuneus/ext/otel.py,sha256=ye4N-WL6xQpxTN8RMj06Q3yQA1CFLrY4J1xsjQjGvUY,9565
+cuneus/ext/server.py,sha256=wyQMiHFZEFYt1a4wC4IjorEp70kH7fF2aLx3_X5t5RI,1869
+cuneus-0.2.10.dist-info/METADATA,sha256=99NJ0rkBSUoc9y-agUxJ5on_oDBdx6s77Fz33rxUQ5Q,7051
+cuneus-0.2.10.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cuneus-0.2.10.dist-info/entry_points.txt,sha256=tzPgom-_UkpP_uLKv3V_XyoIsKg84FBAc9ddjYl0W0Y,43
+cuneus-0.2.10.dist-info/RECORD,,

cuneus-0.2.8.dist-info/RECORD

@@ -1,15 +0,0 @@
-cuneus/__init__.py,sha256=AJXN9dnXIWn0Eg6JxWOgOf0C386EqBNdHiQG2akTpKc,1295
-cuneus/cli.py,sha256=rcJDqU28FMPSw7tkmKUz95ERKzgYv43Y2kKVZw24rLo,3864
-cuneus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cuneus/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cuneus/core/application.py,sha256=Xoqs3fREJ-KPzSilq4ua65JzKv6w5LgugGaMklDELdU,4376
-cuneus/core/exceptions.py,sha256=gyHgVy4UC7gBjs5pXpCzIIyIVsV7K8xt-KZKi8eLJtM,5496
-cuneus/core/extensions.py,sha256=wqN2rbaqhiTkfK_fA5AkFlefOAV2GJr6zTLf9Oi-n4c,2771
-cuneus/core/logging.py,sha256=jWwtPJTNYtvOSb4etg7pglWHAKfV4iRuw4Npoqne_00,4578
-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.8.dist-info/METADATA,sha256=Y3d-3jUnaPU_GkOeHpYaxM9AmiEfnjc4WVIo4OZrYjM,6837
-cuneus-0.2.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-cuneus-0.2.8.dist-info/entry_points.txt,sha256=tzPgom-_UkpP_uLKv3V_XyoIsKg84FBAc9ddjYl0W0Y,43
-cuneus-0.2.8.dist-info/RECORD,,