Skip to content

Commit 147fe98

Browse files
lesnik512claude
andcommitted
docs(engineering): post-0.8.0 sweep — §1 past tense + §8 v0.8 entry + closing version
Closes audit Low findings (engineering.md:9 §1 future tense, engineering.md:136 §8 v0.4 attempt_timeout= line) and Nit (engineering.md:146 §8 closing v0.7.0) from planning/audit/2026-06-07-deep-audit.md. Adds a v0.8.0 entry to the shipped-work log capturing sync Client + Async* rename + attempt_timeout= removal. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent b4833b5 commit 147fe98

1 file changed

Lines changed: 5 additions & 4 deletions

File tree

‎planning/engineering.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ This doc is the single distilled reference for `httpware` design rationale, prot
66

77
`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request` and `httpx2.Response` as the public request/response surface and adds three things on top: typed response decoding (via a `ResponseDecoder` protocol; pydantic and msgspec are both opt-in extras as of 0.3.0), a middleware chain composed at client construction, and a status-keyed exception tree raised automatically on 4xx and 5xx. `AsyncClient(decoder=None)` defaults to constructing a `PydanticDecoder` and so requires the `pydantic` extra; callers can supply an explicit `decoder=` argument to escape the default. As of 0.4.0, the package ships a small resilience suite under `httpware.middleware.resilience` — a `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — composed via the standard middleware chain. As of 0.5.0, `AsyncClient.stream()` provides a context-manager API for chunked response bodies; it bypasses the middleware chain by design (see planning/archive/specs/2026-06-05-streaming-design.md). As of 0.6.0, `Retry` and `Bulkhead` emit operational events via stdlib `logging` records (`httpware.retry` / `httpware.bulkhead` loggers) and — when `opentelemetry-api` is installed — OpenTelemetry span events on the active span. As of 0.7.0, the first-cut user-docs surface is live at <https://httpware.readthedocs.io/> (Middleware, Resilience, Errors, Testing guides) and Epic 3 is closed.
88

9-
The next release renames the async middleware surface to use the `Async*`/`async_*` prefix (aligning with httpx2's convention) and removes the seldom-used `attempt_timeout=` kwarg from `AsyncRetry` — see `planning/specs/2026-06-07-sync-client-design.md` for the rationale.
9+
As of 0.8.0 the async middleware surface uses the `Async*`/`async_*` prefix (aligning with httpx2's convention); the `attempt_timeout=` kwarg was removed from `AsyncRetry` in the same release — see `planning/specs/2026-06-07-sync-client-design.md` for the rationale.
1010

11-
The same release also adds a sync `Client` with full feature parity (typed decoding, middleware chain, `Retry`/`Bulkhead`, `stream()`). `RetryBudget` is now thread-safe (one class, both worlds). Sync `Bulkhead` uses `threading.Semaphore` and cannot share an instance with `AsyncBulkhead`. See `planning/specs/2026-06-07-sync-client-design.md`.
11+
0.8.0 also shipped a sync `Client` with full feature parity (typed decoding, middleware chain, `Retry`/`Bulkhead`, `stream()`). `RetryBudget` is now thread-safe (one class, both worlds). Sync `Bulkhead` uses `threading.Semaphore` and cannot share an instance with `AsyncBulkhead`. See `planning/specs/2026-06-07-sync-client-design.md`.
1212

1313
The 0.1.0 release attempted to own a full abstraction over the underlying HTTP client. v0.2 walks that back: `httpx2` is part of the public surface.
1414

@@ -135,17 +135,18 @@ Post-pivot, the roadmap has three categories. Topic slugs in `planning/specs/` a
135135
### Shipped (all epics closed)
136136

137137
- **Epic 3 — Resilience: SHIPPED.**
138-
- **v0.4 slice 1:** `Retry` middleware + Finagle-style `RetryBudget` token bucket + `attempt_timeout=` parameter (folded-in 3-1). See [`planning/archive/specs/2026-06-05-retry-and-retry-budget-design.md`](archive/specs/2026-06-05-retry-and-retry-budget-design.md) and [`planning/archive/plans/2026-06-05-retry-and-retry-budget-plan.md`](archive/plans/2026-06-05-retry-and-retry-budget-plan.md).
138+
- **v0.4 slice 1:** `Retry` middleware + Finagle-style `RetryBudget` token bucket + `attempt_timeout=` parameter (folded-in 3-1; `attempt_timeout=` was removed in 0.8.0 — see v0.8.0 entry below). See [`planning/archive/specs/2026-06-05-retry-and-retry-budget-design.md`](archive/specs/2026-06-05-retry-and-retry-budget-design.md) and [`planning/archive/plans/2026-06-05-retry-and-retry-budget-plan.md`](archive/plans/2026-06-05-retry-and-retry-budget-plan.md).
139139
- **v0.4 slice 2:** `Bulkhead` middleware (concurrency limiter via `asyncio.Semaphore` with bounded acquire wait). See [`planning/archive/specs/2026-06-05-bulkhead-design.md`](archive/specs/2026-06-05-bulkhead-design.md) and [`planning/archive/plans/2026-06-05-bulkhead-plan.md`](archive/plans/2026-06-05-bulkhead-plan.md).
140140
- **v0.7:** `3-6` extension-slot docs — [`docs/middleware.md`](../docs/middleware.md). Covers the Middleware Protocol, phase decorators, a Request-ID worked example, and "when NOT to write a middleware." See [`planning/archive/specs/2026-06-05-extension-slot-docs-design.md`](archive/specs/2026-06-05-extension-slot-docs-design.md) and [`planning/archive/plans/2026-06-05-extension-slot-docs-plan.md`](archive/plans/2026-06-05-extension-slot-docs-plan.md).
141141
- **v0.7 also bundles** the rest of the first-cut user-docs surface — [`docs/resilience.md`](../docs/resilience.md) (Retry/RetryBudget/Bulkhead reference), [`docs/errors.md`](../docs/errors.md) (exception tree + catching strategies), [`docs/testing.md`](../docs/testing.md) (mock-transport injection pattern) — plus an "OpenTelemetry wiring" section appended to `docs/middleware.md`. See [`planning/archive/specs/2026-06-05-v0.7-docs-expansion-design.md`](archive/specs/2026-06-05-v0.7-docs-expansion-design.md) and [`planning/archive/plans/2026-06-05-v0.7-docs-expansion-plan.md`](archive/plans/2026-06-05-v0.7-docs-expansion-plan.md).
142+
- **v0.8.0:** sync `Client` with full feature parity (middleware chain, decoder seam, `Retry`, `Bulkhead`, `stream()`); async surface renamed to `Async*`/`async_*` prefix; `attempt_timeout=` removed from `AsyncRetry`. Breaking release for every public async middleware import.
142143
- **Epic 4 — Streaming: SHIPPED in v0.5.** `AsyncClient.stream()` context manager + Retry refuses streamed-body requests. See [`planning/archive/specs/2026-06-05-streaming-design.md`](archive/specs/2026-06-05-streaming-design.md) and [`planning/archive/plans/2026-06-05-streaming-plan.md`](archive/plans/2026-06-05-streaming-plan.md).
143144
- **Epic 5 — Observability: SHIPPED in v0.6** — re-scoped from the original 4-story plan. `Retry` and `Bulkhead` emit operational events via stdlib `logging` + opt-in OpenTelemetry span events. Stories `5-1` (Layer 1 middleware hooks) and `5-4` (standalone OTel middleware) RETIRED — `opentelemetry-instrumentation-httpx` already covers transport-level tracing; a separate httpware middleware would duplicate it. See [`planning/archive/specs/2026-06-05-observability-design.md`](archive/specs/2026-06-05-observability-design.md) and [`planning/archive/plans/2026-06-05-observability-plan.md`](archive/plans/2026-06-05-observability-plan.md).
144145
- **Epic 6 — Ship v1.0: SHIPPED.** `6-2` docs site live at <https://httpware.readthedocs.io/> (mkdocs-material, hand-written content only, auto-publishing from `main`). Stories `6-3` (benchmarks) and `6-5` (Trusted Publishers + Sigstore release flow) RETIRED — neither carries enough value to maintain. Tag-driven release via the existing `publish.yml` workflow stays as-is.
145146
- **Carry-forward decoder:** `1-6` msgspec decoder via extras — second `ResponseDecoder` adapter, already implemented; verified surviving in the pivot.
146147
- **Middleware protocol:** `2-1` and `2-2` already implemented in the pivot (protocol, chain, phase decorators).
147148

148-
All planned epics are closed as of v0.7.0. The next semver bump is a judgment call (cut v1.0 from the current main; or keep iterating at 0.x and let the API settle further before promising stability).
149+
All planned epics are closed as of v0.8.0. The next semver bump is a judgment call (cut v1.0 from the current main; or keep iterating at 0.x and let the API settle further before promising stability).
149150

150151
When work starts on a roadmap item, it gets a spec at `planning/specs/YYYY-MM-DD-<topic>-design.md` and a plan at `planning/plans/YYYY-MM-DD-<topic>-plan.md`.
151152

0 commit comments

Comments
 (0)