|
| 1 | +# httpware 0.7.0 — Middleware extension guide (docs-only) |
| 2 | + |
| 3 | +**0.7.0 is a docs-only release. No API changes.** Code written against 0.6.0 continues to work unchanged. |
| 4 | + |
| 5 | +This release ships the final piece of Epic 3 — a user-facing guide to writing custom middleware against `httpware`'s Middleware protocol. With it, Epic 3 (Resilience) closes. |
| 6 | + |
| 7 | +## What's new |
| 8 | + |
| 9 | +- **[`docs/middleware.md`](../../docs/middleware.md)** — a new top-level docs page covering: |
| 10 | + - The `Middleware` Protocol and `Next` type alias, both exported from `httpware.middleware`. |
| 11 | + - The three phase decorators (`@before_request`, `@after_response`, `@on_error`) as ergonomic shortcuts for the common cases. |
| 12 | + - A worked `RequestIdMiddleware` example — assign a per-call UUID, propagate via `X-Request-Id`, log it alongside the response status. Placed outside `Retry` so all attempts of one call share one ID, and correlates naturally with the 0.6.0 observability events' `url` attribute. |
| 13 | + - A "when NOT to write a middleware" section pointing redaction at `logging.Filter`, URL/header validation at `httpx2`, per-call behavior at `request.extensions=`, and HTTP-level tracing at `opentelemetry-instrumentation-httpx`. |
| 14 | + |
| 15 | +Plus small touchups so the guide is discoverable: a nav entry in `mkdocs.yml`, a one-sentence pointer in the README, and a "Where to go next" bullet in `docs/index.md`. |
| 16 | + |
| 17 | +## What's not in this release |
| 18 | + |
| 19 | +- No source code changes. The `Middleware` protocol, `Next` type, and phase decorators all already existed (shipped pre-0.4 via Epic 2); this release documents them. |
| 20 | +- No new built-in middleware (no CircuitBreaker, no RateLimiter, no metrics counter). The deliberate non-resilience worked-example choice keeps the guide focused on teaching the protocol rather than shipping a half-baked toy that gets cargo-culted. |
| 21 | +- No mkdocs publish workflow / docs-site infra. That's Epic 6 story `6-2`; this release just makes the strict build green. |
| 22 | + |
| 23 | +## Epic 3 closed |
| 24 | + |
| 25 | +Epic 3 (Resilience) has shipped end-to-end: |
| 26 | +- v0.4 slice 1 — `Retry` + `RetryBudget` + `attempt_timeout=` |
| 27 | +- v0.4 slice 2 — `Bulkhead` |
| 28 | +- v0.7 — extension-slot docs |
| 29 | + |
| 30 | +Remaining roadmap is Epic 6 (ship v1.0): `6-2` docs site infrastructure, `6-3` benchmarks, `6-5` release flow (Trusted Publishers + Sigstore). |
| 31 | + |
| 32 | +## References |
| 33 | + |
| 34 | +- Spec: [`planning/specs/2026-06-05-extension-slot-docs-design.md`](../specs/2026-06-05-extension-slot-docs-design.md) |
| 35 | +- Plan: [`planning/plans/2026-06-05-extension-slot-docs-plan.md`](../plans/2026-06-05-extension-slot-docs-plan.md) |
| 36 | +- Roadmap: [`planning/engineering.md`](../engineering.md) §8 |
0 commit comments