httpware 0.11.0__tar.gz → 0.13.0__tar.gz

{httpware-0.11.0 → httpware-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.11.0
+Version: 0.13.0
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev

{httpware-0.11.0 → httpware-0.13.0}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.11.0"
+version = "0.13.0"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]

{httpware-0.11.0 → httpware-0.13.0}/src/httpware/client.py

@@ -228,7 +228,7 @@ class AsyncClient:
         """Delegate request construction to the wrapped httpx2.AsyncClient."""
         return self._httpx2_client.build_request(method, url, **kwargs)
 
-    async def _request_with_body(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
+    def _prepare_request(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
         self,
         method: str,
         url: str,
@@ -242,8 +242,7 @@ class AsyncClient:
         content: typing.Any | None = None,
         data: typing.Any | None = None,
         files: typing.Any | None = None,
-        response_model: type[T] | None = None,
-    ) -> httpx2.Response | T:
+    ) -> httpx2.Request:
         kwargs: dict[str, typing.Any] = {}
         if params is not None:
             kwargs["params"] = params
@@ -266,8 +265,70 @@ class AsyncClient:
         request = self._httpx2_client.build_request(method, url, **kwargs)
         if _is_streaming_body_async(content) or _is_streaming_body_async(data) or _is_streaming_body_async(files):
             request.extensions[STREAMING_BODY_MARKER] = True
+        return request
+
+    async def _request_with_body(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T] | None = None,
+    ) -> httpx2.Response | T:
+        request = self._prepare_request(
+            method,
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+        )
         return await self.send(request, response_model=response_model)
 
