prodkit 0.1.0__py3-none-any.whl

prodkit/core/production.py

@@ -0,0 +1,123 @@
+"""The Production entrypoint — ProdKit's public API.
+
+from fastapi import FastAPI
+from prodkit import Production
+
+app = FastAPI()
+Production(app)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from prodkit.contracts.plugin import Plugin
+from prodkit.core.config import ProdKitConfig, resolve_config
+from prodkit.core.context import Context
+from prodkit.core.exceptions import ProdKitError
+from prodkit.core.lifecycle import compose_lifespan
+from prodkit.core.plugin_manager import PluginManager
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+_MARKER_ATTR = "_prodkit_production"
+
+# The built-in plugin factory is injected by prodkit/__init__.py so the kernel
+# stays free of plugin imports (enforced by import-linter).
+_builtin_factory: Callable[[ProdKitConfig], list[Plugin]] = lambda config: []  # noqa: E731
+
+
+def set_builtin_factory(factory: Callable[[ProdKitConfig], list[Plugin]]) -> None:
+    global _builtin_factory
+    _builtin_factory = factory
+
+
+# Plugin sections that can be toggled with Production(app, cors=False) etc.
+_TOGGLEABLE = (
+    "logging",
+    "request_id",
+    "errors",
+    "health",
+    "security",
+    "cors",
+    "compression",
+)
+
+
+class Production:
+    """Configure production best practices on a FastAPI application.
+
+    Args:
+        app: The FastAPI application to productionize (mutated in place).
+        plugins: Additional plugins, activated after the built-ins.
+        config_file: Path to the TOML config file (default ``prodkit.toml``).
+        environment: ``"development"``, ``"staging"``, or ``"production"``.
+        **overrides: Top-level config overrides. Booleans toggle a section
+            (``cors=False``); dicts configure it
+            (``cors={"origins": ["https://app.example.com"]}``).
+    """
+
+    def __init__(
+        self,
+        app: FastAPI,
+        *,
+        plugins: list[Plugin] | None = None,
+        config_file: str | Path = "prodkit.toml",
+        environment: str | None = None,
+        **overrides: Any,
+    ) -> None:
+        if getattr(app, _MARKER_ATTR, None) is not None:
+            raise ProdKitError("Production() was already applied to this app")
+
+        self.config = resolve_config(
+            self._normalize_overrides(environment, overrides), toml_path=config_file
+        )
+        self.context = Context(app, self.config)
+
+        all_plugins = _builtin_factory(self.config) + list(plugins or [])
+        self.plugins = PluginManager(all_plugins).plugins
+
+        self._boot(app)
+        setattr(app, _MARKER_ATTR, self)
+
+    @staticmethod
+    def _normalize_overrides(environment: str | None, overrides: dict[str, Any]) -> dict[str, Any]:
+        normalized: dict[str, Any] = {}
+        if environment is not None:
+            normalized["environment"] = environment
+        for key, value in overrides.items():
+            if key in _TOGGLEABLE and isinstance(value, bool):
+                normalized[key] = {"enabled": value}
+            elif key in _TOGGLEABLE and isinstance(value, dict):
+                normalized[key] = {"enabled": True, **value}
+            else:
+                normalized[key] = value
+        return normalized
+
+    def _boot(self, app: FastAPI) -> None:
+        ctx = self.context
+        for plugin in self.plugins:
+            ctx._current_plugin = plugin.name
+            plugin.configure(ctx)
+        for plugin in self.plugins:
+            ctx._current_plugin = plugin.name
+            plugin.register_middleware(ctx)
+        ctx._current_plugin = ""
+
+        # The health plugin aggregates readiness checks from all plugins; hand
+        # it the activated list via its registry-published interface.
+        if ctx.registry.has("health"):
+            ctx.registry.get("health").register_plugins(self.plugins)
+
+        # Starlette applies middleware inside-out (last added = outermost),
+        # so apply in DESCENDING priority: highest (innermost) first.
+        for spec in sorted(ctx.middleware_specs(), key=lambda s: s.priority, reverse=True):
+            app.add_middleware(spec.cls, **spec.options)  # type: ignore[arg-type]
+
+        for plugin in self.plugins:
+            plugin.register_routes(ctx)
+
+        app.router.lifespan_context = compose_lifespan(app, ctx, self.plugins)

prodkit/core/registry.py

@@ -0,0 +1,38 @@
+"""Named service registry shared across plugins."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from prodkit.core.exceptions import ProdKitError, ServiceNotFoundError
+
+
+class Registry:
+    """Simple name → service store. Names are unique; re-registration is an
+    explicit error so two plugins can't silently fight over a name."""
+
+    def __init__(self) -> None:
+        self._services: dict[str, Any] = {}
+
+    def provide(self, name: str, service: Any) -> None:
+        if name in self._services:
+            raise ProdKitError(
+                f"Service {name!r} is already registered; "
+                "use a different name or remove the conflicting plugin"
+            )
+        self._services[name] = service
+
+    def get(self, name: str) -> Any:
+        try:
+            return self._services[name]
+        except KeyError:
+            available = ", ".join(sorted(self._services)) or "<none>"
+            raise ServiceNotFoundError(
+                f"No service named {name!r}; available: {available}"
+            ) from None
+
+    def has(self, name: str) -> bool:
+        return name in self._services
+
+    def names(self) -> list[str]:
+        return sorted(self._services)

