openframe-core 3.3.0__tar.gz → 3.4.0__tar.gz

{openframe_core-3.3.0 → openframe_core-3.4.0}/.github/CHANGELOG.md

@@ -11,6 +11,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v3.4.0 — 2026-09-28
+
+### Added
+
+- **`openframe.core.resilience.CircuitBreakerProxy`** (new module,
+  experimental) — zero-code async circuit breaker. Wraps any object and
+  short-circuits its async methods after `failure_threshold` consecutive
+  failures, raising `AdapterConnectionError` ("circuit open", retryable)
+  immediately instead of letting every caller block until
+  `operation_timeout` on every single call during a sustained outage.
+  Standard closed → open → half-open → closed/open state machine.
+  Mirrors `TracingProxy`'s exact wrapping mechanism (`__getattr__`
+  interception, fresh `getattr` resolution of the wrapped method on every
+  call, sync methods pass through unwrapped) so the two proxies compose
+  predictably — see the module docstring for the recommended composition
+  order (`CircuitBreakerProxy(TracingProxy(repo, ...), ...)`, not the
+  reverse, so a short-circuited call never produces a misleading adapter
+  span). Addresses a real gap: none of the four `openframe-adapters`
+  packages (or anything else in the ecosystem) previously had any
+  resilience pattern beyond "block until timeout, then raise."
+
+### Changed
+
+- **Graduated `PluginRegistry` and `ApplicationBootstrap` from `experimental`
+  to `stable`** (`openframe.core.plugins.registry`, `openframe.core.runtime.bootstrap`,
+  and their respective package `__init__.py` re-exports). Graduation
+  criteria: (1) all 7 `openframe-local-validation-framework` services
+  already depend on both in production-shaped code across multiple
+  releases with no breaking change required of them; (2) v3.3.0's
+  `ApplicationBootstrap.compose()`/`get_all()`/`registry` additions landed
+  as pure additive extensions on top of the existing contract — no
+  breaking change was needed to add meaningful new functionality, which is
+  itself evidence the contract shape is right. This is the first module in
+  `openframe-core` to graduate via an explicit, written criteria set
+  (documented in each module's own docstring) rather than an unstated
+  judgment call — future modules going through the same
+  experimental→stable path should record their own criteria the same way.
+
+---
+
 ## v3.3.0 — 2026-09-28
 
 ### Added
@@ -385,7 +425,8 @@ Dev dependencies: `pytest>=8.0`, `pytest-asyncio>=0.23`, `httpx>=0.27`.
 
 ---
 
-[Unreleased]: https://github.com/openframe-org/openframe-core/compare/v3.3.0...HEAD
+[Unreleased]: https://github.com/openframe-org/openframe-core/compare/v3.4.0...HEAD
+[3.4.0]: https://github.com/openframe-org/openframe-core/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/openframe-org/openframe-core/compare/v3.2.1...v3.3.0
 [3.2.1]: https://github.com/openframe-org/openframe-core/compare/v3.2.0...v3.2.1
 [3.2.0]: https://github.com/openframe-org/openframe-core/compare/v3.1.0...v3.2.0

{openframe_core-3.3.0 → openframe_core-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openframe-core
-Version: 3.3.0
+Version: 3.4.0
 Summary: OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-core
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-core/

{openframe_core-3.3.0 → openframe_core-3.4.0}/openframe/core/plugins/__init__.py

@@ -9,10 +9,10 @@ plugin protocol. This package re-exports the ``ports`` types
 :class:`~openframe.core.plugins.registry.PluginRegistry` operates on for
 convenience, plus the registry itself.
 
-All symbols are **experimental** in v3.0 and will stabilise based on real
-usage.
+Stable as of v3.3.0 — see ``PluginRegistry``'s own module docstring
+(``openframe.core.plugins.registry``) for the graduation rationale.
 
-.. stability: experimental
+.. stability: stable
 """
 from __future__ import annotations
 

{openframe_core-3.3.0 → openframe_core-3.4.0}/openframe/core/plugins/registry.py

@@ -17,10 +17,14 @@ correct shutdown ordering (ports then ``shutdown_telemetry()``). Use
 initialization order or are building a framework layer on top of
 openframe-core.
 
-All symbols are **experimental** in v3.0.
+Stable as of v3.3.0 — graduated from experimental after all 7
+``openframe-local-validation-framework`` services proved it in
+production-shaped code across multiple releases with no breaking change,
+and the v3.3.0 ``ApplicationBootstrap.compose()``/``get_all()``/``registry``
+additions landed as pure additive extensions on top of this contract,
+confirming the shape was already right.
 
-.. stability: experimental
-   Experimental — API may change or be removed in any version.
+.. stability: stable
 
 Dependency order:
     ports            → (apex; no plugins/registry-side imports)
@@ -52,7 +56,7 @@ if TYPE_CHECKING:
 
 __all__ = ["PluginRegistry"]
 
-__stability__ = "experimental"
+__stability__ = "stable"
 
 _log = logging.getLogger(__name__)
 
@@ -75,7 +79,7 @@ class PluginRegistry:
     control over initialization order, or when building a framework layer
     that manages the registry lifecycle itself.
 
-    .. stability: experimental
+    .. stability: stable
 
     Direct usage::
 

openframe_core-3.4.0/openframe/core/resilience/__init__.py

@@ -0,0 +1,44 @@
+"""
+openframe/core/resilience/
+============================
+Resilience patterns for the OpenFrame ecosystem.
+
+Modules
+-------
+``CircuitBreakerProxy``
+    Zero-code async circuit breaker. Wraps any object and short-circuits
+    its async methods after a run of consecutive failures, without
+    requiring the adapter or service layer to know it exists. Mirrors
+    ``openframe.core.tracing.TracingProxy``'s wrapping mechanism, so the
+    two proxies compose predictably.
+
+Usage::
+
+    from openframe.core.resilience import CircuitBreakerProxy
+
+    raw_repo = PostgresRepository(settings)
+    guarded_repo = CircuitBreakerProxy(raw_repo, failure_threshold=5, reset_timeout=30.0)
+    # After 5 consecutive failures, calls raise AdapterConnectionError
+    # ("circuit open") immediately instead of blocking on operation_timeout.
+
+Composing with ``TracingProxy`` — prefer wrapping the traced object, not
+the other way around, so a short-circuited call never produces a
+misleading adapter span for a call that never reached the adapter::
+
+    from openframe.core.tracing import TracingProxy
+
+    traced = TracingProxy(raw_repo, prefix="repository.item")
+    guarded = CircuitBreakerProxy(traced, failure_threshold=5, reset_timeout=30.0)
+
+.. stability: experimental
+   New in v3.4.0. Experimental — API may change based on real usage,
+   consistent with how ``ApplicationBootstrap``/``PluginRegistry`` started
+   experimental and graduated once proven (see their own module docstrings).
+"""
+from __future__ import annotations
+
+from openframe.core.resilience.circuit_breaker import CircuitBreakerProxy, CircuitState
+
+__all__ = ["CircuitBreakerProxy", "CircuitState"]
+
+__stability__ = "experimental"

openframe_core-3.4.0/openframe/core/resilience/circuit_breaker.py

@@ -0,0 +1,260 @@
+"""
+openframe/core/resilience/circuit_breaker.py
+===============================================
+Generic async circuit breaker for the OpenFrame ecosystem.
+
+``CircuitBreakerProxy`` wraps any object and short-circuits its async
+methods after a run of consecutive failures, giving a struggling backend
+time to recover instead of every caller blocking until ``operation_timeout``
+on every single call. Neither the wrapped adapter nor the service layer
+need to know the circuit breaker exists.
+
+Mirrors :class:`~openframe.core.tracing.proxy.TracingProxy`'s exact
+wrapping mechanism (``__getattr__`` interception, ``object.__setattr__``
+for the proxy's own state, fresh ``getattr`` resolution of the wrapped
+method on every call — never a stale snapshot) so the two proxies compose
+predictably and a reader who understands one understands the other.
+
+State machine (per proxy instance, per wrapped object — not global)::
+
+    CLOSED --[failure_threshold consecutive failures]--> OPEN
+    OPEN --[reset_timeout elapsed]--> HALF_OPEN
+    HALF_OPEN --[probe call succeeds]--> CLOSED
+    HALF_OPEN --[probe call fails]--> OPEN (timer restarts)
+
+Known simplification: multiple concurrent callers arriving right at the
+``reset_timeout`` boundary can all be let through as "probes" during the
+same half-open window (this implementation does not cap in-flight probes
+at exactly one). In practice this only matters under high concurrent call
+volume at the exact moment the circuit would reopen or close — it does not
+affect the CLOSED/OPEN transitions, which are strictly threshold- and
+timeout-gated.
+
+Dependency order: imports ``openframe.core.exceptions`` (lowest layer) only.
+No dependency on ``telemetry``/``tracing`` — composes with ``TracingProxy``
+by wrapping, not by sharing state.
+
+.. stability: experimental
+   New in v3.4.0. API may change based on real usage.
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import time
+from collections.abc import Callable
+from enum import Enum, auto
+from typing import Any
+
+from openframe.core.exceptions import AdapterConnectionError
+
+__all__ = ["CircuitBreakerProxy", "CircuitState"]
+
+__stability__ = "experimental"
+
+_log = logging.getLogger(__name__)
+
+
+class CircuitState(Enum):
+    """Lifecycle state of a single :class:`CircuitBreakerProxy` instance."""
+
+    CLOSED = auto()
+    OPEN = auto()
+    HALF_OPEN = auto()
+
+
+class CircuitBreakerProxy:
+    """
+    Generic async circuit breaker.
+
+    Wraps any object and intercepts every async method call. After
+    ``failure_threshold`` consecutive failures, the circuit opens: further
+    calls raise :class:`~openframe.core.exceptions.AdapterConnectionError`
+    immediately (retryable) without invoking the wrapped method, for
+    ``reset_timeout`` seconds. After that window elapses, the next call is
+    let through as a probe (half-open); if it succeeds the circuit closes
+    and failures reset to zero, if it fails the circuit reopens and the
+    timer restarts.
+
+    Reconnect safety:
+        Like ``TracingProxy``, the wrapped method is resolved fresh via
+        ``getattr`` on every invocation — never captured as a snapshot.
+
+    Sync methods:
+        Pass through unwrapped, uncounted — the circuit breaker only
+        applies to async methods, matching ``TracingProxy``'s convention.
+
+    Composing with ``TracingProxy``:
+        Order matters. ``TracingProxy(CircuitBreakerProxy(repo, ...), ...)``
+        traces the circuit breaker's own short-circuit raises as failed
+        spans. ``CircuitBreakerProxy(TracingProxy(repo, ...), ...)`` counts
+        failures on the traced calls but never creates a span for a
+        short-circuited call (the wrapped ``TracingProxy`` is never
+        reached while open). Prefer the latter — a call that never reached
+        the adapter is not an adapter span.
+
+    .. stability: experimental
+
+    Usage::
+
+        raw = PostgresRepository(settings)
+        guarded = CircuitBreakerProxy(raw, failure_threshold=5, reset_timeout=30.0)
+        # After 5 consecutive failures, calls raise AdapterConnectionError
+        # ("circuit open") immediately for 30s instead of blocking on
+        # operation_timeout each time.
+    """
+
+    def __init__(
+        self,
+        wrapped: object,
+        *,
+        failure_threshold: int = 5,
+        reset_timeout: float = 30.0,
+        name: str = "circuit-breaker",
+    ) -> None:
+        """
+        Initialise the proxy.
+
+        Args:
+            wrapped: The object whose async methods will be guarded.
+            failure_threshold: Consecutive failures (per method call,
+                across all methods on this proxy) before the circuit opens.
+                Must be >= 1.
+            reset_timeout: Seconds the circuit stays open before a probe
+                call is allowed through (half-open). Must be > 0.
+            name: Used as the ``adapter`` field on the
+                ``AdapterConnectionError`` raised while open, and in log
+                messages — e.g. ``"postgres-primary"``.
+
+        Raises:
+            ValueError: ``failure_threshold`` < 1 or ``reset_timeout`` <= 0.
+        """
+        if failure_threshold < 1:
+            raise ValueError(f"failure_threshold must be >= 1, got {failure_threshold!r}")
+        if reset_timeout <= 0:
+            raise ValueError(f"reset_timeout must be > 0, got {reset_timeout!r}")
+
+        object.__setattr__(self, "_wrapped", wrapped)
+        object.__setattr__(self, "_failure_threshold", failure_threshold)
+        object.__setattr__(self, "_reset_timeout", reset_timeout)
+        object.__setattr__(self, "_name", name)
+        object.__setattr__(self, "_cache", {})
+        object.__setattr__(self, "_state", CircuitState.CLOSED)
+        object.__setattr__(self, "_consecutive_failures", 0)
+        object.__setattr__(self, "_opened_at", 0.0)
+        # Guards state transitions against concurrent callers racing on
+        # the same proxy instance (e.g. two coroutines calling .get()
+        # concurrently while the circuit is deciding whether to open).
+        object.__setattr__(self, "_lock", asyncio.Lock())
+
+    @property
+    def state(self) -> CircuitState:
+        """Current circuit state. Read-only — for observability/tests."""
+        return object.__getattribute__(self, "_state")
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Intercept attribute access.
+
+        Returns a cached guarded closure for async methods, or the raw
+        attribute for sync methods and non-callable attributes.
+        """
+        cache: dict[str, Callable[..., Any]] = object.__getattribute__(self, "_cache")
+        if name in cache:
+            return cache[name]
+
+        wrapped = object.__getattribute__(self, "_wrapped")
+        probe = getattr(wrapped, name)
+
+        if not inspect.iscoroutinefunction(probe):
+            return probe
+
+        async def _guarded(*args: Any, **kwargs: Any) -> Any:
+            await self._before_call(name)
+            try:
+                current = getattr(object.__getattribute__(self, "_wrapped"), name)
+                result = await current(*args, **kwargs)
+            except Exception:
+                await self._on_failure(name)
+                raise
+            else:
+                await self._on_success(name)
+                return result
+
+        cache[name] = _guarded
+        return _guarded
+
+    async def _before_call(self, method_name: str) -> None:
+        """
+        Called before every guarded invocation.
+
+        Raises ``AdapterConnectionError`` immediately if the circuit is
+        open and ``reset_timeout`` has not yet elapsed. If the timeout has
+        elapsed, transitions to half-open and lets exactly this one call
+        through as a probe.
+        """
+        lock: asyncio.Lock = object.__getattribute__(self, "_lock")
+        async with lock:
+            state: CircuitState = object.__getattribute__(self, "_state")
+            if state is not CircuitState.OPEN:
+                return
+
+            opened_at: float = object.__getattribute__(self, "_opened_at")
+            reset_timeout: float = object.__getattribute__(self, "_reset_timeout")
+            if time.monotonic() - opened_at < reset_timeout:
+                name: str = object.__getattribute__(self, "_name")
+                raise AdapterConnectionError(
+                    f"circuit open — {name}.{method_name} short-circuited "
+                    f"after repeated failures; retry after "
+                    f"{reset_timeout - (time.monotonic() - opened_at):.1f}s",
+                    adapter=name,
+                    operation=method_name,
+                )
+
+            # reset_timeout elapsed — allow exactly this call through as a probe.
+            object.__setattr__(self, "_state", CircuitState.HALF_OPEN)
+            _log.info("CircuitBreakerProxy %r half-open — probing %r", object.__getattribute__(self, "_name"), method_name)
+
+    async def _on_success(self, method_name: str) -> None:
+        """Reset failure count and close the circuit on any success."""
+        lock: asyncio.Lock = object.__getattribute__(self, "_lock")
+        async with lock:
+            object.__setattr__(self, "_consecutive_failures", 0)
+            if object.__getattribute__(self, "_state") is not CircuitState.CLOSED:
+                object.__setattr__(self, "_state", CircuitState.CLOSED)
+                _log.info(
+                    "CircuitBreakerProxy %r closed — %r succeeded",
+                    object.__getattribute__(self, "_name"),
+                    method_name,
+                )
+
+    async def _on_failure(self, method_name: str) -> None:
+        """
+        Count the failure. Opens the circuit if the threshold is reached
+        (from closed) or immediately re-opens it (from half-open, where a
+        single probe failure is sufficient — the backend is still down).
+        """
+        lock: asyncio.Lock = object.__getattribute__(self, "_lock")
+        async with lock:
+            state: CircuitState = object.__getattribute__(self, "_state")
+            name: str = object.__getattribute__(self, "_name")
+
+            if state is CircuitState.HALF_OPEN:
+                object.__setattr__(self, "_state", CircuitState.OPEN)
+                object.__setattr__(self, "_opened_at", time.monotonic())
+                _log.warning(
+                    "CircuitBreakerProxy %r re-opened — probe %r failed", name, method_name
+                )
+                return
+
+            failures = object.__getattribute__(self, "_consecutive_failures") + 1
+            object.__setattr__(self, "_consecutive_failures", failures)
+            threshold: int = object.__getattribute__(self, "_failure_threshold")
+            if failures >= threshold:
+                object.__setattr__(self, "_state", CircuitState.OPEN)
+                object.__setattr__(self, "_opened_at", time.monotonic())
+                _log.warning(
+                    "CircuitBreakerProxy %r opened — %d consecutive failures (last: %r)",
+                    name, failures, method_name,
+                )

{openframe_core-3.3.0 → openframe_core-3.4.0}/openframe/core/runtime/__init__.py

@@ -12,7 +12,10 @@ See ``openframe.core.plugins.PluginRegistry`` if you need fine-grained
 control over initialization order or want to manage the registry lifecycle
 directly without the composition abstraction.
 
-.. stability: experimental
+Stable as of v3.3.0 — see ``ApplicationBootstrap``'s own module docstring
+(``openframe.core.runtime.bootstrap``) for the graduation rationale.
+
+.. stability: stable
 """
 from __future__ import annotations
 

{openframe_core-3.3.0 → openframe_core-3.4.0}/openframe/core/runtime/bootstrap.py

@@ -26,10 +26,14 @@ intentionally no separate ``PluginRegistry``-direct or ``deps.py``+``lru_cache``
 like when hand-rolled, minus the correct shutdown ordering tier 1-3 give you
 for free.
 
-All symbols are **experimental** in v3.0.
+Stable as of v3.3.0 — graduated from experimental after all 7
+``openframe-local-validation-framework`` services proved it in
+production-shaped code across multiple releases with no breaking change,
+and the v3.3.0 ``compose()``/``get_all()``/``registry`` additions landed
+as pure additive extensions on top of this contract, confirming the shape
+was already right.
 
-.. stability: experimental
-   Experimental — API may change or be removed in any version.
+.. stability: stable
 
 Dependency order:
     ports             → (apex)
@@ -49,7 +53,7 @@ if TYPE_CHECKING:
 
 __all__ = ["ApplicationBootstrap"]
 
-__stability__ = "experimental"
+__stability__ = "stable"
 
 
 class ApplicationBootstrap:
@@ -63,7 +67,7 @@ class ApplicationBootstrap:
     the OTel SDK is flushed via ``shutdown_telemetry()`` so no spans are
     silently dropped at process exit.
 
-    .. stability: experimental
+    .. stability: stable
 
     **Tier 1 — no subclass, one or a few ports**::
 

{openframe_core-3.3.0 → openframe_core-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openframe-core"
-version = "3.3.0"
+version = "3.4.0"
 description = "OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root."
 readme = "README.md"
 requires-python = ">=3.11"