prodkit 0.1.0__py3-none-any.whl

prodkit/__init__.py

@@ -0,0 +1,57 @@
+"""ProdKit — the production framework for FastAPI.
+
+from fastapi import FastAPI
+from prodkit import Production
+
+app = FastAPI()
+Production(app)
+"""
+
+from prodkit.contracts.plugin import Check, Plugin
+from prodkit.core.config import (
+    CompressionConfig,
+    CORSConfig,
+    ErrorsConfig,
+    HealthConfig,
+    LoggingConfig,
+    ProdKitConfig,
+    RequestIDConfig,
+    SecurityConfig,
+)
+from prodkit.core.context import Context
+from prodkit.core.exceptions import (
+    PluginDependencyError,
+    PluginError,
+    ProdKitConfigError,
+    ProdKitError,
+    ServiceNotFoundError,
+)
+from prodkit.core.production import Production, set_builtin_factory
+from prodkit.plugins import builtin_plugins
+
+# Wire the built-in plugins into the kernel here, at the package composition
+# root — the kernel itself never imports from prodkit.plugins.
+set_builtin_factory(builtin_plugins)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CORSConfig",
+    "Check",
+    "CompressionConfig",
+    "Context",
+    "ErrorsConfig",
+    "HealthConfig",
+    "LoggingConfig",
+    "Plugin",
+    "PluginDependencyError",
+    "PluginError",
+    "ProdKitConfig",
+    "ProdKitConfigError",
+    "ProdKitError",
+    "Production",
+    "RequestIDConfig",
+    "SecurityConfig",
+    "ServiceNotFoundError",
+    "__version__",
+]

prodkit/contracts/plugin.py

@@ -0,0 +1,61 @@
+"""The Plugin contract every ProdKit plugin implements."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from prodkit.core.context import Context
+
+
+@dataclass
+class Check:
+    """A readiness/doctor check result."""
+
+    name: str
+    passed: bool
+    detail: str = ""
+
+
+class Plugin:
+    """Base class for all ProdKit plugins. All hooks are optional overrides.
+
+    Hooks run in dependency order (see ``requires``); ``shutdown`` runs in
+    reverse activation order (LIFO).
+    """
+
+    name: ClassVar[str] = ""
+    requires: ClassVar[tuple[str, ...]] = ()
+
+    def configure(self, ctx: Context) -> None:
+        """Validate and resolve configuration. Raise ProdKitConfigError to
+        abort boot with a clear message."""
+
+    def register_middleware(self, ctx: Context) -> None:
+        """Register middleware via ``ctx.add_middleware(cls, priority=N, ...)``."""
+
+    def register_routes(self, ctx: Context) -> None:
+        """Add routes to ``ctx.app`` (e.g. /health)."""
+
+    async def startup(self, ctx: Context) -> None:
+        """Acquire async resources (connection pools, clients)."""
+
+    async def shutdown(self, ctx: Context) -> None:
+        """Release resources gracefully."""
+
+    def checks(self, ctx: Context) -> list[Check]:
+        """Readiness checks, aggregated by the health plugin's /ready."""
+        return []
+
+
+# Documented middleware priorities for the built-ins. Lower = outermost.
+PRIORITY_REQUEST_ID = 100
+PRIORITY_LOGGING = 200
+PRIORITY_ERRORS = 250
+PRIORITY_METRICS = 300
+PRIORITY_SECURITY = 400
+PRIORITY_CORS = 500
+PRIORITY_RATE_LIMIT = 600
+PRIORITY_COMPRESSION = 700
+PRIORITY_AUTH = 800

prodkit/core/config.py

