docs(plans): S01 HTTP server and routing implementation plan (#89)

Suleimi Ahmedrequested to merge
sahmed/s01-plan into main

Summary

Six-step plan for re-implementing the S01 HTTP server foundation against the corrected spec (!240 (merged)), tracked under #89 (closed).

Authored under /planner per the planner skill workflow: preflight, first gap-clearing pass, mandatory pr-review-toolkit:review-pr pass, second gap-clearing pass, one operator-override review pass, then operator-review sign-off. The plan is the approval gate for the six step MRs that follow; merging this MR signs off research, approach, and step breakdown.

Refs #89 (closed).

Step decomposition

Step 1 (proto + loader) ───┐
                           │
Step 2 (transport) ────────┤
       │                   │
       └─> Step 3 (mw) ────┼──> Step 5 (server.New) ──> Step 6
                           │             (composition root)
Step 4 (shutdown comp) ────┘
# Step Type
1 ServerConfig proto + config loader chore
2 Transport — JSON error envelope chore
3 S01 middleware chain chore
4 Pre-shutdown delay component chore
5 Server assembly — server.New chore
6 Composition root — cmd/artifact-registry/ feat

Steps 1, 2, 4 are sibling-parallel (no edges between them; mergeable in any order). Step 3 depends on Step 2 (uses transport.WriteError). Step 5 depends on Steps 1, 3, 4. Step 6 depends on Step 5 and ships the user-visible binary delta.

What this plan covers

  • All 21 spec acceptance criteria, mapped to specific steps in the plan's AC-coverage table.
  • LabKit v2.4.0 surface verified against pinned source: app.App, app.Component, httpserver.NewWithConfig, Server.AddReadinessCheck, SetRoutePattern, URLParam, labkit/v2/config.
  • Full Go signatures for every exported function the plan introduces (config.Load, config.ParseSize, transport.WriteJSON, transport.WriteError, server.New, server.NewShutdownDelay, server.OriginalBody) so test-author can derive call sites without guessing per docs/dev/go-testing.md §Authorship.
  • Out-of-scope items explicitly named: authentication (S08), authorization (S09), HTTP metrics middleware (#56 (closed)), dependency-aware readiness (#58), format-specific route registration (S10-S12, S17).

Code-source decision

Rewrite from spec with the reverted S01 code on origin/offsite-poc-implementation (commits `b04985be`, `d0e55680`) consulted as reference for known-good patterns (Content-Type-based rewrite trigger, preemption WARN with nil return, shutdown-budget derivation, the OriginalBody accessor). Each step MR description names the patterns it adopted so reviewers can cross-check.

Review trail

  • First pr-review-toolkit:review-pr pass: 2 critical + 7 important + 4 suggestion findings surfaced.
  • Second gap-clearing pass (per the planner skill): all findings folded in via AskUserQuestion rounds.
  • Second pr-review-toolkit:review-pr pass (one-time operator override): 11/12 first-pass findings resolved; 1 partial (§Context revert breadcrumb) accepted as-is on engineer judgment; no new blocking issues.

Test plan

  • npx markdownlint-cli2 docs/plans/2026-05-20-s01-http-server-and-routing.md passes locally (already verified)
  • CI: markdownlint, vale, lychee all green
  • Visual review: the six steps' DAG matches the Mermaid block
  • Visual review: every AC in the AC-coverage table is claimed by exactly one step
  • Visual review: §Naming Conventions function signatures are complete (parameter types AND return types) for every exported function the plan introduces

After this MR merges

Step MRs may open per the DAG. None may open before this MR lands per the project's plan-MR-first guardrail.

Merge request reports