Skip to content

README.md

Latest commit

 

History

History
144 lines (117 loc) · 14.2 KB

README.md

File metadata and controls

144 lines (117 loc) · 14.2 KB

Planning

Specs, plans, and change history for httpware. The living truth about what the system does now lives in architecture/ at the repo root; this directory records how it got there.

Conventions

This section is the portable convention — identical across the modern-python repos. The Index below is repo-specific. To adopt elsewhere, copy this section plus _templates/ and point that repo's CLAUDE.md Workflow + truth home at it.

Two axes, never mixed

  • architecture/ (repo root) — the present. One file per capability, living prose, updated whenever a change ships. The truth home.
  • planning/changes/ — the past-and-pending. One folder per change, frozen once shipped.

Shipping a change promotes its conclusions into the affected architecture/<capability>.md by hand, then archives the bundle. That hand-edit is what keeps architecture/ true; the archived bundle carries the why.

Change bundles

A change is a folder changes/active/YYYY-MM-DD.NN-<slug>/:

  • YYYY-MM-DD — proposal date; .NN — zero-padded intra-day counter (.01, .02, …) that breaks same-date ties so the timeline sorts stably.
  • <slug> — kebab-case description, not a story ID.

On merge the folder moves to changes/archive/ with status: shipped, pr:, and outcome: filled, and its line moves from Active to Archived in the Index below.

Three lanes

Lane Artifacts Use when
Full design.md + plan.md design judgment; new file/module; public-API change; cross-cutting/multi-file; non-trivial test design
Lightweight change.md small-but-real: ≲30 LOC net, ≤2 files, no new file, no public-API change, single straightforward test
Tiny none — conventional commit typo, dep bump, linter/formatter/CI tweak, mechanical rename, single-line config

Heavier lane wins on ambiguity. A change.md that outgrows its lane splits into design.md + plan.md.