@@ -0,0 +1,245 @@
+"""Layered configuration.
+
+Resolution priority (highest wins):
+    1. Python arguments to ``Production(...)``
+    2. Environment variables (``PRODKIT_*``, ``__`` as section delimiter)
+    3. ``prodkit.toml``
+    4. Environment-profile defaults (development / staging / production)
+    5. Library defaults declared on the models below
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised on Python 3.10 in CI
+    import tomli as tomllib
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from prodkit.core.exceptions import ProdKitConfigError
+
+Environment = Literal["development", "staging", "production"]
+
+_ENV_PREFIX = "PRODKIT_"
+
+
+class _Section(BaseModel):
+    """Base for config sections: unknown keys are a hard error (fail fast)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class LoggingConfig(_Section):
+    enabled: bool = True
+    level: str = "INFO"
+    format: Literal["json", "console"] = "json"
+    include_request_body: bool = False  # off by default: bodies may contain secrets/PII
+
+
+class RequestIDConfig(_Section):
+    enabled: bool = True
+    header: str = "X-Request-ID"
+    # Trusting inbound IDs lets clients forge/poison log correlation, so
+    # only honor them from a proxy you control.
+    trust_incoming: bool = False
+
+
+class ErrorsConfig(_Section):
+    enabled: bool = True
+    # Debug tracebacks in responses are opt-in and refused in production (see checks below).
+    include_debug_details: bool = False
+
+
+class HealthConfig(_Section):
+    enabled: bool = True
+    health_path: str = "/health"
+    ready_path: str = "/ready"
+    live_path: str = "/live"
+
+
+class SecurityConfig(_Section):
+    enabled: bool = True
+    hsts: bool = True
+    hsts_max_age: int = 63072000  # 2 years, preload-eligible
+    frame_options: Literal["DENY", "SAMEORIGIN"] = "DENY"
+    referrer_policy: str = "strict-origin-when-cross-origin"
+    content_security_policy: str | None = None  # opt-in: app-specific
+    permissions_policy: str = "camera=(), microphone=(), geolocation=()"
+    trusted_hosts: list[str] = Field(default_factory=list)
+    https_redirect: bool = False
+
+
+class CORSConfig(_Section):
+    enabled: bool = False
+    origins: list[str] = Field(default_factory=list)
+    allow_credentials: bool = False
+    allow_methods: list[str] = Field(default_factory=lambda: ["GET", "POST", "PUT", "DELETE"])
+    allow_headers: list[str] = Field(default_factory=lambda: ["Authorization", "Content-Type"])
+    max_age: int = 600
+
+
+class CompressionConfig(_Section):
+    enabled: bool = True
+    minimum_size: int = 500  # bytes; don't waste CPU on tiny responses
+
+
+class ProdKitConfig(_Section):
+    """Fully resolved, validated ProdKit configuration."""
+
+    environment: Environment = "production"
+    debug: bool = False
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    request_id: RequestIDConfig = Field(default_factory=RequestIDConfig)
+    errors: ErrorsConfig = Field(default_factory=ErrorsConfig)
+    health: HealthConfig = Field(default_factory=HealthConfig)
+    security: SecurityConfig = Field(default_factory=SecurityConfig)
+    cors: CORSConfig = Field(default_factory=CORSConfig)
+    compression: CompressionConfig = Field(default_factory=CompressionConfig)
+
+
+# Profile defaults: applied beneath toml/env/args. The one-liner must be
+# pleasant in development and hardened in production.
+_PROFILE_DEFAULTS: dict[Environment, dict[str, Any]] = {
+    "development": {
+        "debug": True,
+        "logging": {"level": "DEBUG", "format": "console"},
+        "security": {"hsts": False, "https_redirect": False},
+        "errors": {"include_debug_details": True},
+    },
+    "staging": {
+        "logging": {"format": "json"},
+    },
+    "production": {
+        "debug": False,
+        "logging": {"format": "json"},
+        "security": {"hsts": True},
+        "errors": {"include_debug_details": False},
+    },
+}
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in override.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        raise ProdKitConfigError(f"Invalid TOML in {path}: {exc}") from exc
+    # Accept both flat sections and a [prodkit] table for top-level keys.
+    prodkit_table = data.pop("prodkit", {})
+    if not isinstance(prodkit_table, dict):
+        raise ProdKitConfigError(f"[prodkit] in {path} must be a table")
+    return _deep_merge(data, prodkit_table)
+
+
+def _parse_env_value(raw: str) -> Any:
+    lowered = raw.strip().lower()
+    if lowered in {"true", "1", "yes", "on"}:
+        return True
+    if lowered in {"false", "0", "no", "off"}:
+        return False
+    if "," in raw:
+        return [item.strip() for item in raw.split(",") if item.strip()]
+    return raw
+
+
+def _load_env(environ: dict[str, str]) -> dict[str, Any]:
+    """PRODKIT_DEBUG=false → {"debug": False};
+    PRODKIT_LOGGING__LEVEL=DEBUG → {"logging": {"level": "DEBUG"}}."""
+    result: dict[str, Any] = {}
+    for key, raw in environ.items():
+        if not key.startswith(_ENV_PREFIX):
+            continue
+        path = key[len(_ENV_PREFIX) :].lower().split("__")
+        cursor = result
+        for part in path[:-1]:
+            cursor = cursor.setdefault(part, {})
+            if not isinstance(cursor, dict):
+                raise ProdKitConfigError(f"Conflicting environment variable: {key}")
+        cursor[path[-1]] = _parse_env_value(raw)
+    return result
+
+
+def _format_validation_error(exc: ValidationError) -> str:
+    lines = ["Invalid ProdKit configuration:"]
+    for err in exc.errors():
+        location = ".".join(str(part) for part in err["loc"]) or "<root>"
+        lines.append(f"  - {location}: {err['msg']}")
+    return "\n".join(lines)
+
+
+def resolve_config(
+    overrides: dict[str, Any] | None = None,
+    *,
+    toml_path: Path | str = "prodkit.toml",
+    environ: dict[str, str] | None = None,
+) -> ProdKitConfig:
+    """Resolve configuration from all layers and validate it."""
+    environ = dict(os.environ) if environ is None else environ
+    overrides = {k: v for k, v in (overrides or {}).items() if v is not None}
+
+    toml_layer = _load_toml(Path(toml_path))
+    env_layer = _load_env(environ)
+
+    # Environment must be decided first — it selects the profile defaults
+    # that sit *under* every other layer.
+    env_name = (
+        overrides.get("environment")
+        or env_layer.get("environment")
+        or toml_layer.get("environment", "production")
+    )
+    if env_name not in _PROFILE_DEFAULTS:
+        raise ProdKitConfigError(
+            f"Unknown environment {env_name!r}; expected one of: "
+            + ", ".join(sorted(_PROFILE_DEFAULTS))
+        )
+
+    merged = _PROFILE_DEFAULTS[env_name]
+    for layer in (toml_layer, env_layer, overrides):
+        merged = _deep_merge(merged, layer)
+    merged["environment"] = env_name
+
+    try:
+        config = ProdKitConfig(**merged)
+    except ValidationError as exc:
+        raise ProdKitConfigError(_format_validation_error(exc)) from exc
+
+    _check_production_safety(config)
+    return config
+
+
+def _check_production_safety(config: ProdKitConfig) -> None:
+    """Refuse configurations that would silently weaken a production deployment."""
+    if config.environment != "production":
+        return
+    problems: list[str] = []
+    if config.debug:
+        problems.append("debug=True is not allowed in production")
+    if config.errors.include_debug_details:
+        problems.append("errors.include_debug_details=True would leak tracebacks in production")
+    if config.cors.enabled and config.cors.allow_credentials and "*" in config.cors.origins:
+        problems.append(
+            "cors: origins=['*'] with allow_credentials=True allows any site to make "
+            "authenticated requests; list explicit origins instead"
+        )
+    if problems:
+        raise ProdKitConfigError(
+            "Unsafe production configuration:\n" + "\n".join(f"  - {p}" for p in problems)
+        )

