resilience-kit 0.1.0__py3-none-any.whl

resilience_kit/__init__.py

@@ -0,0 +1,123 @@
+"""``resilience-kit`` — framework-agnostic Python resilience kernel.
+
+Public surface:
+
+* Decorators — :func:`retry`, :func:`retry_on_failure`,
+  :func:`circuit_breaker`, :func:`resilient`.
+* Registry — :class:`ResilienceRegistry`, :data:`registry`.
+* Exceptions — see :mod:`resilience_kit.exceptions`.
+* SSRF guard — :func:`resolve_and_validate`, :func:`assert_public_url`,
+  :func:`assert_allowed_url` (M3).
+* HTTP client — :class:`AsyncAPIClient`, :func:`pinned` (M3, requires
+  the ``http`` extra; imported lazily so users without the extra still
+  ``import resilience_kit``).
+* Field crypto — :class:`FernetCipher` (M3, requires the ``crypto``
+  extra; imported lazily).
+
+Backends and adapters land in later milestones (see ``docs/ROADMAP.md``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from resilience_kit._version import __version__
+from resilience_kit.audit import AuditEvent, log_inbound, log_outbound
+from resilience_kit.decorators import circuit_breaker, resilient
+from resilience_kit.exceptions import (
+    HTTP_STATUS_MAP,
+    DecryptionError,
+    ExternalServiceError,
+    ExternalTimeoutError,
+    MissingExtraError,
+    RateLimitError,
+    RepositoryError,
+    ResilienceKitError,
+    ServiceUnavailableError,
+    TransientError,
+    UnknownBackendError,
+    ValidationError,
+    http_status_for,
+)
+from resilience_kit.health import HealthAggregate, HealthStatus, health_snapshot
+from resilience_kit.registry import ResilienceRegistry, registry
+from resilience_kit.retry import retry, retry_on_failure
+from resilience_kit.ssrf import (
+    assert_allowed_url,
+    assert_public_url,
+    resolve_and_validate,
+)
+
+if TYPE_CHECKING:
+    from resilience_kit.crypto import FernetCipher
+    from resilience_kit.http_client import AsyncAPIClient, pinned
+
+# Lazy re-exports for optional-extra-gated names.
+# Importing the kit without ``[http]`` / ``[crypto]`` must not fail.
+_LAZY: dict[str, tuple[str, str]] = {
+    "AsyncAPIClient": ("resilience_kit.http_client", "AsyncAPIClient"),
+    "pinned": ("resilience_kit.http_client", "pinned"),
+    "FernetCipher": ("resilience_kit.crypto", "FernetCipher"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve optional-extra-gated names lazily on first access.
+
+    Importing :mod:`resilience_kit` itself must not require the
+    ``[http]`` or ``[crypto]`` extras. The names below are resolved at
+    attribute-access time; missing the extra surfaces as
+    :class:`MissingExtraError` (raised by the submodule's import guard).
+
+    Args:
+        name: Attribute name being accessed.
+
+    Returns:
+        The resolved attribute.
+
+    Raises:
+        AttributeError: ``name`` is not exposed by this package.
+    """
+    if name in _LAZY:
+        module_path, attr = _LAZY[name]
+        import importlib  # noqa: PLC0415
+
+        return getattr(importlib.import_module(module_path), attr)
+    msg = f"module 'resilience_kit' has no attribute {name!r}"
+    raise AttributeError(msg)
+
+
+__all__ = [
+    "HTTP_STATUS_MAP",
+    "AsyncAPIClient",
+    "AuditEvent",
+    "DecryptionError",
+    "ExternalServiceError",
+    "ExternalTimeoutError",
+    "FernetCipher",
+    "HealthAggregate",
+    "HealthStatus",
+    "MissingExtraError",
+    "RateLimitError",
+    "RepositoryError",
+    "ResilienceKitError",
+    "ResilienceRegistry",
+    "ServiceUnavailableError",
+    "TransientError",
+    "UnknownBackendError",
+    "ValidationError",
+    "__version__",
+    "assert_allowed_url",
+    "assert_public_url",
+    "circuit_breaker",
+    "health_snapshot",
+    "http_status_for",
+    "log_inbound",
+    "log_outbound",
+    "pinned",
+    "registry",
+    "resilient",
+    "resolve_and_validate",
+    "retry",
+    "retry_on_failure",
+]