+    async def _request_with_body_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        request = self._prepare_request(
+            method,
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+        )
+        return await self.send_with_response(request, response_model=response_model)
+
     @typing.overload
     async def get(
         self,
@@ -317,6 +378,29 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    async def get_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a GET request; return (response, decoded body)."""
+        return await self._request_with_body_with_response(
+            "GET",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            response_model=response_model,
+        )
+
     @typing.overload
     async def post(
         self,
@@ -382,6 +466,37 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    async def post_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a POST request; return (response, decoded body)."""
+        return await self._request_with_body_with_response(
+            "POST",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     async def put(
         self,
@@ -447,6 +562,37 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    async def put_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a PUT request; return (response, decoded body)."""
+        return await self._request_with_body_with_response(
+            "PUT",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     async def patch(
         self,
@@ -512,6 +658,37 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    async def patch_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a PATCH request; return (response, decoded body)."""
+        return await self._request_with_body_with_response(
+            "PATCH",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     async def delete(
         self,
@@ -577,6 +754,37 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    async def delete_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a DELETE request; return (response, decoded body)."""
+        return await self._request_with_body_with_response(
+            "DELETE",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     async def head(
         self,
@@ -743,6 +951,38 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    async def request_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a request with an explicit method; return (response, decoded body)."""
+        return await self._request_with_body_with_response(
+            method,
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @contextlib.asynccontextmanager
     async def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
         self,
@@ -1003,7 +1243,7 @@ class Client:
         """Delegate request construction to the wrapped httpx2.Client."""
         return self._httpx2_client.build_request(method, url, **kwargs)
 
-    def _request_with_body(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
+    def _prepare_request(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
         self,
         method: str,
         url: str,
@@ -1017,8 +1257,7 @@ class Client:
         content: typing.Any | None = None,
         data: typing.Any | None = None,
         files: typing.Any | None = None,
-        response_model: type[T] | None = None,
-    ) -> httpx2.Response | T:
+    ) -> httpx2.Request:
         kwargs: dict[str, typing.Any] = {}
         if params is not None:
             kwargs["params"] = params
@@ -1041,8 +1280,70 @@ class Client:
         request = self._httpx2_client.build_request(method, url, **kwargs)
         if _is_streaming_body_sync(content) or _is_streaming_body_sync(data) or _is_streaming_body_sync(files):
             request.extensions[STREAMING_BODY_MARKER] = True
+        return request
+
+    def _request_with_body(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T] | None = None,
+    ) -> httpx2.Response | T:
+        request = self._prepare_request(
+            method,
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+        )
         return self.send(request, response_model=response_model)
 
+    def _request_with_body_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        request = self._prepare_request(
+            method,
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+        )
+        return self.send_with_response(request, response_model=response_model)
+
     @typing.overload
     def get(
         self,
@@ -1092,6 +1393,29 @@ class Client:
             response_model=response_model,
         )
 
+    def get_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a GET request; return (response, decoded body)."""
+        return self._request_with_body_with_response(
+            "GET",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            response_model=response_model,
+        )
+
     @typing.overload
     def post(
         self,
@@ -1157,6 +1481,37 @@ class Client:
             response_model=response_model,
         )
 
+    def post_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a POST request; return (response, decoded body)."""
+        return self._request_with_body_with_response(
+            "POST",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     def put(
         self,
@@ -1222,6 +1577,37 @@ class Client:
             response_model=response_model,
         )
 
+    def put_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a PUT request; return (response, decoded body)."""
+        return self._request_with_body_with_response(
+            "PUT",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     def patch(
         self,
@@ -1287,6 +1673,37 @@ class Client:
             response_model=response_model,
         )
 
+    def patch_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a PATCH request; return (response, decoded body)."""
+        return self._request_with_body_with_response(
+            "PATCH",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     def delete(
         self,
@@ -1352,6 +1769,37 @@ class Client:
             response_model=response_model,
         )
 
+    def delete_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a DELETE request; return (response, decoded body)."""
+        return self._request_with_body_with_response(
+            "DELETE",
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @typing.overload
     def head(
         self,
@@ -1518,6 +1966,38 @@ class Client:
             response_model=response_model,
         )
 
+    def request_with_response(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+        response_model: type[T],
+    ) -> tuple[httpx2.Response, T]:
+        """Send a request with an explicit method; return (response, decoded body)."""
+        return self._request_with_body_with_response(
+            method,
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            extensions=extensions,
+            json=json,
+            content=content,
+            data=data,
+            files=files,
+            response_model=response_model,
+        )
+
     @contextlib.contextmanager
     def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
         self,

{httpware-0.11.0 → httpware-0.13.0}/src/httpware/middleware/resilience/circuit_breaker.py

@@ -1,4 +1,4 @@
-"""CircuitBreaker + AsyncCircuitBreaker — classic consecutive-failure circuit breaker.
+"""CircuitBreaker + AsyncCircuitBreaker — consecutive-failure and failure-rate circuit breakers.
 
 See planning/specs/2026-06-13-circuit-breaker-and-timeout-design.md for the contract.
 
@@ -17,6 +17,15 @@ State machine (classic / consecutive-failure):
     HALF_OPEN — admit exactly one probe at a time; success_threshold consecutive probe
                 successes close the circuit; one probe failure re-opens it.
 
+Trip modes:
+    Classic (default) — opens when consecutive counted-failures reach failure_threshold.
+        Set failure_threshold to use this mode; leave failure_rate_threshold unset.
+    Rate (opt-in) — opens when the failure rate over a rolling window_seconds window
+        meets or exceeds failure_rate_threshold, provided at least minimum_calls
+        outcomes have been observed in that window. Set failure_rate_threshold to
+        activate; failure_threshold is ignored in this mode.
+    Half-open recovery and event names are identical across both modes.
+
 The lock-free _CircuitBreakerState holds the transition logic, shared by both wrappers.
 AsyncCircuitBreaker relies on asyncio atomicity (no await inside a transition) plus a
 single-event-loop guard; CircuitBreaker (sync) serializes transitions with a
@@ -42,6 +51,9 @@ from httpware.middleware import AsyncNext, Next
 _FAILURE_THRESHOLD_INVALID = "failure_threshold must be >= 1"
 _RESET_TIMEOUT_INVALID = "reset_timeout must be >= 0"
 _SUCCESS_THRESHOLD_INVALID = "success_threshold must be >= 1"
+_FAILURE_RATE_THRESHOLD_INVALID = "failure_rate_threshold must be in (0, 1]"
+_WINDOW_SECONDS_INVALID = "window_seconds must be > 0"
+_MINIMUM_CALLS_INVALID = "minimum_calls must be >= 1"
 _CROSS_LOOP_MSG = (
     "AsyncCircuitBreaker is bound to a single event loop. First seen on {first!r}; "
     "current request is on {current!r}. Use one AsyncCircuitBreaker per loop; "
@@ -50,6 +62,8 @@ _CROSS_LOOP_MSG = (
 
 _DEFAULT_FAILURE_STATUS_CODES = frozenset(range(500, 600))
 
+_BUCKET_COUNT = 10
+
 _ROLE_CLOSED = "closed"
 _ROLE_PROBE = "probe"
 
@@ -62,6 +76,56 @@ class _CircuitState(enum.Enum):
     HALF_OPEN = "half_open"
 
 
+class _RollingWindow:
+    """Time-bucketed success/failure counters over a rolling window.
+
+    `window_seconds` is split into `_BUCKET_COUNT` buckets. Each bucket holds
+    [successes, failures] tagged with the integer time-slot it represents; a
+    bucket whose slot is stale is reset on write, and `totals` filters to the
+    live slot range so data older than the window never counts. Every method is
+    synchronous and reads `now` from its caller (so the breaker's critical
+    section owns the clock read).
+    """
+
+    def __init__(self, window_seconds: float) -> None:
+        self._bucket_width = window_seconds / _BUCKET_COUNT
+        self._slot = [-1] * _BUCKET_COUNT
+        self._success = [0] * _BUCKET_COUNT
+        self._failure = [0] * _BUCKET_COUNT
+
+    def _current_slot(self, now: float) -> int:
+        return int(now // self._bucket_width)
+
+    def record(self, now: float, *, failed: bool) -> None:
+        slot = self._current_slot(now)
+        index = slot % _BUCKET_COUNT
+        if self._slot[index] != slot:  # bucket reused for a new slot — evict
+            self._slot[index] = slot
+            self._success[index] = 0
+            self._failure[index] = 0
+        if failed:
+            self._failure[index] += 1
+        else:
+            self._success[index] += 1
+
+    def totals(self, now: float) -> tuple[int, int]:
+        """Return (total, failures) across buckets still inside the window at `now`."""
+        slot = self._current_slot(now)
+        oldest = slot - _BUCKET_COUNT + 1
+        total = 0
+        failures = 0
+        for i in range(_BUCKET_COUNT):
+            if oldest <= self._slot[i] <= slot:
+                total += self._success[i] + self._failure[i]
+                failures += self._failure[i]
+        return total, failures
+
+    def clear(self) -> None:
+        self._slot = [-1] * _BUCKET_COUNT
+        self._success = [0] * _BUCKET_COUNT
+        self._failure = [0] * _BUCKET_COUNT
+
+
 class _CircuitBreakerState:
     """Lock-free circuit-breaker state machine shared by the sync + async wrappers.
 
@@ -70,13 +134,16 @@ class _CircuitBreakerState:
     inside a transition); the sync wrapper wraps each call in a threading.Lock.
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913 — breaker state has many orthogonal knobs; a dataclass would be worse
         self,
         *,
         failure_threshold: int,
         reset_timeout: float,
         success_threshold: int,
         failure_status_codes: Collection[int] | None,
+        failure_rate_threshold: float | None,
+        window_seconds: float,
+        minimum_calls: int,
         now: Callable[[], float],
     ) -> None:
         if failure_threshold < 1:
@@ -85,6 +152,12 @@ class _CircuitBreakerState:
             raise ValueError(_RESET_TIMEOUT_INVALID)
         if success_threshold < 1:
             raise ValueError(_SUCCESS_THRESHOLD_INVALID)
+        if failure_rate_threshold is not None and not (0.0 < failure_rate_threshold <= 1.0):
+            raise ValueError(_FAILURE_RATE_THRESHOLD_INVALID)
+        if window_seconds <= 0:
+            raise ValueError(_WINDOW_SECONDS_INVALID)
+        if minimum_calls < 1:
+            raise ValueError(_MINIMUM_CALLS_INVALID)
         self._failure_threshold = failure_threshold
         self._reset_timeout = reset_timeout
         self._success_threshold = success_threshold
@@ -93,6 +166,11 @@ class _CircuitBreakerState:
         self._failure_status_codes = (
             frozenset(failure_status_codes) if failure_status_codes is not None else _DEFAULT_FAILURE_STATUS_CODES
         )
+        self._failure_rate_threshold = failure_rate_threshold
+        self._minimum_calls = minimum_calls
+        self._rate_mode = failure_rate_threshold is not None
+        self._window = _RollingWindow(window_seconds) if self._rate_mode else None
+        self._window_seconds = window_seconds
         self._now = now
         self._state = _CircuitState.CLOSED
         self._consecutive_failures = 0
@@ -140,22 +218,30 @@ class _CircuitBreakerState:
         if role == _ROLE_PROBE:
             self._probe_in_flight = False
         if self._state is _CircuitState.CLOSED:
-            self._consecutive_failures = 0
+            if self._rate_mode:
+                self._record_outcome(request, failed=False)
+            else:
+                self._consecutive_failures = 0
         elif self._state is _CircuitState.HALF_OPEN:
             self._consecutive_successes += 1
             if self._consecutive_successes >= self._success_threshold:
                 self._state = _CircuitState.CLOSED
                 self._consecutive_failures = 0
                 self._consecutive_successes = 0
+                if self._rate_mode:
+                    self._window.clear()  # ty: ignore[unresolved-attribute]
                 self._emit(request, "circuit.closed", logging.INFO, "circuit closed — service recovered", {})
 
     def on_failure(self, role: str, request: httpx2.Request) -> None:
         if role == _ROLE_PROBE:
             self._probe_in_flight = False
         if self._state is _CircuitState.CLOSED:
-            self._consecutive_failures += 1
-            if self._consecutive_failures >= self._failure_threshold:
-                self._open(request, failures=self._consecutive_failures)
+            if self._rate_mode:
+                self._record_outcome(request, failed=True)
+            else:
+                self._consecutive_failures += 1
+                if self._consecutive_failures >= self._failure_threshold:
+                    self._open(request, failures=self._consecutive_failures)
         elif self._state is _CircuitState.HALF_OPEN:
             self._open(request, failures=1)  # 1 = the single probe failure that re-opened the circuit
 
@@ -164,19 +250,41 @@ class _CircuitBreakerState:
         if role == _ROLE_PROBE:
             self._probe_in_flight = False
 
-    def _open(self, request: httpx2.Request, *, failures: int) -> None:
+    def _enter_open(self, request: httpx2.Request, message: str, attributes: dict[str, typing.Any]) -> None:
         self._state = _CircuitState.OPEN
         self._opened_at = self._now()
         self._consecutive_failures = 0
         self._consecutive_successes = 0
-        self._emit(
+        self._emit(request, "circuit.opened", logging.WARNING, message, attributes)
+
+    def _open(self, request: httpx2.Request, *, failures: int) -> None:
+        self._enter_open(
             request,
-            "circuit.opened",
-            logging.WARNING,
             "circuit opened — failure threshold reached",
             {"failure_threshold": self._failure_threshold, "failures": failures},
         )
 
+    def _open_rate(self, request: httpx2.Request, *, total: int, failures: int) -> None:
+        self._enter_open(
+            request,
+            "circuit opened — failure rate threshold reached",
+            {
+                "failure_rate": failures / total,
+                "failure_rate_threshold": self._failure_rate_threshold,
+                "window_seconds": self._window_seconds,
+                "observed_calls": total,
+            },
+        )
+
+    def _record_outcome(self, request: httpx2.Request, *, failed: bool) -> None:
+        # Only reached in rate mode, where _window and _failure_rate_threshold are non-None.
+        now = self._now()
+        self._window.record(now, failed=failed)  # ty: ignore[unresolved-attribute]
+        total, failures = self._window.totals(now)  # ty: ignore[unresolved-attribute]
+        threshold = self._failure_rate_threshold
+        if threshold is not None and total >= self._minimum_calls and failures / total >= threshold:
+            self._open_rate(request, total=total, failures=failures)
+
     def _emit(
         self,
         request: httpx2.Request,
@@ -197,13 +305,16 @@ class _CircuitBreakerState:
 class AsyncCircuitBreaker:
     """Async classic circuit breaker middleware. See the module docstring for the contract."""
 
-    def __init__(
+    def __init__(  # noqa: PLR0913 — breaker has many orthogonal knobs; a dataclass would be worse
         self,
         *,
         failure_threshold: int = 5,
         reset_timeout: float = 30.0,
         success_threshold: int = 1,
         failure_status_codes: Collection[int] | None = None,
+        failure_rate_threshold: float | None = None,
+        window_seconds: float = 30.0,
+        minimum_calls: int = 20,
         _now: Callable[[], float] = time.monotonic,
     ) -> None:
         self._state = _CircuitBreakerState(
@@ -211,6 +322,9 @@ class AsyncCircuitBreaker:
             reset_timeout=reset_timeout,
             success_threshold=success_threshold,
             failure_status_codes=failure_status_codes,
+            failure_rate_threshold=failure_rate_threshold,
+            window_seconds=window_seconds,
+            minimum_calls=minimum_calls,
             now=_now,
         )
         self._loop: asyncio.AbstractEventLoop | None = None
@@ -261,13 +375,16 @@ class CircuitBreaker:
     (one shared circuit); a sync instance cannot be shared with an AsyncClient.
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913 — breaker has many orthogonal knobs; a dataclass would be worse
         self,
         *,
         failure_threshold: int = 5,
         reset_timeout: float = 30.0,
         success_threshold: int = 1,
         failure_status_codes: Collection[int] | None = None,
+        failure_rate_threshold: float | None = None,
+        window_seconds: float = 30.0,
+        minimum_calls: int = 20,
         _now: Callable[[], float] = time.monotonic,
     ) -> None:
         self._state = _CircuitBreakerState(
@@ -275,6 +392,9 @@ class CircuitBreaker:
             reset_timeout=reset_timeout,
             success_threshold=success_threshold,
             failure_status_codes=failure_status_codes,
+            failure_rate_threshold=failure_rate_threshold,
+            window_seconds=window_seconds,
+            minimum_calls=minimum_calls,
             now=_now,
         )
         self._lock = threading.Lock()