prodkit/core/context.py

@@ -0,0 +1,53 @@
+"""The Context object handed to every plugin hook."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from prodkit.core.event_bus import EventBus
+from prodkit.core.registry import Registry
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from prodkit.core.config import ProdKitConfig
+
+
+@dataclass
+class MiddlewareSpec:
+    """A deferred middleware registration; the kernel sorts these by priority
+    (ascending = outermost first) before applying them to the app."""
+
+    cls: type
+    priority: int
+    options: dict[str, Any] = field(default_factory=dict)
+    plugin: str = ""
+
+
+class Context:
+    """Everything a plugin may touch: the app, config, registry, and events."""
+
+    def __init__(self, app: FastAPI, config: ProdKitConfig) -> None:
+        self.app = app
+        self.config = config
+        self.registry = Registry()
+        self.events = EventBus()
+        self._middleware: list[MiddlewareSpec] = []
+        self._current_plugin: str = ""
+
+    def add_middleware(self, cls: type, *, priority: int, **options: Any) -> None:
+        """Register middleware with an explicit priority.
+
+        Lower priority = outermost (runs first on requests, last on responses).
+        Built-in priorities: request-id=100, logging=200, security=400,
+        cors=500, compression=700.
+        """
+        self._middleware.append(
+            MiddlewareSpec(
+                cls=cls, priority=priority, options=options, plugin=self._current_plugin
+            )
+        )
+
+    def middleware_specs(self) -> list[MiddlewareSpec]:
+        return list(self._middleware)

prodkit/core/event_bus.py

@@ -0,0 +1,42 @@
+"""Minimal in-process pub/sub for cross-plugin signals."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Callable
+from typing import Any
+
+logger = logging.getLogger("prodkit")
+
+Handler = Callable[..., Any]
+
+
+class EventBus:
+    """Synchronous-by-default event bus; async handlers are awaited by
+    :meth:`emit_async`. A failing handler is logged and skipped — one plugin's
+    bug must not take down another's event handling."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[Handler]] = {}
+
+    def subscribe(self, event: str, handler: Handler) -> None:
+        self._handlers.setdefault(event, []).append(handler)
+
+    def emit(self, event: str, **payload: Any) -> None:
+        for handler in self._handlers.get(event, []):
+            if inspect.iscoroutinefunction(handler):
+                raise TypeError(f"Handler {handler!r} for {event!r} is async; use emit_async()")
+            try:
+                handler(**payload)
+            except Exception:
+                logger.exception("Event handler failed for event %r", event)
+
+    async def emit_async(self, event: str, **payload: Any) -> None:
+        for handler in self._handlers.get(event, []):
+            try:
+                result = handler(**payload)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:
+                logger.exception("Event handler failed for event %r", event)

prodkit/core/exceptions.py

@@ -0,0 +1,23 @@
+"""ProdKit exception hierarchy."""
+
+from __future__ import annotations
+
+
+class ProdKitError(Exception):
+    """Base class for all ProdKit errors."""
+
+
+class ProdKitConfigError(ProdKitError):
+    """Raised when configuration is invalid. Aborts boot with a clear message."""
+
+
+class PluginError(ProdKitError):
+    """Raised when a plugin misbehaves (bad contract, failed hook)."""
+
+
+class PluginDependencyError(PluginError):
+    """Raised when plugin dependencies are missing or cyclic."""
+
+
+class ServiceNotFoundError(ProdKitError):
+    """Raised when a requested service is not in the registry."""

prodkit/core/lifecycle.py

@@ -0,0 +1,54 @@
+"""Lifespan composition: ProdKit startup wraps the user's existing lifespan.
+
+Order guarantee:
+    plugin startup (dependency order)
+        → user lifespan enter
+            → requests
+        → user lifespan exit
+    plugin shutdown (reverse order, LIFO)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator, Callable
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from prodkit.contracts.plugin import Plugin
+    from prodkit.core.context import Context
+
+logger = logging.getLogger("prodkit")
+
+
+def compose_lifespan(
+    app: FastAPI, ctx: Context, plugins: list[Plugin]
+) -> Callable[[FastAPI], Any]:
+    existing_lifespan = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def lifespan(app_: FastAPI) -> AsyncIterator[Any]:
+        async with AsyncExitStack() as stack:
+            started: list[Plugin] = []
+
+            async def _shutdown_all() -> None:
+                for plugin in reversed(started):
+                    try:
+                        await plugin.shutdown(ctx)
+                    except Exception:
+                        # One plugin's failing shutdown must not prevent the
+                        # rest from releasing their resources.
+                        logger.exception("Shutdown failed for plugin %r", plugin.name)
+
+            stack.push_async_callback(_shutdown_all)
+            for plugin in plugins:
+                await plugin.startup(ctx)
+                started.append(plugin)
+
+            state = await stack.enter_async_context(existing_lifespan(app_))
+            yield state
+
+    return lifespan