prodkit/plugins/__init__.py

@@ -0,0 +1,54 @@
+"""Built-in plugin composition.
+
+This module (not the kernel) knows about the concrete built-in plugins.
+``prodkit/__init__.py`` injects :func:`builtin_plugins` into the kernel at
+import time, keeping ``prodkit.core`` free of plugin imports (enforced by
+import-linter).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from prodkit.plugins.compression import CompressionPlugin
+from prodkit.plugins.cors import CORSPlugin
+from prodkit.plugins.errors import ErrorsPlugin
+from prodkit.plugins.health import HealthPlugin
+from prodkit.plugins.logging import LoggingPlugin
+from prodkit.plugins.request_id import RequestIDPlugin
+from prodkit.plugins.security import SecurityPlugin
+
+if TYPE_CHECKING:
+    from prodkit.contracts.plugin import Plugin
+    from prodkit.core.config import ProdKitConfig
+
+__all__ = [
+    "CORSPlugin",
+    "CompressionPlugin",
+    "ErrorsPlugin",
+    "HealthPlugin",
+    "LoggingPlugin",
+    "RequestIDPlugin",
+    "SecurityPlugin",
+    "builtin_plugins",
+]
+
+
+def builtin_plugins(config: ProdKitConfig) -> list[Plugin]:
+    """The built-in plugins enabled by the given configuration."""
+    plugins: list[Plugin] = []
+    if config.request_id.enabled:
+        plugins.append(RequestIDPlugin())
+    if config.logging.enabled:
+        plugins.append(LoggingPlugin())
+    if config.errors.enabled:
+        plugins.append(ErrorsPlugin())
+    if config.health.enabled:
+        plugins.append(HealthPlugin())
+    if config.security.enabled:
+        plugins.append(SecurityPlugin())
+    if config.cors.enabled:
+        plugins.append(CORSPlugin())
+    if config.compression.enabled:
+        plugins.append(CompressionPlugin())
+    return plugins

prodkit/plugins/compression/__init__.py

@@ -0,0 +1,22 @@
+"""Compression plugin: gzip via Starlette; innermost of the built-in
+middleware so it compresses final response bodies."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from starlette.middleware.gzip import GZipMiddleware
+
+from prodkit.contracts.plugin import PRIORITY_COMPRESSION, Plugin
+from prodkit.core.context import Context
+
+
+class CompressionPlugin(Plugin):
+    name: ClassVar[str] = "compression"
+
+    def register_middleware(self, ctx: Context) -> None:
+        ctx.add_middleware(
+            GZipMiddleware,
+            priority=PRIORITY_COMPRESSION,
+            minimum_size=ctx.config.compression.minimum_size,
+        )

prodkit/plugins/cors/__init__.py

