httpware 0.16.0 — free-threading (nogil) support, Beta

Certifies httpware under free-threaded CPython (PEP 703), backed by CI
evidence rather than a bare classifier.

Feature

• Free-threading support (Beta). Adds the
  Programming Language :: Python :: Free Threading :: 2 - Beta classifier.
  A new pytest-freethreaded CI job runs the full test suite (all extras) on
  free-threaded CPython 3.14t with the GIL disabled. Real-thread stress tests
  (marked pytest.mark.stress) exercise the thread-shared components — the sync
  Bulkhead, CircuitBreaker, and the shared RetryBudget — plus the httpx2
  connection pool, with zero cross-talk or crashes under parallelism; a separate
  deterministic test covers the single-event-loop guard's cross-loop rejection. 3.13t is deferred until msgspec ships a cp313t
  wheel (planning/deferred.md).

Why

httpware's resilience suite is built on threading.Lock/Semaphore and a
shared client across threads is a documented usage pattern; free-threaded
CPython removes the GIL that currently masks latent races. This release adds
the missing proof: a committed contention benchmark
(benchmarks/contention.py, planning/audits/2026-07-18-free-threading-audit.md)
found free-threaded 3.14t ~1.9x slower than GIL 3.11 for RetryBudget's
single-shared-lock hot loop — lock contention dominates that access pattern.
Free-threading support here is a correctness certification, not a
performance claim.

Downstream

No API changes. Safe to upgrade unconditionally; the classifier and CI job
are the only visible additions.

Internals

• New stress pytest marker (architecture/testing.md): runs under the GIL
  too (counts toward coverage) but only proves thread-safety on 3.14t.
• architecture/resilience.md, architecture/overview.md updated with the
  free-threading promotion.

httpware 0.15.2 — docs accuracy + internal dedup, no behavior change

No public API changes. Every commit since 0.15.1 is docs, internal refactoring,
CI, or planning tooling — safe to upgrade unconditionally.

Docs

