Skip to content

0.7.0 — First-cut user docs

Choose a tag to compare

View all tags
@lesnik512 lesnik512 released this 05 Jun 20:26
0.7.0
12f6c92
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

httpware 0.7.0 — First-cut user docs (docs-only)

0.7.0 is a docs-only release. No API changes. Code written against 0.6.0 continues to work unchanged.

This release ships the first-cut user-facing documentation surface — every shipped feature through 0.6 now has a user-facing reference page, and the two highest-friction adoption recipes (test-mocking and OpenTelemetry wiring) are concrete. Epic 3 (Resilience) closes with this release.

What's new

Four new docs deliverables on the docs site:

  • docs/middleware.md — write your own middleware against httpware.middleware.Middleware and Next. Covers the protocol, the phase decorators (@before_request, @after_response, @on_error), a worked RequestIdMiddleware example, a "when NOT to write a middleware" section, and an "OpenTelemetry wiring" section with a minimal SDK + opentelemetry-instrumentation-httpx setup that makes the 0.6.0 Retry/Bulkhead observability events visible as span events.
  • docs/resilience.md — deep-dive reference for Retry, RetryBudget, and Bulkhead: every parameter with its default and effect, the retry-rule matrix (status codes × methods), Retry-After parsing, streaming-body refusal contract, the token-bucket formula, why the floor matters, budget/bulkhead sharing across clients, and composition guidance.
  • docs/errors.md — the full StatusError hierarchy as an ASCII tree, the status-to-exception mapping table, practical catching strategies (specific status → StatusError → NetworkError → resilience errors → ClientError catch-all), the exc.response.* access pattern with the userinfo-stripping security note, and the payloads on RetryBudgetExhaustedError / BulkheadFullError for caller-side logging.
  • docs/testing.md — the httpx2.MockTransport injection pattern via AsyncClient(httpx2_client=...). Recording/stateful handlers, testing custom middleware end-to-end, brief "why not respx" note pointing at the private-internals risk.

Plus discovery: three new mkdocs nav entries (Resilience, Errors, Testing), four new bullets in docs/index.md "Where to go next", and engineering notes updated.

What's not in this release

  • No source code changes. The Middleware protocol, phase decorators, resilience primitives, exception tree, and test-transport seam all already existed; this release documents them.
  • No new built-in middleware. No CircuitBreaker, no RateLimiter, no auth helpers.
  • No API autodoc (e.g., mkdocstrings). Hand-written user docs only.
  • No benchmarks page, no migration guide, no speculative cookbook recipes. Reference pages for shipped features + concrete adoption recipes only.
  • No mkdocs publish workflow / docs-site infrastructure. That's Epic 6 (story 6-2); this release just keeps mkdocs build --strict green.

Epic 3 closed

Epic 3 (Resilience) has shipped end-to-end:

  • v0.4 slice 1 — Retry + RetryBudget + attempt_timeout=
  • v0.4 slice 2 — Bulkhead
  • v0.7 — 3-6 extension-slot docs + the rest of the first-cut user-docs surface

Remaining roadmap is Epic 6 (ship v1.0): 6-2 docs site infrastructure (mkdocs publishing, hand-written content only — no autodoc), and 6-5 release flow (Trusted Publishers + Sigstore).

References

Assets 2
Loading