prodkit/core/plugin_manager.py

@@ -0,0 +1,52 @@
+"""Plugin collection, validation, and dependency-ordered activation."""
+
+from __future__ import annotations
+
+from graphlib import CycleError, TopologicalSorter
+
+from prodkit.contracts.plugin import Plugin
+from prodkit.core.exceptions import PluginDependencyError, PluginError
+
+
+class PluginManager:
+    """Validates plugins and produces a deterministic activation order via
+    topological sort of their ``requires`` declarations."""
+
+    def __init__(self, plugins: list[Plugin]) -> None:
+        self._validate(plugins)
+        self.plugins = self._sort(plugins)
+
+    @staticmethod
+    def _validate(plugins: list[Plugin]) -> None:
+        seen: set[str] = set()
+        for plugin in plugins:
+            if not isinstance(plugin, Plugin):
+                raise PluginError(f"{plugin!r} does not implement the ProdKit Plugin contract")
+            if not plugin.name:
+                raise PluginError(f"{type(plugin).__name__} has no 'name' set")
+            if plugin.name in seen:
+                raise PluginError(f"Duplicate plugin name: {plugin.name!r}")
+            seen.add(plugin.name)
+
+    @staticmethod
+    def _sort(plugins: list[Plugin]) -> list[Plugin]:
+        by_name = {plugin.name: plugin for plugin in plugins}
+        graph: dict[str, set[str]] = {}
+        for plugin in plugins:
+            missing = [dep for dep in plugin.requires if dep not in by_name]
+            if missing:
+                raise PluginDependencyError(
+                    f"Plugin {plugin.name!r} requires missing plugin(s): "
+                    + ", ".join(repr(m) for m in missing)
+                )
+            graph[plugin.name] = set(plugin.requires)
+
+        # static_order is deterministic for a fixed insertion order, which we
+        # have (built-ins first, then user plugins in the order given).
+        try:
+            order = list(TopologicalSorter(graph).static_order())
+        except CycleError as exc:
+            raise PluginDependencyError(
+                f"Plugin dependency cycle detected: {exc.args[1]}"
+            ) from exc
+        return [by_name[name] for name in order]