• Site overhaul + audit fixes (#90): the "Why httpware" pitch is now
  benefit-first (raise_for_status() dropped from the lead); index.md
  slimmed to a true quickstart; the OpenTelemetry wiring guide moved to a new
  docs/observability.md; resilience.md trimmed. Fixed two
  security-relevant doc bugs where errors.md/middleware.md said secrets in
  URLs are not redacted when the code does redact them, plus several other
  doc/code mismatches (Retry-After-over-max_delay behavior,
  previously-undocumented ResponseTooLargeError/max_response_body_bytes).
• Project lockup hero added to the docs home page (#91).
• Docs-and-comments audit: fixed stale docstrings (BulkheadFullError,
  AsyncClient.stream()'s version caveat), a cross-doc contradiction on where
  DecodeError wrapping happens, a httpx/httpx2 terminology slip (with a
  follow-up correction to the underlying respx-compatibility claim, verified
  against respx's own docs), a contributing.md wording contradiction on
  docstring requirements, and deduplicated ResponseTooLargeError's
  triple-repeated behavior description down to one canonical account
  (#103, #104, #105).

Internal (no behavior change)

Continuation of the sync/async deduplication pass flagged by the 2026-06-14
deep audit — every remaining "duplicated, no divergence yet" item from that
audit is now closed:

• Body-cap subsystem and httpx2-exception-mapper context managers extracted
  out of client.py into dedicated _internal/ modules.
• Client construction-validation and kwargs-assembly logic shared between
  Client/AsyncClient.
• The 6 hand-duplicated exception reconstruct/__reduce__ pairs in
  errors.py collapsed into one _KeywordReduceMixin.
• Bulkhead/AsyncBulkhead constructor validation and rejection-event
  construction shared.
• The decoders' memoizing get-or-build cache pattern (4 sites across
  pydantic.py/msgspec.py) shared via one generic helper.
• _read_capped/_read_capped_async's declared-length-reject and
  Response-reconstruction blocks shared.
• AsyncBulkhead/AsyncCircuitBreaker's identical single-event-loop guard
  shared via a new _event_loop_guard.py.

CI & tooling

• PRs now run mkdocs --strict as a check, catching broken internal
  links/anchors and orphaned pages before merge (#92).
• Planning convention bumped to 2.0.0 (flat change files, no per-change
  folders) (#93, #94).
• Dropped stale ty: ignore suppressions in circuit-breaker tests that a
  newer ty no longer needs (#96).

Downstream

No action required. Nothing about the installed package's public behavior
changes.

httpware 0.15.1 — release pipeline on PyPI Trusted Publishing

No library changes. The package is identical to 0.15.0; this release exercises the new publish path end-to-end.

CI

• Releases now authenticate to PyPI via Trusted Publishing (OIDC) instead of a long-lived PYPI_TOKEN secret. uv publish auto-detects the GitHub Actions id-token; the release job runs under a pypi environment that scopes the trusted publisher (#89).

Downstream

No action required. Nothing about the installed package changes.

httpware 0.15.0 — status-agnostic response-body cap (max_response_body_bytes)

Minor release. Contains one breaking change (pre-1.0): the opt-in
max_error_body_bytes parameter is replaced by max_response_body_bytes.

This release turns the error-only body guard into a real, status-agnostic memory
cap that is actually enforced on the non-streaming send() path and against
compression bombs.

Breaking change

max_error_body_bytes is removed and replaced by max_response_body_bytes
on both Client and AsyncClient. There is no compatibility alias — passing the
old keyword raises TypeError.

# before
client = AsyncClient(max_error_body_bytes=1_000_000)
# after
client = AsyncClient(max_response_body_bytes=1_000_000)

None (the default) remains unbounded. A non-None value below 1 is now
rejected with ValueError at construction.

What changed and why

The old max_error_body_bytes only fired inside stream(), only on 4xx/5xx, and
only as a declared-Content-Length pre-check. For a non-streaming send(),
httpx2 buffered the whole body before httpware got control, so the hot path had
no cap at all — and a small compressed body could decode to something enormous
(a 133-byte gzip body decodes to 100 KB; real bombs run ~1000:1) and slip past a
header check entirely.

max_response_body_bytes:

• Is status-agnostic — a 200 is capped the same as a 500. Memory
  exhaustion has no status code, and the success path is the larger surface.
• Counts decoded bytes (the in-memory footprint), so compression bombs are
  caught.
• Is enforced at the non-streaming terminal (send() and the per-verb helpers)
  via a streaming capped-accumulator, and on stream()'s internal error
  pre-read. User-driven stream() iteration is never capped.
• Fails fast with ResponseTooLargeError, which now carries a reason field:
  "declared" (declared Content-Length over the cap, rejected before a byte is
  read) or "streamed" (the decoded body crossed the cap mid-read).

The declared Content-Length is kept only as an early reject (never an early
accept), so chunked and bomb bodies are always run through the accumulator.

Semantics

• ResponseTooLargeError is a non-status ClientError: it is not retried and
  does not count toward the circuit breaker.
• An otherwise-retryable 5xx whose body exceeds the cap surfaces as
  ResponseTooLargeError (cap-wins / fail-hard), not the status error — retrying
  would only re-fetch the oversized body.
• On the capped path the buffered response is rebuilt via the public
  httpx2.Response(content=...) constructor and therefore has no .elapsed. The
  default (None-cap) fast path keeps plain send() and preserves .elapsed.

All public API is honored — no httpx2 private access.

httpware 0.14.0 — read-only circuit-breaker state introspection

Minor release. Additive only — no breaking changes.

This release adds a read-only state property and a public CircuitState enum
to both AsyncCircuitBreaker and CircuitBreaker, enabling health checks,
readiness probes, dashboards, and test assertions against the current circuit
state without any impact on circuit behavior.

New behavior

Both breakers now expose a state property that returns one of three values from
the new CircuitState enum (CLOSED, OPEN, HALF_OPEN). The enum is exported
from the top-level httpware package:

from httpware import CircuitState
from httpware.middleware.resilience import AsyncCircuitBreaker

breaker = AsyncCircuitBreaker(failure_threshold=5)

# In a health or readiness handler:
if breaker.state is CircuitState.OPEN:
    ...  # report the dependency as degraded

The same property exists on the sync CircuitBreaker.

Semantics

state is a raw read of the stored state. The OPEN→HALF_OPEN transition is lazy:
it fires on the next request admitted after reset_timeout elapses, not on a
clock tick. This means state will report OPEN until a request is actually
admitted as the probe — reading the property never triggers the transition.

This is intentional. A health endpoint that polls state cannot accidentally
promote the circuit to HALF_OPEN by reading it; only real traffic does.

What is NOT in this release

The following remain deferred and are not part of 0.14.0:

• Manual circuit control (force_open, force_closed)
• Writable state transitions (e.g., reset via property assignment)
• Count-based sliding windows
• Slow-call detection

Shipped via

PR #70 — read-only circuit-breaker state introspection.

httpware 0.13.0 — time-based failure-rate trip mode for the circuit breaker

Minor release. Additive only — no breaking changes.

This release adds an opt-in time-based failure-rate trip mode to both
AsyncCircuitBreaker and CircuitBreaker. Classic consecutive-failure behavior
is the default and is unchanged.

New behavior

The classic circuit breaker trips after failure_threshold consecutive counted
failures — a simple and effective policy for hard outages. It can miss partial
degradation, though: a downstream returning errors on half of all requests may
never form a long enough consecutive streak to trip the circuit.

Rate mode addresses this. Pass failure_rate_threshold to switch:

from httpware import AsyncClient
from httpware.middleware.resilience import AsyncCircuitBreaker


breaker = AsyncCircuitBreaker(
    failure_rate_threshold=0.5,  # open at ≥50% failures
    window_seconds=30.0,         # over a rolling 30s window
    minimum_calls=20,            # but only once 20+ calls are observed
)

async with AsyncClient(
    base_url="https://api.example.com",
    middleware=[breaker],
) as client:
    response = await client.get("/users/1")

The circuit opens when the observed failure rate over the rolling window_seconds
window meets or exceeds failure_rate_threshold — but only once minimum_calls
outcomes have been recorded in that window. The minimum_calls guard prevents a
single early failure from immediately tripping the circuit before a meaningful
sample has accumulated.

New constructor parameters

Both AsyncCircuitBreaker and CircuitBreaker accept three new keyword
arguments:

In rate mode, failure_threshold is ignored — the trip condition is purely
rate-based. All other parameters (reset_timeout, success_threshold,
failure_status_codes) apply in both modes.

Observability

Event names are identical in both modes: circuit.opened, circuit.rejected,
circuit.half_open, circuit.closed. In rate mode the circuit.opened event
carries additional attributes — failure_rate, failure_rate_threshold,
window_seconds, observed_calls — and its message is
"circuit opened — failure rate threshold reached".

What is NOT in this release

The following remain deferred and are not part of 0.13.0:

• Count-based sliding windows (the current implementation is time-based only)
• Slow-call detection (a separate trip axis based on latency percentiles)
• Manual circuit control (force_open, force_closed)
• State introspection properties on the breaker instance

Shipped via

PR #69 — time-based failure-rate trip mode for the circuit breaker.

httpware 0.12.0 — per-verb *_with_response siblings

Minor release. Additive only — no breaking changes.

This release adds ergonomic per-verb shortcuts for the common pattern of needing
both the raw httpx2.Response (headers, status, request URL) and a typed body in
a single call — without having to pair build_request(...) with
send_with_response(...).

New public names

Six methods on both AsyncClient and Client:

from httpware import AsyncClient

client = AsyncClient(base_url="https://api.example.com", decoders=[...])

# One call — response metadata and typed body together
response, users = await client.get_with_response(
    "/users", params={"page": 2}, response_model=list[User]
)
next_url = response.headers.get("Link")
etag = response.headers.get("ETag")

Details

Signature: each method requires response_model (keyword-only) and returns
tuple[httpx2.Response, T]. All other kwargs (params, headers, json,
content, timeout, …) pass through to httpx2 unchanged — identical to the
non-_with_response siblings.

Use case: response metadata alongside a typed body — Link-header pagination,
ETag caching, rate-limit reads (X-RateLimit-Remaining), request URL logging on
redirect. When you don't need the raw response, the existing get / post /
… methods remain the preferred form.

Scope: no head_with_response or options_with_response — HEAD is
bodiless and OPTIONS is rarely decoded. request_with_response(method, url, …)
is the escape hatch for any other verb.

Inherited behavior: MissingDecoderError is raised before the HTTP call
when no decoder claims the model type; DecodeError wraps a failure inside
decode(). Both propagate unchanged through the new methods, identical to
send_with_response.

Shipped via

PR #68 — per-verb *_with_response siblings on AsyncClient and Client
(src/httpware/client.py).

Minor release. Additive only — no breaking changes.

This release ships the full remediation of the 2026-06-14 full-codebase deep
audit: 35 confirmed findings closed across security, correctness, public API,
test quality, and documentation.

New public names

from httpware import ResponseTooLargeError

AsyncClient / Client gain an opt-in max_error_body_bytes: int | None = None.

Security hardening

• URL secret redaction. Request URLs that reach logs, OpenTelemetry span
  events, and StatusError messages/repr are now sanitized: user:pass@
  userinfo is stripped and the values of known-sensitive query/fragment
  parameters (api_key, access_token, token, secret, password, …) are
  masked with REDACTED. Redaction is centralized at the _emit_event
  emission boundary, so every resilience event is covered and a future event
  cannot reintroduce the leak. Non-secret URLs are byte-identical to before.
• Bounded error bodies. With max_error_body_bytes set, stream() raises
  the new ResponseTooLargeError on a 4xx/5xx whose declared Content-Length
  exceeds the cap, before reading the body. Default (None) is unchanged.
  A chunked error body with no declared length is still read — a hard mid-read
  cap would require httpx2 private API; that deeper bound is tracked as
  deferred work.
• Documented trust boundaries. trust_env=True proxy inheritance and the
  fact that exc.response.request exposes Authorization/Cookie headers are
  now called out in architecture/.

Correctness fixes

• RetryBudget no longer spends a token on a Retry-After give-up. When a
  server's Retry-After exceeds max_delay, the give-up check now runs before
  budget.try_withdraw(), so a Retry-After flood can't drain shared-budget
  capacity for unrelated requests (sync and async).
• Hostile headers no longer crash the retry loop. A Retry-After of a few
  hundred digits raised OverflowError; _parse_retry_after now degrades it
  to "no hint". full_jitter_delay likewise no longer raises at very large
  attempt indices — it clamps to max_delay as documented.
• Decoder/extras robustness. The pydantic import is fully guarded so the
  decoder module loads without the extra (the friendly ImportError is the
  real fail-fast path), and msgspec's internal type walk raises a friendly
  ImportError rather than NameError when the extra is absent.
• AsyncClient streaming-body detection now recognizes non-replayable sync
  iterables explicitly instead of relying on an undocumented httpx2 detail.
• URL sanitizer no longer emits a malformed http:///path for the
  credentials-but-no-host edge case.

Public API

• httpware.middleware now defines __all__, so from httpware.middleware import * no longer leaks httpx2, typing helpers, or submodules.

Quality

• Test suite hardened: closed coverage gaps (sync terminal mapping, the
  CookieConflict branch, TimeoutError tripping the circuit breaker, the
  three never-constructed status errors), added sync/async parity mirrors and
  Client overload typing tests, replaced a flaky time.sleep-based bulkhead
  test with a deterministic barrier, and pinned a budget-test clock.
• Documentation accuracy fixes across architecture/ and the docs site.

Shipped via

PRs #62 (pydantic isolation), #63 (security cluster), #64 (correctness +
public API), #65 (test quality), #66 (docs). See
planning/audits/2026-06-14-deep-audit.md
for the full audit.

httpware 0.10.1 — 0.10.0 delta-audit closure

Patch release. Bug fixes + hardening from the 0.10.0 delta audit. No breaking changes (one additive observability field; see below).

Audit report: planning/audit/2026-06-13-delta-audit.md.

Fixes

• AsyncTimeout now rejects non-finite values. AsyncTimeout(timeout=float("nan")) and float("inf") were silently accepted — timeout <= 0 is False for both under IEEE-754 — producing a nondeterministic (nan) or never-firing (inf) deadline. The constructor now requires a finite positive number.
• Observability failures can no longer break the request path. _emit_event previously called OpenTelemetry's span.add_event(...) unguarded; a recording span whose add_event raised would propagate into the caller. Because the circuit breaker emits inside its state transitions, this could strand the circuit permanently in HALF_OPEN. The OTel emission now degrades silently on failure (the structured log record has already fired), at the root for all middleware.

Observability (additive)

• Each event log record now carries an event field holding the event-name string (e.g. event="circuit.opened"). Previously the event name reached only OpenTelemetry span events; it is now also a first-class, filterable field on the stdlib log record. Purely additive — no existing attribute changed.

Docs

• docs/index.md observability section now lists all four middleware loggers (httpware.retry, httpware.bulkhead, httpware.circuit_breaker, httpware.timeout) and their events with levels.
• CircuitOpenError added to the resilience-refusal error lists in README.md and docs/index.md.
• README logging example now sets httpware.circuit_breaker to INFO so the circuit.half_open / circuit.closed recovery events are visible.
• Corrected the AsyncRetry timeout-knob note (now points to AsyncTimeout), the OPEN-state wording (the first request after reset_timeout becomes the probe), and the observability/breaker docstrings.

Tests

Hardened to assert the stable event-name strings, the exact retry_after value, the 429-resets-the-failure-streak path, success_threshold > 1 with a mid-streak probe failure, and reset_timeout=0 / empty failure_status_codes boundaries. No production behavior change from the test work.

httpware 0.10.0 — circuit breaker + async timeout

Minor release. Additive only — no breaking changes.

New public names

from httpware.middleware.resilience import AsyncCircuitBreaker  # async
from httpware.middleware.resilience import CircuitBreaker        # sync
from httpware.middleware.resilience import AsyncTimeout
from httpware import CircuitOpenError

AsyncCircuitBreaker / CircuitBreaker

Classic consecutive-failure circuit breaker. Counts counted failures (5xx, NetworkError, TimeoutError) and fast-fails with CircuitOpenError once failure_threshold consecutive failures are observed. Recovers via a HALF_OPEN probe after reset_timeout seconds; closes when success_threshold consecutive probe successes are seen.

4xx responses — including 429 — count as successes. A 429 means healthy-but-throttling; tripping the circuit on it would amplify incidents.

CircuitOpenError (a ClientError subclass) carries retry_after: float | None — the seconds until the next probe window (None when HALF_OPEN with a probe already in flight).

Sharable across multiple clients (one shared circuit). A sync CircuitBreaker cannot be shared with an AsyncCircuitBreaker.

AsyncTimeout

Bounds total wall-clock across the inner pipeline — including retries and backoff sleeps. Raises httpware.TimeoutError on expiry. Async-only: sync Python has no cancellation primitive that can interrupt a blocking call mid-flight.

New observability events

Recommended chain ordering

AsyncTimeout → AsyncCircuitBreaker → AsyncBulkhead → AsyncRetry → terminal

Breaker outside retry: an open circuit short-circuits the whole retry loop; the breaker counts one outcome per fully-exhausted retry sequence.