@@ -0,0 +1,38 @@
+"""CORS plugin: thin, priority-ordered wrapper over Starlette's CORSMiddleware.
+
+The dangerous combination (origins=['*'] + allow_credentials=True) is rejected
+at config-resolution time in production.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from starlette.middleware.cors import CORSMiddleware
+
+from prodkit.contracts.plugin import PRIORITY_CORS, Plugin
+from prodkit.core.context import Context
+from prodkit.core.exceptions import ProdKitConfigError
+
+
+class CORSPlugin(Plugin):
+    name: ClassVar[str] = "cors"
+
+    def configure(self, ctx: Context) -> None:
+        if not ctx.config.cors.origins:
+            raise ProdKitConfigError(
+                "cors is enabled but no origins are configured; set "
+                "cors={'origins': ['https://app.example.com']} or disable it"
+            )
+
+    def register_middleware(self, ctx: Context) -> None:
+        cfg = ctx.config.cors
+        ctx.add_middleware(
+            CORSMiddleware,
+            priority=PRIORITY_CORS,
+            allow_origins=cfg.origins,
+            allow_credentials=cfg.allow_credentials,
+            allow_methods=cfg.allow_methods,
+            allow_headers=cfg.allow_headers,
+            max_age=cfg.max_age,
+        )

prodkit/plugins/errors/__init__.py

@@ -0,0 +1,98 @@
+"""Errors plugin: normalized error responses per RFC 9457 (problem+json).
+
+- HTTPException and validation errors keep their semantics, reshaped into a
+  consistent problem-details body (via FastAPI exception handlers).
+- Unhandled exceptions are caught by our own middleware INSIDE the request-id
+  scope — Starlette's outermost ServerErrorMiddleware would run after the
+  request-id contextvar is reset, losing log/response correlation. The
+  traceback is logged with the request ID, never sent to the client (unless
+  include_debug_details, which the config layer refuses in production).
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+from typing import Any, ClassVar
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import JSONResponse, Response
+
+from prodkit.contracts.plugin import PRIORITY_ERRORS, Plugin
+from prodkit.core.context import Context
+from prodkit.plugins.request_id import get_request_id
+
+logger = logging.getLogger("prodkit")
+
+_MEDIA_TYPE = "application/problem+json"
+
+
+def _problem(status: int, title: str, detail: Any = None, **extra: Any) -> JSONResponse:
+    body: dict[str, Any] = {"type": "about:blank", "title": title, "status": status}
+    if detail is not None:
+        body["detail"] = detail
+    request_id = get_request_id()
+    if request_id:
+        body["request_id"] = request_id
+    body.update(extra)
+    return JSONResponse(body, status_code=status, media_type=_MEDIA_TYPE)
+
+
+class ErrorHandlingMiddleware(BaseHTTPMiddleware):
+    """Catch-all for exceptions no handler dealt with. Runs inside request-id
+    and logging middleware so the 500 is correlated and access-logged."""
+
+    def __init__(self, app, include_debug_details: bool = False):  # type: ignore[no-untyped-def]
+        super().__init__(app)
+        self.include_debug_details = include_debug_details
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        try:
+            return await call_next(request)
+        except Exception as exc:
+            # Full traceback to logs (correlated by request ID) ...
+            logger.exception("Unhandled exception on %s %s", request.method, request.url.path)
+            if self.include_debug_details:
+                return _problem(
+                    500,
+                    "Internal Server Error",
+                    detail=str(exc),
+                    traceback=traceback.format_exc().splitlines(),
+                )
+            # ... opaque response to the client. The request_id in the body
+            # is what support/ops use to find the logged traceback.
+            return _problem(500, "Internal Server Error")
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    @app.exception_handler(StarletteHTTPException)
+    async def http_exception_handler(
+        request: Request, exc: StarletteHTTPException
+    ) -> JSONResponse:
+        response = _problem(exc.status_code, exc.detail or "HTTP error")
+        for key, value in (exc.headers or {}).items():
+            response.headers[key] = value
+        return response
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        return _problem(422, "Validation error", detail=exc.errors())
+
+
+class ErrorsPlugin(Plugin):
+    name: ClassVar[str] = "errors"
+
+    def register_middleware(self, ctx: Context) -> None:
+        ctx.add_middleware(
+            ErrorHandlingMiddleware,
+            priority=PRIORITY_ERRORS,
+            include_debug_details=ctx.config.errors.include_debug_details,
+        )
+
+    def register_routes(self, ctx: Context) -> None:
+        install_error_handlers(ctx.app)