resilience_kit/_providers.py

@@ -0,0 +1,104 @@
+"""Shared backend-provider resolution chain (LLD §3).
+
+One helper, used by every swappable subsystem (cache / breaker / throttle /
+audit / sanitizer / metrics / settings-source). Resolution order:
+
+1. Explicit callable / instance — return as-is.
+2. ``"pkg.mod:Class"`` importable string — import + instantiate.
+3. ``name`` matches an entry point in the named group — load + instantiate.
+4. ``name`` matches one of the kit's builtin names — instantiate.
+5. Otherwise raise :class:`UnknownBackendError` with the list of available
+   names so the failure message itself tells the operator what to set
+   ``RESILIENCE_<SUBSYSTEM>_BACKEND`` to.
+
+Backends gated behind a pip extra raise :class:`MissingExtraError` at
+import time (not first use), so the failure is immediate and the hint is
+unambiguous.
+
+Precedence note (ADR 0004): entry points are checked **before** builtins
+(step 3 before step 4). A third-party package that publishes an entry
+point with the same name as a kit builtin therefore **shadows** the
+builtin. This is intentional — it lets a third party ship a drop-in
+replacement for ``memory`` / ``noop`` / ``stdlib_logging`` without
+forking the kit — but it is also a footgun for accidental name
+collisions. Operators should namespace third-party backend names
+(``acme-redis``, not ``redis``) to avoid surprises. Documented in
+``docs/LLD.md`` §3 and ``docs/adr/0004-entry-points-for-third-party-backends.md``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from resilience_kit.exceptions import UnknownBackendError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+T = TypeVar("T")
+
+
+def resolve_provider(
+    *,
+    group: str,
+    name: str | T | Callable[..., T],
+    builtins: Mapping[str, Callable[..., T]],
+    factory_kwargs: Mapping[str, Any] | None = None,
+) -> T:
+    """Resolve a backend instance via the 5-step chain in this module's docstring.
+
+    Args:
+        group: Entry-point group queried (e.g. ``"resilience_kit.cache_backends"``).
+        name: Explicit instance / callable, importable ``"mod:Class"`` string,
+            entry-point name, or builtin name.
+        builtins: Mapping of builtin names → callables that produce a backend.
+        factory_kwargs: Optional kwargs threaded into the factory call when
+            ``name`` resolves to a callable (string / entry-point / builtin
+            cases). Pre-built instances pass through unchanged.
+
+    Returns:
+        The resolved backend.
+
+    Raises:
+        UnknownBackendError: ``name`` is a string but does not resolve via
+            entry-point or builtin.
+        TypeError: ``name`` is a string with ``":"`` but the import target
+            is not a callable.
+    """
+    kwargs: Mapping[str, Any] = factory_kwargs or {}
+
+    # 1. Explicit instance — anything that is not a string is treated as
+    # either a ready-made instance or a no-arg factory the caller wants to
+    # use as-is.
+    if not isinstance(name, str):
+        return name(**kwargs) if callable(name) else name
+
+    # 2. Importable string "pkg.mod:Class".
+    if ":" in name:
+        module_path, _, attr = name.partition(":")
+        module = importlib.import_module(module_path)
+        target = getattr(module, attr)
+        if not callable(target):
+            raise TypeError(
+                f"Importable string {name!r} resolved to a non-callable "
+                f"({type(target).__name__}); expected a class or factory.",
+            )
+        return target(**kwargs)  # type: ignore[no-any-return]
+
+    # 3. Entry-point lookup.
+    for ep in entry_points(group=group):
+        if ep.name == name:
+            target = ep.load()
+            return target(**kwargs)  # type: ignore[no-any-return]
+
+    # 4. Builtin.
+    if name in builtins:
+        return builtins[name](**kwargs)
+
+    # 5. Fail with the list of options.
+    available = sorted(
+        {*builtins.keys(), *(ep.name for ep in entry_points(group=group))},
+    )
+    raise UnknownBackendError(group=group, name=name, available=available)

resilience_kit/_version.py

@@ -0,0 +1,7 @@
+"""Single source of truth for the package version.
+
+Read by ``hatchling`` at build time (see ``[tool.hatch.version]`` in
+``pyproject.toml``) and re-exported as ``resilience_kit.__version__``.
+"""
+
+__version__ = "0.1.0"

resilience_kit/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Framework adapters.
+
+Each adapter is pure glue between a web framework's lifecycle hooks and
+the kit's framework-agnostic primitives (recovery monitor, audit
+dispatcher, health aggregator, middleware, decorators). Adapters never
+hold business logic; if an adapter file grows past ~300 LOC the
+underlying primitive is wrong, not the adapter.
+
+Sub-packages are extras-gated: importing
+``resilience_kit.adapters.fastapi`` (or ``resilience_kit.adapters.django``)
+without the corresponding extra installed raises
+:class:`~resilience_kit.exceptions.MissingExtraError`.
+"""

