Skip to content

Commit c679eef

Browse files
lesnik512claude
andcommitted
docs(retro): v0.2 thin-httpx2-wrapper pivot
Six sections: what shipped, what the pivot bought us, what it cost, decisions worth keeping, decisions to revisit before 1.0, lessons. Cites the pivot commit cluster and tag pre-v0.2-pivot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent c650b5e commit c679eef

1 file changed

Lines changed: 57 additions & 0 deletions

File tree

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
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

Comments
 (0)