|
| 1 | +# Retro: v0.2 thin-httpx2-wrapper pivot |
| 2 | + |
| 3 | +**Released:** 2026-06-04 as `0.2.0` |
| 4 | +**Landing PR:** [#20](https://github.com/modern-python/httpware/pull/20) — `feat/v0.2-thin-httpx2-wrapper` |
| 5 | +**Recovery anchor:** tag `pre-v0.2-pivot` (the last commit on the 0.1 surface) |
| 6 | + |
| 7 | +## 1. What shipped |
| 8 | + |
| 9 | +The 0.2 line replaces the 0.1 "full abstraction over the underlying HTTP client" with a thin opinionated wrapper around `httpx2`. The pivot cluster, in causal order: |
| 10 | + |
| 11 | +- `4c569de` — implementation plan for the rewrite. |
| 12 | +- `55a5a65` / `1240493` — design spec and pydantic-decoder clarification. |
| 13 | +- `ce293c1` — tore down the 0.1 surfaces (`request.py`, `response.py`, `config.py`, `transports/`, `_internal/auth.py`, `_internal/chain.py`) ahead of the rewrite. |
| 14 | +- `974d84c` — status-keyed exception tree retyped onto `httpx2.Response`. |
| 15 | +- `93142f0` — IPv6 userinfo stripping + branch-coverage gaps. |
| 16 | +- `635de95` — middleware protocol and chain retyped on `httpx2.Request`/`Response`. |
| 17 | +- `ab262b4`, `337ae1f`, `d1ebd3b`, `ae5a742` — `AsyncClient` rebuilt from scratch: construction, `send()` + `build_request()`, per-method API surface, `__aenter__`/`__aexit__` honoring owned vs. borrowed `httpx2` clients. |
| 18 | +- `fcac5d1`, `da5ed1c`, `c7c185f` — integration tests, surface assertions, branch-coverage closure under tightened `--cov=.` gate. |
| 19 | +- `4dc1c4d` — `CLAUDE.md` collapsed seams from five to three; retired the no-leakage invariant. |
| 20 | +- `17bba20`, `6223135` — `engineering.md` rewritten and moved to `planning/`. |
| 21 | +- `dcbf0d1` — `deferred-work.md` closed 12 items obsoleted by the pivot. |
| 22 | +- `1e4a027` — version bump to 0.2.0, release notes drafted. |
| 23 | +- `3edef19` — PR #20 merged. |
| 24 | + |
| 25 | +## 2. What the pivot bought us |
| 26 | + |
| 27 | +- **Smaller surface.** `src/httpware/` went from 14 modules to 8. `request.py`, `response.py`, `config.py`, the entire `transports/` subtree, `_internal/auth.py`, and `_internal/chain.py` are gone. |
| 28 | +- **One fewer abstraction layer.** The `Transport` protocol and `Httpx2Transport` collapsed into the `AsyncClient` terminal. Seams 1 (Middleware↔Transport) and 4 (Transport↔httpx2) merged into Seam A. |
| 29 | +- **Full request/response context in every error for free.** `StatusError` carries `httpx2.Response`. Callers get headers, body, request URL, request method, extensions — all the things 0.1 exposed as flat fields — without our type definitions. |
| 30 | +- **`httpx2.MockTransport` replaces `RecordedTransport`.** Tests inject `httpx2_client=httpx2.AsyncClient(transport=mock)`. We stop maintaining a bespoke recorder and align with the public seam. |
| 31 | +- **Honest dependency story.** `httpx2` is now part of the public surface, not a hidden implementation detail. Users can read `httpx2` docs and the types map directly. |
| 32 | + |
| 33 | +## 3. What the pivot cost |
| 34 | + |
| 35 | +- **0.x public break.** Any consumer importing `httpware.Request`, `httpware.Response`, `httpware.StreamResponse`, `httpware.Limits`, `httpware.Timeout`, `httpware.ClientConfig`, `httpware.Transport`, `httpware.Httpx2Transport`, or `httpware.RecordedTransport` is broken. No deprecation cycle — 0.x semver. |
| 36 | +- **Six specs went from roadmap to archive.** Story 1-8 (`RecordedTransport`), 2-3 (Request immutability helpers), 2-4 (auth coercion middleware), 4-1 (`StreamResponse` type), 4-2 (transport stream implementation), 5-3 (`Redactor` middleware) all describe code that no longer has a host module. |
| 37 | +- **The auth-coercion feature shipped and was removed in the same release cycle.** Epic 2 closed on 2026-06-01 with auth coercion as its last story; the pivot deleted it 2 days later. Users now pass `httpx2.Auth` subclasses directly. The retired code was a real piece of work that did not survive its first ship. |
| 38 | +- **Test fixtures rewritten.** Every test relying on `RecordedTransport` had to migrate to `httpx2.MockTransport`. |
| 39 | + |
| 40 | +## 4. Decisions worth keeping |
| 41 | + |
| 42 | +- **The three-seam architecture.** `AsyncClient ↔ Middleware`, `AsyncClient ↔ ResponseDecoder`, `httpware ↔ optional extras`. Documented in `planning/engineering.md` §3. Every cross-seam call goes through its protocol; nothing leaks. |
| 43 | +- **Status-keyed exceptions with one positional arg.** `raise NotFoundError(response)`. No `__init__` overrides in subclasses. All fields available via `exc.response.*`. Userinfo stripping in `__repr__`/summary. |
| 44 | +- **Single-pass decoder protocol.** `decode(content: bytes, model: type[T]) -> T`. No two-pass JSON-then-validate. `PydanticDecoder` uses `TypeAdapter.validate_json` with a memoized adapter; `MsgspecDecoder` uses `msgspec.json.decode(content, type=model)`. |
| 45 | +- **Optional-extras pattern.** One extra per dedicated module. Top-level import of an extra is forbidden — `grep` should return exactly one file per extra. |
| 46 | + |
| 47 | +## 5. Decisions to revisit before 1.0 |
| 48 | + |
| 49 | +- **Pydantic required vs. optional.** Resolved in this conversation's follow-up: 0.3.0 will move `pydantic` into `[project.optional-dependencies]` and guard its import like `msgspec`. See `planning/specs/2026-06-04-pydantic-optional-extra-design.md` (forthcoming). |
| 50 | +- **Default-decoder model.** With pydantic optional, `AsyncClient(decoder=None)` needs a fail-fast path when no decoder can be constructed. Folded into the 0.3.0 spec. |
| 51 | +- **`httpx2._` audit cadence.** CI enforces `grep -rE 'httpx2\._' src/httpware/` returns zero. A scheduled audit on each `httpx2` upgrade would catch new private surfaces sooner. Open question; no spec yet. |
| 52 | + |
| 53 | +## 6. Lessons |
| 54 | + |
| 55 | +- **Writing `engineering.md` *after* the pivot was the right ordering.** A pre-pivot rewrite would have been aspirational fiction. Post-pivot, every section maps to code that exists today. |
| 56 | +- **`deferred-work.md` made the pivot's blast radius obvious.** Closed-by-pivot items each cited a host file that no longer existed. The grep was instant: if the file is gone, the item is closed. |
| 57 | +- **Specs survive their own death.** The retired Story 1-8 / 2-3 / 2-4 / 4-1 / 4-2 / 5-3 designs are still useful reading — they document the road not taken. `planning/archive/` keeps them legible without crowding the active spec set. |
0 commit comments