resilience_kit/adapters/_envelope.py

@@ -0,0 +1,135 @@
+"""Framework-agnostic envelope builder for kit exceptions.
+
+Both the FastAPI and Django adapters need to translate a
+:class:`~resilience_kit.exceptions.ResilienceKitError` into
+
+* a JSON-serialisable body dict,
+* an HTTP status code,
+* a header dict (with ``Retry-After`` + ``X-RateLimit-*`` for rate-limit errors).
+
+Before this module they each built that triple inline, producing duplicated
+code (FastAPI :func:`_envelope` and Django :func:`_build_response` had the same
+body, severity, and header logic). The duplication is consolidated here so a
+third adapter (Litestar / Flask / Starlette-only) gets the behaviour for free
+and consumers can call :func:`from_exception` directly to wrap kit exceptions
+into a non-kit envelope shape — the M7 FastAPI dogfooding fix for the
+two-handler envelope collision (MIGRATION §10.2 "Option 3").
+
+The default envelope shape (``envelope_cls=None``) is **byte-for-byte
+identical** to what both adapters emitted before the refactor — LLD §11's
+``{error_code, message, details}``. The ``envelope_cls`` projection is opt-in
+and only consulted when a consumer hands in their own pydantic model.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from resilience_kit.context import request_id
+from resilience_kit.exceptions import RateLimitError, ResilienceKitError, http_status_for
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from pydantic import BaseModel
+
+# Field-name aliases recognised when projecting onto a consumer envelope model.
+# Order matters — the first match wins. If a target model declares more than
+# one, only the first is filled.
+_ERROR_CODE_ALIASES = ("error_code", "code", "error")
+_MESSAGE_ALIASES = ("message", "detail")
+_DETAILS_ALIASES = ("details", "errors")
+
+
+def from_exception(
+    exc: ResilienceKitError,
+    *,
+    envelope_cls: type[BaseModel] | None = None,
+    extra_headers: Mapping[str, str] | None = None,
+) -> tuple[dict[str, Any], int, dict[str, str]]:
+    """Build ``(body, status, headers)`` for a kit exception.
+
+    Args:
+        exc: Any :class:`ResilienceKitError` subclass instance.
+        envelope_cls: Optional pydantic model whose field names should
+            receive the projected values. When omitted the body is the
+            locked LLD §11 shape — ``{error_code, message, details}``.
+            When given, the projection looks at ``envelope_cls.model_fields``
+            and writes ``error_code`` onto whichever of ``error_code | code
+            | error`` is declared, ``message`` onto ``message | detail``,
+            and ``details`` onto ``details`` (as a dict) or ``errors`` (as
+            a list of ``{field, message}`` objects, mirroring DRF-style
+            validation envelopes). A ``request_id`` field is filled from
+            the current :data:`resilience_kit.context.request_id` value
+            when present. A ``success`` field is set to ``False``.
+            Other declared fields are left unfilled — the consumer's model
+            defaults / required-field rules decide what happens.
+        extra_headers: Headers the caller wants merged into the response
+            (e.g. CORS, instrumentation). ``Retry-After`` + ``X-RateLimit-*``
+            from :meth:`RateLimitError.response_headers` are always added
+            on top for :class:`RateLimitError`.
+
+    Returns:
+        ``(body, status, headers)`` — the body is a plain dict ready to
+        feed to ``JSONResponse`` / DRF ``Response`` / the consumer's
+        envelope constructor. ``status`` comes from
+        :func:`http_status_for`. ``headers`` is a fresh dict (never the
+        caller's original).
+    """
+    body: dict[str, Any] = {
+        "error_code": exc.error_code,
+        "message": str(exc),
+        "details": dict(exc.details),
+    }
+    status = http_status_for(exc)
+    headers = dict(extra_headers or {})
+    if isinstance(exc, RateLimitError):
+        headers.update(exc.response_headers())
+    if envelope_cls is not None:
+        body = _project_onto_envelope(body, envelope_cls)
+    return body, status, headers
+
+
+def _project_onto_envelope(
+    body: dict[str, Any],
+    envelope_cls: type[BaseModel],
+) -> dict[str, Any]:
+    """Project the canonical body onto whatever field names ``envelope_cls`` declares."""
+    fields = set(envelope_cls.model_fields)
+    out: dict[str, Any] = {}
+
+    code_field = _first_match(_ERROR_CODE_ALIASES, fields)
+    if code_field is not None:
+        out[code_field] = body["error_code"]
+
+    message_field = _first_match(_MESSAGE_ALIASES, fields)
+    if message_field is not None:
+        out[message_field] = body["message"]
+
+    if "details" in fields:
+        out["details"] = body["details"]
+    elif "errors" in fields:
+        out["errors"] = _details_to_error_list(body["details"])
+
+    if "request_id" in fields:
+        out["request_id"] = request_id.get()
+
+    if "success" in fields:
+        out["success"] = False
+
+    return out
+
+
+def _first_match(candidates: tuple[str, ...], fields: set[str]) -> str | None:
+    for c in candidates:
+        if c in fields:
+            return c
+    return None
+
+
+def _details_to_error_list(details: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """Convert a flat ``details`` dict to the ``[{field, message}, ...]`` shape."""
+    return [{"field": k, "message": str(v)} for k, v in details.items()]
+
+
+__all__ = ["from_exception"]

resilience_kit/adapters/django/__init__.py

@@ -0,0 +1,27 @@
+"""Django adapter (ROADMAP M6).
+
+Wires the kit into Django's `AppConfig.ready()` lifecycle, middleware
+chain, DRF throttle classes, DRF exception handler, model fields, and
+management commands. Pure glue; no business logic.
+
+Django is sync-first; the kit is async-first. The bridge lives in
+``apps.py``: a daemon thread owns a private asyncio loop and drives the
+recovery monitor for the lifetime of the worker. ADR 0011 documents
+the bridge in full.
+
+This module exposes the AppConfig path Django expects:
+
+.. code-block:: python
+
+    # settings.py
+    INSTALLED_APPS = [
+        ...,
+        "resilience_kit.adapters.django",
+    ]
+"""
+
+from __future__ import annotations
+
+default_app_config = "resilience_kit.adapters.django.apps.ResilienceConfig"
+
+__all__ = ["default_app_config"]

resilience_kit/adapters/django/apps.py

@@ -0,0 +1,155 @@
+"""Django :class:`AppConfig` for the resilience-kit adapter.
+
+``ResilienceConfig.ready()`` runs once per Django process — twice if the
+autoreloader is active, hence the idempotency guard. It performs three
+jobs:
+
+1. Reads ``settings.RESILIENCE`` (a dict the project supplies) and calls
+   :meth:`ResilienceRegistry.register_service` for each declared
+   service so ``@resilient(name)`` sees the right retry / breaker
+   config.
+
+2. Spawns a daemon thread that owns a private :mod:`asyncio` loop and
+   drives :data:`recovery.monitor`. Django is sync-first so there is no
+   ambient loop the monitor can attach to; the daemon thread bridges
+   that gap. The thread is daemon=True so it dies with the worker —
+   acceptable because the monitor is purely re-probing, never holding
+   un-flushed state. ADR 0011 documents the bridge in detail.
+
+3. Registers an :func:`atexit` hook to call :meth:`monitor.stop` and
+   drain the audit dispatcher on graceful exit. Daemon-thread death on
+   SIGKILL still loses in-flight audit events; the
+   :class:`FireAndForgetDispatcher` design accepts that.
+
+Reading ``settings.RESILIENCE`` lazily inside ``ready()`` (not at
+module import) keeps the adapter importable in projects that do not
+configure it yet, which makes the install a one-liner in
+``INSTALLED_APPS``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import logging
+import threading
+from typing import TYPE_CHECKING, Any
+
+from resilience_kit.exceptions import MissingExtraError
+from resilience_kit.recovery import monitor
+
+try:
+    from django.apps import AppConfig
+except ImportError as exc:  # pragma: no cover
+    raise MissingExtraError("django", "resilience-kit[django]") from exc
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_logger = logging.getLogger("resilience_kit.adapters.django")
+
+_lock = threading.Lock()
+_thread: threading.Thread | None = None
+_loop: asyncio.AbstractEventLoop | None = None
+_shutdown_event: threading.Event | None = None
+
+
+class ResilienceConfig(AppConfig):  # type: ignore[misc]  # django.apps untyped — see mypy.ini
+    """Adapter ``AppConfig`` — registers services and starts the monitor."""
+
+    name = "resilience_kit.adapters.django"
+    label = "resilience_kit"
+    verbose_name = "Resilience kit"
+
+    def ready(self) -> None:
+        """Register services and ensure the recovery thread is running."""
+        from django.conf import settings as django_settings  # noqa: PLC0415
+
+        from resilience_kit.registry import registry  # noqa: PLC0415
+
+        services: Mapping[str, Mapping[str, Any]] = getattr(
+            django_settings,
+            "RESILIENCE",
+            {},
+        ).get("services", {})
+        for name, overrides in services.items():
+            registry.register_service(name, overrides)
+
+        _ensure_monitor_thread()
+
+
+def _ensure_monitor_thread() -> None:
+    """Spawn the daemon thread that owns the monitor's asyncio loop.
+
+    Idempotent — guards against AppConfig.ready() being called twice by
+    the autoreloader.
+    """
+    global _thread, _shutdown_event  # noqa: PLW0603
+    with _lock:
+        if _thread is not None and _thread.is_alive():
+            return
+        _shutdown_event = threading.Event()
+        ready = threading.Event()
+        _thread = threading.Thread(
+            target=_run_loop,
+            args=(ready,),
+            name="resilience_kit.recovery_monitor",
+            daemon=True,
+        )
+        _thread.start()
+        # Block briefly so callers know the loop is up before they
+        # schedule work on it.
+        ready.wait(timeout=2.0)
+        atexit.register(_shutdown_monitor_thread)
+        _logger.info("Resilience monitor thread started.")
+
+
+def _run_loop(ready: threading.Event) -> None:
+    """Body of the daemon thread — owns a private asyncio loop."""
+    global _loop  # noqa: PLW0603
+    loop = asyncio.new_event_loop()
+    _loop = loop
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(_drive_monitor(ready))
+    finally:
+        loop.close()
+
+
+async def _drive_monitor(ready: threading.Event) -> None:
+    """Start the monitor, park until shutdown, then drain audit + stop."""
+    from resilience_kit.audit.factory import get_dispatcher  # noqa: PLC0415
+
+    monitor.start()
+    ready.set()
+    assert _shutdown_event is not None  # set by _ensure_monitor_thread.
+    # Poll the threading.Event without blocking the loop. The 0.5 s
+    # cadence is fast enough for tests and cheap enough for prod.
+    # ASYNC110 suggests asyncio.Event but the signal originates from a
+    # different thread (the atexit hook), so a threading.Event polled
+    # from this loop is the correct primitive.
+    while not _shutdown_event.is_set():  # noqa: ASYNC110
+        await asyncio.sleep(0.5)
+    # Drain audit + stop monitor on this loop BEFORE _run_loop closes
+    # it. Doing this from the atexit hook would post coroutines to a
+    # closed loop.
+    try:
+        await get_dispatcher().aclose(drain_timeout=5.0)
+    except Exception:
+        _logger.exception("Audit dispatcher drain raised during shutdown")
+    await monitor.stop()
+
+
+def _shutdown_monitor_thread() -> None:
+    """Atexit hook: signal the loop thread to drain + stop, then join."""
+    global _thread, _loop, _shutdown_event  # noqa: PLW0603
+    if _shutdown_event is None or _thread is None:
+        return
+    _shutdown_event.set()
+    _thread.join(timeout=8.0)
+    _thread = None
+    _loop = None
+    _shutdown_event = None
+
+
+__all__ = ["ResilienceConfig"]