feat: add AsyncKeyedCircuitBreaker and KeyedCircuitBreaker (#142)

* feat: add AsyncKeyedCircuitBreaker and KeyedCircuitBreaker

* docs: warn that circuit_key is logged unredacted

* docs: tighten the keyed circuit breaker section

* fix: build the default circuit key without URL.origin, absent before httpx2 2.11

* style: wrap the keyed breaker docstring

Author: lesnik512

CONTEXT.md

@@ -50,6 +50,11 @@ The circuit breaker's unit of account: a `NetworkError`, an httpware `TimeoutErr
 circuit state. "Failure" alone is ambiguous here: a failed request is very often not a counted
 failure.
 
+**Circuit key**:
+The value a keyed circuit breaker computes from a request to pick its circuit; requests with equal
+keys share one circuit. The default is the URL's origin: scheme, host and port.
+_Avoid_: host — the host alone merges upstreams that differ only in scheme or port.
+
 **Cap**:
 `max_response_body_bytes` — the bound on how many bytes httpware buffers on the caller's behalf.
 Counted *decoded*, status-agnostic, and never applied to user-driven `stream()` iteration.

docs/observability.md

@@ -13,7 +13,7 @@ Logger names and event names are the stable public contract:
 | `httpware.circuit_breaker` | `circuit.opened` (WARNING), `circuit.rejected` (WARNING), `circuit.half_open` (INFO), `circuit.closed` (INFO) |
 | `httpware.timeout` | `timeout.exceeded` (WARNING) |
 
-Each log record carries an `event` field with the event-name string (e.g. `event="circuit.opened"`), usable for log-aggregator filtering. See [resilience.md](resilience.md) for the full event tables per middleware.
+Each log record carries an `event` field with the event-name string (e.g. `event="circuit.opened"`), usable for log-aggregator filtering. Events from `AsyncKeyedCircuitBreaker` / `KeyedCircuitBreaker` also carry `circuit_key`, naming the circuit they belong to. See [resilience.md](resilience.md) for the full event tables per middleware.
 
 ```python
 import logging

docs/resilience.md

@@ -16,6 +16,7 @@ A key ordering constraint: `AsyncBulkhead` must sit outside `AsyncRetry` (before
 - [`RetryBudget`](#retrybudget)
 - [`AsyncBulkhead`](#asyncbulkhead)
 - [`AsyncCircuitBreaker` / `CircuitBreaker`](#asynccircuitbreaker-circuitbreaker)
+- [`AsyncKeyedCircuitBreaker` / `KeyedCircuitBreaker`](#asynckeyedcircuitbreaker-keyedcircuitbreaker)
 - [`AsyncTimeout`](#asynctimeout)
 - [Sync `Retry` and `Bulkhead`](#sync-retry-and-bulkhead)
 
@@ -253,6 +254,49 @@ async with AsyncClient(
 
 Sync usage is identical: `Client` + `CircuitBreaker`, no `await`.
 
+## `AsyncKeyedCircuitBreaker` / `KeyedCircuitBreaker`
+
+```python
+from httpware.middleware.resilience import AsyncKeyedCircuitBreaker  # async
+from httpware.middleware.resilience import KeyedCircuitBreaker  # sync
+```
+
+Use a keyed breaker when one client sends requests to more than one upstream. A plain `AsyncCircuitBreaker` holds a single circuit, so one failing upstream fast-fails requests to all the healthy ones. The keyed breaker keeps a separate circuit for each circuit key and opens only the failing upstream's circuit.
+
+Each circuit behaves exactly like an [`AsyncCircuitBreaker`](#asynccircuitbreaker-circuitbreaker) built with the same arguments: the same states, failure classification, rate mode, half-open probe and events. Each circuit has its own probe slot, so two upstreams that recover at the same time are probed independently.
+
+### Constructor
+
+Every `AsyncCircuitBreaker` parameter, with the same defaults, plus:
+
+| Parameter | Default | Effect |
+|---|---|---|
+| `key` | the request's origin | Maps a request to its circuit key. Any hashable value works. The default is the origin as a string built from scheme, host and port, such as `https://a.example` or `http://a.example:8080`. Hosts are lowercased and default ports dropped, so `https://A.example/x` and `https://a.example:443/y` share a circuit, while `http://a.example` and `https://a.example:8443` each get their own. Userinfo is never part of it. |
+
+### Circuit lifetime
+
+A circuit is created on the first request for its key and kept for as long as the breaker lives. Nothing is evicted or pruned, so memory grows with the number of distinct keys. `key` must therefore map requests to a small, bounded set, such as your configured upstreams. Never derive it from user input. A key function that returns something unbounded, such as the full URL, grows the map forever.
+
+### Observability
+
+The keyed breakers emit the same events as `AsyncCircuitBreaker` on the same `httpware.circuit_breaker` logger. Each event has one extra attribute, `circuit_key`, which is the `str()` of the request's circuit key. httpware redacts `url` but not `circuit_key`, which reaches log records and span events exactly as the key function returned it. A custom `key` must not return credentials, tokens or other sensitive values. The default origin contains none.
+
+### Example
+
+```python
+from httpware import AsyncClient
+from httpware.middleware.resilience import AsyncKeyedCircuitBreaker, AsyncRetry
+
+
+async with AsyncClient(
+    middleware=[AsyncKeyedCircuitBreaker(failure_threshold=5, reset_timeout=60.0), AsyncRetry()],
+) as client:
+    await client.get("https://suggest-a.example/v1/suggest")
+    await client.get("https://suggest-b.example/v1/suggest")  # unaffected if suggest-a is down
+```
+
+In the [composition](#composition), the keyed breaker goes where the circuit breaker goes. It sits outside `AsyncRetry` and counts one outcome per retry sequence. Sync usage is identical: `Client` + `KeyedCircuitBreaker`, no `await`.
+
 ## `AsyncTimeout`
 
 ```python

src/httpware/__init__.py

@@ -42,11 +42,13 @@
 from httpware.middleware.resilience import (
     AsyncBulkhead,
     AsyncCircuitBreaker,
+    AsyncKeyedCircuitBreaker,
     AsyncRetry,
     AsyncTimeout,
     Bulkhead,
     CircuitBreaker,
     CircuitState,
+    KeyedCircuitBreaker,
     Retry,
     RetryBudget,
 )
@@ -57,6 +59,7 @@
     "AsyncBulkhead",
     "AsyncCircuitBreaker",
     "AsyncClient",
+    "AsyncKeyedCircuitBreaker",
     "AsyncMiddleware",
     "AsyncNext",
     "AsyncRetry",
@@ -74,6 +77,7 @@
     "DecodeError",
     "ForbiddenError",
     "InternalServerError",
+    "KeyedCircuitBreaker",
     "Middleware",
     "MissingDecoderError",
     "NetworkError",

src/httpware/middleware/resilience/__init__.py

@@ -2,19 +2,27 @@
 
 from httpware.middleware.resilience.budget import RetryBudget
 from httpware.middleware.resilience.bulkhead import AsyncBulkhead, Bulkhead
-from httpware.middleware.resilience.circuit_breaker import AsyncCircuitBreaker, CircuitBreaker, CircuitState
+from httpware.middleware.resilience.circuit_breaker import (
+    AsyncCircuitBreaker,
+    AsyncKeyedCircuitBreaker,
+    CircuitBreaker,
+    CircuitState,
+    KeyedCircuitBreaker,
+)
 from httpware.middleware.resilience.retry import AsyncRetry, Retry
 from httpware.middleware.resilience.timeout import AsyncTimeout
 
 
 __all__ = [
     "AsyncBulkhead",
     "AsyncCircuitBreaker",
+    "AsyncKeyedCircuitBreaker",
     "AsyncRetry",
     "AsyncTimeout",
     "Bulkhead",
     "CircuitBreaker",
     "CircuitState",
+    "KeyedCircuitBreaker",
     "Retry",
     "RetryBudget",
 ]