feat: add AsyncKeyedCircuitBreaker and KeyedCircuitBreaker

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
+```
+
+One independent circuit per **circuit key**, for a client whose requests go to more than one upstream. A plain `AsyncCircuitBreaker` holds a single circuit, so one failing upstream would fast-fail requests to every healthy one; the keyed breaker opens only the failing upstream's circuit.
+
+Each circuit behaves exactly like an [`AsyncCircuitBreaker`](#asynccircuitbreaker-circuitbreaker) built with the same arguments: same states, failure classification, rate mode, half-open probe and events. The probe slot is per circuit, so two upstreams recovering at once each get their own probe.
+
+### Constructor
+
+Every `AsyncCircuitBreaker` parameter, with the same defaults, plus:
+
+| Parameter | Default | Effect |
+|---|---|---|
+| `key` | `request.url.origin` | Maps a request to its circuit key. Any hashable value works. The default origin combines scheme, host and port, normalized, 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. |
+
+### 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. Memory grows with the number of distinct keys, so `key` must map to a small, bounded set — configured upstreams, not a value taken from user input. A key function that returns something unbounded, such as the full URL, grows the map forever.
+
+### Observability
+
+The same events as `AsyncCircuitBreaker`, on the same `httpware.circuit_breaker` logger, each carrying one extra attribute: `circuit_key`, the `str()` of the request's circuit key.
+
+### 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
+```
+
+The keyed breaker takes the circuit breaker's place in the [composition](#composition): outside `AsyncRetry`, so it 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",
 ]