prodkit/plugins/health/__init__.py

@@ -0,0 +1,72 @@
+"""Health plugin: Kubernetes-native endpoints.
+
+- /live   → 200 if the process is alive (liveness probe)
+- /health → alias for liveness, the conventional human-checked URL
+- /ready  → 200 only when every registered plugin check passes; 503 with
+            per-check detail otherwise (readiness probe)
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, ClassVar
+
+from starlette.responses import JSONResponse
+
+from prodkit.contracts.plugin import Check, Plugin
+from prodkit.core.context import Context
+from prodkit.core.exceptions import ProdKitError
+
+
+class HealthPlugin(Plugin):
+    name: ClassVar[str] = "health"
+
+    def __init__(self) -> None:
+        self._ctx: Context | None = None
+        self._plugins: list[Plugin] = []
+
+    def configure(self, ctx: Context) -> None:
+        self._ctx = ctx
+        # The health plugin aggregates checks from every active plugin; the
+        # registry hands us the list without coupling to the plugin manager.
+        ctx.registry.provide("health", self)
+
+    def register_plugins(self, plugins: list[Plugin]) -> None:
+        self._plugins = plugins
+
+    async def run_checks(self) -> list[Check]:
+        if self._ctx is None:  # pragma: no cover - configure() always runs first
+            raise ProdKitError("HealthPlugin used before configure()")
+        results: list[Check] = []
+        for plugin in self._plugins:
+            checks = plugin.checks(self._ctx)
+            if inspect.isawaitable(checks):
+                checks = await checks
+            results.extend(checks)
+        return results
+
+    def register_routes(self, ctx: Context) -> None:
+        cfg = ctx.config.health
+
+        async def live() -> JSONResponse:
+            return JSONResponse({"status": "alive"})
+
+        async def health() -> JSONResponse:
+            return JSONResponse({"status": "ok"})
+
+        async def ready() -> JSONResponse:
+            checks = await self.run_checks()
+            failed = [c for c in checks if not c.passed]
+            payload: dict[str, Any] = {
+                "status": "ready" if not failed else "not ready",
+                "checks": [
+                    {"name": c.name, "passed": c.passed, "detail": c.detail} for c in checks
+                ],
+            }
+            return JSONResponse(payload, status_code=200 if not failed else 503)
+
+        # Excluded from the OpenAPI schema: probe endpoints are infrastructure,
+        # not API surface.
+        ctx.app.add_api_route(cfg.live_path, live, include_in_schema=False)
+        ctx.app.add_api_route(cfg.health_path, health, include_in_schema=False)
+        ctx.app.add_api_route(cfg.ready_path, ready, include_in_schema=False)

prodkit/plugins/logging/__init__.py

@@ -0,0 +1,116 @@
+"""Structured logging plugin.
+
+JSON logs in production (machine-parseable), pretty console logs in
+development. Every request gets one access-log line with method, path,
+status, duration, and the correlated request ID.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import time
+from typing import Any, ClassVar
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from prodkit.contracts.plugin import PRIORITY_LOGGING, Plugin
+from prodkit.core.context import Context
+from prodkit.plugins.request_id import get_request_id
+
+_CONTROL_CHARS = dict.fromkeys(range(32))
+
+
+def _sanitize(value: str) -> str:
+    """Strip control characters (CR/LF included) so attacker-controlled
+    strings (paths, headers) cannot forge extra log lines."""
+    return value.translate(_CONTROL_CHARS)
+
+
+class JSONFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        entry: dict[str, Any] = {
+            "timestamp": self.formatTime(record, "%Y-%m-%dT%H:%M:%S%z"),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        request_id = get_request_id()
+        if request_id:
+            entry["request_id"] = request_id
+        if record.exc_info and record.exc_info[0] is not None:
+            entry["exception"] = self.formatException(record.exc_info)
+        extra = getattr(record, "prodkit_extra", None)
+        if isinstance(extra, dict):
+            entry.update(extra)
+        return json.dumps(entry, default=str)
+
+
+class ConsoleFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        request_id = get_request_id()
+        rid = f" [{request_id[:8]}]" if request_id else ""
+        base = (
+            f"{self.formatTime(record, '%H:%M:%S')} "
+            f"{record.levelname:<8}{rid} {record.getMessage()}"
+        )
+        if record.exc_info and record.exc_info[0] is not None:
+            base += "\n" + self.formatException(record.exc_info)
+        return base
+
+
+class AccessLogMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, logger_name: str = "prodkit.access"):  # type: ignore[no-untyped-def]
+        super().__init__(app)
+        self.logger = logging.getLogger(logger_name)
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        start = time.perf_counter()
+        response = await call_next(request)
+        duration_ms = (time.perf_counter() - start) * 1000
+        path = _sanitize(request.url.path)
+        self.logger.info(
+            "%s %s %d %.1fms",
+            request.method,
+            path,
+            response.status_code,
+            duration_ms,
+            extra={
+                "prodkit_extra": {
+                    "method": request.method,
+                    "path": path,
+                    "status": response.status_code,
+                    "duration_ms": round(duration_ms, 1),
+                }
+            },
+        )
+        return response
+
+
+def configure_logging(level: str, log_format: str) -> None:
+    formatter: logging.Formatter
+    formatter = JSONFormatter() if log_format == "json" else ConsoleFormatter()
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(formatter)
+
+    for name in ("prodkit", "prodkit.access"):
+        logger = logging.getLogger(name)
+        logger.handlers = [handler]
+        logger.setLevel(level.upper())
+        logger.propagate = False
+
+
+class LoggingPlugin(Plugin):
+    # No hard dependency on request-id: correlation degrades gracefully to ""
+    # when that plugin is disabled, and middleware order comes from priorities.
+    name: ClassVar[str] = "logging"
+
+    def configure(self, ctx: Context) -> None:
+        cfg = ctx.config.logging
+        configure_logging(cfg.level, cfg.format)
+
+    def register_middleware(self, ctx: Context) -> None:
+        ctx.add_middleware(AccessLogMiddleware, priority=PRIORITY_LOGGING)

