feat(v0.7): first-cut user docs — Middleware + Resilience + Errors + Testing (closes Epic 3)#28
Merged
Merged
Conversation
Closes the deferred-tutorial half of story 3-6 (the docs-sync-0.4 pass shipped the freshness half; the walkthrough was explicitly punted there). Scope: one new docs/middleware.md page (~150 lines) — Middleware protocol, phase decorators, Request-ID propagation example, when NOT to write a middleware. Plus four small touchups (mkdocs nav, README pointer, docs/index.md pointer, engineering.md §8 SHIPPED line) and release notes for 0.7.0. Non-resilience example by design — Request-ID pairs naturally with 0.6.0's observability events (correlate via the URL attribute) without shipping a half-baked CircuitBreaker that would get cargo-culted. Closes Epic 3.
7 tasks for docs-only PR feat/v0.7-middleware-docs: 1. Branch + docs/middleware.md (~150 lines markdown — full page content) 2. mkdocs.yml nav entry + strict-build verification 3. README.md pointer in 'With resilience middleware' subsection 4. docs/index.md bullet in 'Where to go next' 5. engineering.md §8 — mark 3-6 SHIPPED, Epic 3 closed 6. planning/releases/0.7.0.md release notes 7. Final verification + push (mkdocs --strict, lint sanity, test sanity, push branch) Each task is a single commit. No source code changes; verification is mkdocs strict build + the existing test/lint suites as no-op confirmation. Spec at planning/specs/2026-06-05-extension-slot-docs-design.md.
New docs/middleware.md covering: - The Middleware Protocol + Next type, exported from httpware.middleware - Phase decorators (@before_request, @after_response, @on_error) as ergonomic shortcuts for the no-state-keeping cases - Worked example: a RequestIdMiddleware that assigns a per-call UUID via X-Request-Id and logs it alongside the response status. Placed outside Retry on purpose so all attempts of the same call share one ID and correlate with the 0.6.0 observability events' url attribute - 'When NOT to write a middleware' section covering redaction (use a logging.Filter), URL/header validation (httpx2 owns it), per-call behavior (use request.extensions=), and HTTP-tracing (install opentelemetry-instrumentation-httpx instead) Closes the deferred-tutorial half of story 3-6. See spec at planning/specs/2026-06-05-extension-slot-docs-design.md.
Inserts between Quick-Start and Development. The page itself (added in the prior commit) is reachable from the Quick-Start's resilience section and the README; this nav slot is for users browsing the docs site directly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
One-sentence pointer in the existing 'With resilience middleware' subsection. Surfaces the new guide for users skimming the README who want to write their own middleware.
Adds the guide as the first bullet — most user-facing of the four entries in that section.
§8 now records the extension-slot docs as shipped in v0.7 and notes Epic 3 closed. The remaining roadmap collapses to Epic 6 (ship v1.0) plus Epic 5's already-shipped observability work.
Docs-only release. Calls out the new docs/middleware.md page, notes the non-goals (no source changes, no new built-in middleware, no docs-site infra), and records Epic 3 as closed end-to-end after v0.4 + v0.7.
…el onto open branch Expands the scope of the open PR #28 / feat/v0.7-middleware-docs from just the Middleware guide to the full first-cut user docs surface: - New docs/resilience.md (~180 lines) — Retry/RetryBudget/Bulkhead parameter tables + retry-rule matrix + Retry-After + streaming refusal + budget sharing + composition guidance - New docs/errors.md (~120 lines) — full StatusError tree + status->exc mapping + catching strategies + exc.response.* access + userinfo note - New docs/testing.md (~80 lines) — httpx2.MockTransport injection pattern + recording handlers + custom-middleware testing + why no respx - docs/middleware.md gets ~30-line 'Wiring OpenTelemetry' section appended (concrete SDK + opentelemetry-instrumentation-httpx setup) - mkdocs nav, docs/index.md 'Where to go next' bullets, engineering.md §8 enrichment, planning/releases/0.7.0.md rewrite, PR #28 title/body No code changes, no version bump, no new branch — all stacks on top of the existing 6 commits. Per user-docs-philosophy memory: hand-written only, no autodoc/benchmarks/migration/cookbook. Closes Epic 3 with a richer user-docs surface than originally scoped.
9 tasks for the bundle-onto-PR-#28 docs expansion. Stacks on top of the existing 6 + 2 commits on feat/v0.7-middleware-docs (do NOT branch fresh): 1. Append 'Wiring OpenTelemetry' section to docs/middleware.md 2. Create docs/resilience.md (~190 lines verbatim) 3. Create docs/errors.md (~130 lines verbatim) 4. Create docs/testing.md (~90 lines verbatim) 5. Update mkdocs.yml nav (+3 entries) 6. Update docs/index.md Where-to-go-next (+3 bullets, amend Middleware) 7. Update planning/engineering.md §8 (Epic 3 SHIPPED enrichment) 8. Rewrite planning/releases/0.7.0.md (cover expanded scope) 9. Final verification + push + gh pr edit #28 Each task is a single commit. No source code changes; verification is mkdocs --strict + the existing test/lint suites as no-op confirmation. Spec at planning/specs/2026-06-05-v0.7-docs-expansion-design.md.
httpware[otel] only ships opentelemetry-api; to make Retry/Bulkhead observability events visible users also need an SDK + the opentelemetry-instrumentation-httpx instrumentor (so each HTTP call has an active span our events can attach to). Section sits between 'When NOT to write a middleware' and 'See also'. Minimal console-exporter setup for dev; pointer to OTel Python docs for production exporter wiring.
New docs/resilience.md (~190 lines) — full parameter tables, defaults, Retry-After parsing rules, streaming-body refusal contract, exhaustion behavior, the token-bucket formula + why-the-floor-matters note, budget/bulkhead sharing across clients, composition guidance, and cross-references to Middleware guide, Errors reference, and the Observability section. No new built-in middleware. Documents what already shipped through v0.4 (Retry/RetryBudget/Bulkhead) and v0.6 (the observability events each emits).
…ilience.md links Creates docs/errors.md (~130 lines): - Full StatusError hierarchy as an ASCII tree - Status-to-exception mapping table - Practical catching patterns (specific status -> StatusError -> NetworkError -> resilience errors -> ClientError catch-all) - exc.response.* access pattern with userinfo-stripping security note - Payloads on RetryBudgetExhaustedError / BulkheadFullError Also restores three [Errors reference](errors.md) links in docs/resilience.md that the previous commit had to neutralize because errors.md didn't exist yet at strict-build time. No new exception classes. Documents the tree that already shipped through v0.4 (resilience errors) and v0.2 (status-keyed).
New docs/testing.md (~90 lines) — the httpx2.MockTransport pattern that the project's own tests use; instance-state handler for stateful responses (response sequences, request recording); composing custom middleware with the mock transport for end-to-end tests; brief 'why not respx' note pointing at the private-internals risk. No code changes. Documents the test pattern that has been in tests/ since v0.2 but never user-facing.
Six top-level entries after this: Quick-Start, Resilience, Middleware, Errors, Testing, Development Resilience precedes Middleware because most users reach for the built-in Retry/Bulkhead before writing their own. Errors and Testing follow as reference + setup-friction pages.
Three new bullets (Resilience reference, Errors reference, Testing guide), plus an addendum to the existing Middleware bullet noting the new OpenTelemetry wiring section. Engineering / Contributing / Release-notes bullets unchanged.
Adds a sub-bullet under Epic 3's existing 'Shipped in v0.7' line calling out docs/resilience.md, docs/errors.md, docs/testing.md, and the OpenTelemetry-wiring section appended to docs/middleware.md. Links to the expansion spec and plan.
The prior release notes covered just the Middleware guide. This rewrite covers the full first-cut user-docs surface that 0.7 actually ships: - docs/middleware.md (incl. new OTel-wiring section) - docs/resilience.md (Retry/RetryBudget/Bulkhead reference) - docs/errors.md (exception tree + catching strategies) - docs/testing.md (mock-transport pattern) Title changes from 'Middleware extension guide' to 'First-cut user docs'. 'What's not in this release' enriched with the autodoc / benchmarks / migration-guide / cookbook out-of-scope items per the project's docs philosophy.
lesnik512
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes Epic 3 (Resilience). 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.
docs/middleware.md— write your own middleware against the protocol. Covers the protocol, the phase decorators, a worked Request-ID propagation example, a "when NOT to write a middleware" section, and an OpenTelemetry wiring section (SDK + opentelemetry-instrumentation-httpx setup).docs/resilience.md— Retry/RetryBudget/Bulkhead parameter tables + retry-rule matrix + Retry-After parsing + streaming-body refusal contract + token-bucket formula + budget sharing + composition guidance.docs/errors.md— full StatusError tree + status-to-exception mapping + catching strategies + exc.response.* access pattern + resilience-error payloads.docs/testing.md— `httpx2.MockTransport` injection pattern + recording handlers + testing custom middleware + why not respx.Specs: extension-slot, docs expansion
Plans: extension-slot, docs expansion
Release notes: planning/releases/0.7.0.md
Test Plan
🤖 Generated with Claude Code