You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 147fe98
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: planning/engineering.md
+5-4Lines changed: 5 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,9 @@ This doc is the single distilled reference for `httpware` design rationale, prot
6
6
7
7
`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.
8
8
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.
10
10
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`.
12
12
13
13
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.
14
14
@@ -135,17 +135,18 @@ Post-pivot, the roadmap has three categories. Topic slugs in `planning/specs/` a
135
135
### Shipped (all epics closed)
136
136
137
137
-**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).
139
139
-**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).
140
140
-**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).
141
141
-**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.
142
143
-**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).
143
144
-**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).
144
145
-**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.
145
146
-**Carry-forward decoder:**`1-6` msgspec decoder via extras — second `ResponseDecoder` adapter, already implemented; verified surviving in the pivot.
146
147
-**Middleware protocol:**`2-1` and `2-2` already implemented in the pivot (protocol, chain, phase decorators).
147
148
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).
149
150
150
151
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`.
0 commit comments