Merge pull request #52 from modern-python/fix/0.10.1-delta-audit

0.10.1 — delta-audit closure (fixes + hardening)

Author: lesnik512

README.md

@@ -112,7 +112,7 @@ It does NOT pass through the middleware chain: `AsyncRetry`, `AsyncBulkhead`, an
 
 ## Errors
 
-All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.
+All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError`, `BulkheadFullError`, and `CircuitOpenError`. Everything inherits `httpware.ClientError`.
 
 ## Observability
 
@@ -126,7 +126,7 @@ import logging
 # Enable visibility into resilience operational events
 logging.getLogger("httpware.retry").setLevel(logging.WARNING)
 logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
-logging.getLogger("httpware.circuit_breaker").setLevel(logging.WARNING)
+logging.getLogger("httpware.circuit_breaker").setLevel(logging.INFO)   # INFO: includes recovery events (half_open, closed)
 logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
 ```
 

docs/index.md

@@ -138,23 +138,34 @@ All errors inherit `httpware.ClientError`. The categories:
 
 - **Status errors** (4xx/5xx responses) — raised automatically, no `raise_for_status()` needed: `NotFoundError`, `RateLimitedError`, `ServiceUnavailableError`, and the rest. All subclass `StatusError`.
 - **Transport errors** — connection / network / protocol failures before a response arrived. `NetworkError` (transient) subclasses `TransportError`.
-- **Resilience refusals** — `RetryBudgetExhaustedError` and `BulkheadFullError`, raised by the resilience middleware.
+- **Resilience refusals** — `RetryBudgetExhaustedError`, `BulkheadFullError`, and `CircuitOpenError`, raised by the resilience middleware.
 - **Decode errors** — `DecodeError`, raised when `response_model=` decoding fails (HTTP call itself succeeded). `MissingDecoderError`, raised when no registered decoder claims the `response_model=` type — fires *before* the HTTP call.
 
 See the [Errors reference](errors.md) for the full tree and catching strategies.
 
 ## Observability
 
-`AsyncRetry`/`Retry` and `AsyncBulkhead`/`Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
+All resilience middleware emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
 
-Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
+Logger names and event names are the stable public contract:
+
+| Logger | Events |
+|---|---|
+| `httpware.retry` | `retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused` |
+| `httpware.bulkhead` | `bulkhead.rejected` |
+| `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.
 
 ```python
 import logging
 
-# Enable visibility into retry / bulkhead operational events
+# Enable visibility into resilience operational events
 logging.getLogger("httpware.retry").setLevel(logging.WARNING)
 logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
+logging.getLogger("httpware.circuit_breaker").setLevel(logging.INFO)  # INFO for recovery events
+logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
 ```
 
 For OTel attribute enrichment on the active span — install the extra:

docs/resilience.md

@@ -24,9 +24,7 @@ from httpware.middleware.resilience import AsyncRetry
 | `respect_retry_after` | `True` | When the response carries a `Retry-After` header on a retryable status, sleep for the header value instead of the jittered backoff. If the header value exceeds `max_delay`, AsyncRetry gives up and re-raises the underlying `StatusError` with a PEP 678 note `httpware: Retry-After (Ns) exceeded max_delay (Ms); giving up`. Set `max_delay` higher (or `respect_retry_after=False`) to opt out. |
 | `budget` | `RetryBudget()` (default-configured) | The token bucket. Pass a shared `RetryBudget` instance to apply one budget across multiple clients. |
 
-For a whole-attempt wall-clock bound, use `httpx2.Timeout` on the client or
-pass `timeout=` per request. `httpware` does not own a structured-cancellation
-timeout knob.
+For a whole-operation wall-clock bound across all retry attempts, compose `AsyncTimeout` outermost — see [AsyncTimeout](#asynctimeout) below. For a per-request bound, use `httpx2.Timeout` on the client or pass `timeout=` per request.
 
 ### Retry-After parsing
 
@@ -156,7 +154,7 @@ Classic consecutive-failure circuit breaker. Counts failures and prevents reques
 ### States
 
 - **CLOSED** — normal operation. Each counted failure increments the consecutive-failure counter. Once `failure_threshold` consecutive counted failures accumulate, the circuit opens.
-- **OPEN** — fast-fail. All requests are rejected immediately with `CircuitOpenError` (carrying `retry_after` seconds until the next probe window). After `reset_timeout` seconds the circuit moves to HALF_OPEN.
+- **OPEN** — fast-fail. While elapsed time is below `reset_timeout`, requests are rejected immediately with `CircuitOpenError` (carrying `retry_after` seconds until the next probe window). The first request after `reset_timeout` elapses transitions the circuit to HALF_OPEN and becomes the probe.
 - **HALF_OPEN** — exactly one probe is admitted. If `success_threshold` consecutive probe successes are observed, the circuit closes. A single probe failure re-opens the circuit.
 
 ### Constructor
@@ -317,7 +315,7 @@ from httpware.middleware.resilience import Retry
 
 `Retry` uses `time.sleep` between attempts. `Retry-After`, streaming-body refusal, exhaustion behavior, and `RetryBudgetExhaustedError` semantics are identical to `AsyncRetry`.
 
-For a whole-attempt wall-clock bound, use `httpx2.Timeout` on the wrapped client or pass `timeout=` per request. `httpware` does not own a structured-cancellation timeout knob.
+For a whole-attempt wall-clock bound, use `httpx2.Timeout` on the wrapped client or pass `timeout=` per request. No sync `Timeout` middleware exists — sync Python has no cancellation primitive that can interrupt a blocking call mid-flight.
 
 ### `Bulkhead`