prodkit/plugins/request_id/__init__.py

@@ -0,0 +1,61 @@
+"""Request-ID plugin: generates/propagates X-Request-ID and exposes it via a
+contextvar so the logging plugin can correlate every log line to a request."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from contextvars import ContextVar
+from typing import ClassVar
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from prodkit.contracts.plugin import PRIORITY_REQUEST_ID, Plugin
+from prodkit.core.context import Context
+
+request_id_var: ContextVar[str] = ContextVar("prodkit_request_id", default="")
+
+# Inbound IDs are attacker-controlled input headed for logs and response
+# headers: constrain to a safe charset and length to prevent log injection.
+_SAFE_ID = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+
+def get_request_id() -> str:
+    """The current request's ID, or '' outside a request."""
+    return request_id_var.get()
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, header: str = "X-Request-ID", trust_incoming: bool = False):  # type: ignore[no-untyped-def]
+        super().__init__(app)
+        self.header = header
+        self.trust_incoming = trust_incoming
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        incoming = request.headers.get(self.header, "")
+        if self.trust_incoming and incoming and _SAFE_ID.match(incoming):
+            request_id = incoming
+        else:
+            request_id = uuid.uuid4().hex
+        token = request_id_var.set(request_id)
+        try:
+            response = await call_next(request)
+        finally:
+            request_id_var.reset(token)
+        response.headers[self.header] = request_id
+        return response
+
+
+class RequestIDPlugin(Plugin):
+    name: ClassVar[str] = "request-id"
+
+    def register_middleware(self, ctx: Context) -> None:
+        cfg = ctx.config.request_id
+        ctx.add_middleware(
+            RequestIDMiddleware,
+            priority=PRIORITY_REQUEST_ID,
+            header=cfg.header,
+            trust_incoming=cfg.trust_incoming,
+        )