Artifacts at a glance

  • design.md — the spec: the thinking (why, design, trade-offs, scope).
  • plan.md — the plan: the sequencing (the executor's task checklist).
  • change.md — both, condensed, for the lightweight lane.
  • releases/<semver>.md — per-release user-facing notes.
  • audits/<date>-<slug>.md — findings from a code/docs/bug-hunt sweep; spawns fix changes.
  • retros/<date>-<slug>.md — what we learned after a body of work.
  • deferred.md — real-but-unscheduled items, each with a revisit trigger.

Templates live in _templates/.

Frontmatter

design.md / change.md: status (draft|approved|shipped|superseded), date, slug, supersedes, superseded_by, pr, outcome. plan.md: status, date, slug, spec, pr. Files in architecture/ carry no frontmatter — living prose, dated by git.

Index

Active

None.

Archived (shipped)

  • delta-audit-followups (#71, 2026-06-16) — Closed the 2026-06-16 delta audit Low findings: rate-mode HALF_OPEN probe-failure re-open test + document-as-intended note. Tests + doc only, no release.

  • circuit-breaker-state (#70, 2026-06-16) — Read-only state property + public CircuitState enum on the circuit breaker. Shipped 0.14.0; closed the read-only-state half of the deferred CircuitBreaker introspection item.

  • circuit-breaker-rate-mode (#69, 2026-06-16) — Added an opt-in time-based failure-rate trip mode to the circuit breaker (classic stays default). Shipped 0.13.0; closed deferred item "CircuitBreaker v2 (a)".

  • per-verb-with-response (#68, 2026-06-16) — Added get_with_response … request_with_response siblings (required response_model, returns (Response, T)) to both clients. Shipped 0.12.0; closed the deferred "Per-verb-with-response siblings" item.

  • custom-decoder-guide (#67, 2026-06-15) — Docs: a "write your own ResponseDecoder" guide for Seam B, mirroring docs/middleware.md. Closed deferred item G6.

  • audit-doc-fixes (#66, 2026-06-14) — Closed the deep-audit doc-accuracy findings: Client.stream() docs, terminal-call attribution, the four auto-raise sites, the pydantic upper bound, and root import paths.

  • audit-test-quality (#65, 2026-06-14) — Closed 11 deep-audit test-quality findings: sync-terminal + CookieConflict coverage, the StatusError.__init__ invariant, missing status constructions, sync mirrors, typing overloads, a deterministic bulkhead barrier, a pinned budget clock, an observability assertion, and the TimeoutError circuit trigger.

  • audit-correctness (#64, 2026-06-14) — Closed 8 deep-audit correctness + public-API findings: RetryBudget token ordering, two OverflowError crashes, the redaction triple-slash, the msgspec guard, streaming-body symmetry, the RetryBudget docstring caveat, and middleware/__all__.

  • security-hardening (#63, 2026-06-14) — Closed the deep-audit security cluster: URL secret redaction centralized at the _emit_event chokepoint (userinfo + sensitive query/fragment keys), opt-in max_error_body_bytes + ResponseTooLargeError bounding the stream() error pre-read, and trust_env + header-reachability docs. Non-streaming hard body cap deferred.

  • pydantic-import-isolation (#62, 2026-06-14) — Guarded the pydantic import so the decoder module loads without the extra and the architecture/extras.md Seam-C invariant holds for pydantic. Closed the deep-audit High + 2 folded Mediums.

  • deep-audit (2026-06-14) — Full-codebase deep audit (perf/security/supply-chain gaps + correctness/concurrency/refactoring/test quality). Report: 35 confirmed; all remediated across #62–#66 (non-streaming hard body cap deferred).

  • docs-ux-restructure (#60, 2026-06-14) — Thin README front-door + canonical docs/index.md (G3), why-httpware hook (G1), runnable jsonplaceholder example (G4), nav reorder + architecture links, base-client scrub. G2 dropped; G6 (decoder guide) still open.

  • docs-audit-followups (#58, 2026-06-13) — Second docs-audit batch: corrected the overstated invariant-enforcement claims in CLAUDE.md + architecture/overview.md (only print()/blanket-type: ignore are machine-checked), readability findings R1–R3, and documented the public STATUS_TO_EXCEPTION (G5).

  • docs-accuracy-fixes (f203821, 2026-06-13) — Fixed 5 verified factual errors from the docs audit: RetryBudget formula, modern-di 2.x recipe, contributing-doc CI/grep claim, just lint comment, middleware stable-contracts list (+ AsyncTimeout non-finite wording).

  • portable-planning-convention (#55, 2026-06-13) — Adopt the portable two-axis convention: per-capability architecture/ truth files + changes/ bundles, full history backfill, byte-identical Conventions.

  • circuit-breaker-and-timeout (#51, 2026-06-13) — Shipped 0.10.0 — CircuitBreaker + AsyncTimeout

  • msgspec-nested-customtype-fix (#43, 2026-06-13) — Shipped 0.9.1 — nested-CustomType guard

  • delta-audit (#43, 2026-06-12) — 0.9.0 delta audit; closed via 0.9.1

  • decoder-instance-cache (#42, 2026-06-10) — Shipped 0.9.0 — per-instance decoder cache

  • multi-decoder (#41, 2026-06-10) — Shipped 0.9.0 — multi-decoder routing

  • readme-link-cleanup (#39, 2026-06-08) — README link cleanup

  • mkdocs-gh-pages-migration (#38, 2026-06-08) — Docs host -> GitHub Pages

  • test-mop-up (#37, 2026-06-08) — Shipped 0.8.6 — test-only audit findings

  • small-fixes-mop-up (#36, 2026-06-08) — Shipped 0.8.5 — 4 small audit findings

  • otel-partial-install (#35, 2026-06-08) — Shipped 0.8.4 — OTel partial-install guards

  • post-080-doc-sweep (#34, 2026-06-08) — Post-0.8.0 doc sweep

  • retry-budget-cluster (#34, 2026-06-08) — Shipped 0.8.3 — 7 RetryBudget findings

  • send-with-response (#33, 2026-06-08) — Shipped 0.8.2 — send_with_response

  • deep-audit (#32, 2026-06-07) — Deep audit; findings closed across 0.8.1-0.8.6

  • decoder-error (#32, 2026-06-07) — Shipped 0.8.1 — DecodeError at seam B

  • sync-client (#31, 2026-06-07) — Shipped 0.8.0 — sync Client + Async* rename

  • modern-di-recipe (#29, 2026-06-06) — modern-di DI recipe doc

  • v0.7-docs-expansion (#28, 2026-06-05) — Shipped 0.7.0 — first-cut user docs

  • extension-slot-docs (#28, 2026-06-05) — Shipped 0.7.0 — middleware docs

  • observability (#27, 2026-06-05) — Shipped 0.6.0 — logging + OTel events

  • streaming (#26, 2026-06-05) — Shipped 0.5.0 — stream()

  • docs-sync-0.4 (#25, 2026-06-05) — 0.4 docs sync

  • bulkhead (#23, 2026-06-05) — Shipped 0.4.0 — Bulkhead

  • retry-and-retry-budget (#22, 2026-06-05) — Shipped 0.4.0 — Retry + RetryBudget

  • v0.2-retro-and-housekeeping (#21, 2026-06-04) — Post-0.2 retro + housekeeping

  • pydantic-optional-extra (#21, 2026-06-04) — Shipped 0.3.0 — pydantic moves to an extra

  • thin-httpx2-wrapper (#20, 2026-06-03) — Shipped 0.2.0 — the thin-wrapper pivot

  • input-validation-pass (#19, 2026-06-03) — Input-validation hardening

  • project-hygiene-tidy (#18, 2026-06-02) — Repo hygiene pass

  • docs-reorg-and-mkdocs (#17, 2026-06-02) — Docs reorg + mkdocs scaffolding

  • auth-coercion (#16, 2026-06-01) — Shipped (Epic 2); removed by the v0.2 pivot (superseded by thin-httpx2-wrapper)

  • release-0.1.0-prep (#14, 2026-05-31) — 0.1.0 released

  • recordedtransport (#13, 2026-05-31) — Shipped in 0.1.0; removed by the v0.2 pivot (superseded by thin-httpx2-wrapper)

  • asyncclient (#12, 2026-05-31) — Shipped in 0.1.0; rewritten by the v0.2 pivot (superseded by thin-httpx2-wrapper)

  • msgspec-decoder-via-extras (#11, 2026-05-31) — Shipped in 0.1.0; carry-forward decoder

  • request-immutability-helpers (#10, 2026-05-31) — Shipped in 0.1.0; removed by the v0.2 pivot (superseded by thin-httpx2-wrapper)

  • phase-shortcut-decorators (#9, 2026-05-31) — Shipped in 0.1.0; survived the v0.2 pivot

  • middleware-protocol-and-chain (#8, 2026-05-31) — Shipped in 0.1.0; survived the v0.2 pivot

  • shipped-work-review (#7, 2026-05-31) — 0.1.0-era review of shipped stories

  • bmad-to-superpowers-transition (#6, 2026-05-31) — Bootstrapped the planning workflow

Other

  • architecture/ at the repo root — the living per-capability truth (overview, client, middleware, decoders, errors, resilience, optional extras, testing). This is the promotion target on every ship.
  • audits/ — findings reports (deep audit + delta audits) and their scripts/ tooling.
  • deferred.md — real-but-unscheduled items with revisit triggers.