httpx/CLAUDE.md

CLAUDE.md — httpx

Commands

go build ./...                          # compile
go test ./...                           # all tests
go test -race ./...                     # tests with race detector
go test -v -run TestName ./package/     # single test
go vet ./...                            # static analysis

Architecture

• Module: git.codelab.vc/pkg/httpx, Go 1.24, zero external dependencies
• Core pattern: middleware is func(http.RoundTripper) http.RoundTripper
• Chain assembly order (client.go): Logging → User MW → Retry → CB → Balancer → Transport
  • Retry wraps CB+Balancer so each attempt can hit a different endpoint
• Circuit breaker is per-host (sync.Map of host → Breaker)
• Sentinel errors: canonical values live in sub-packages, root package re-exports as aliases
• balancer.Transport returns (Middleware, *Closer) — Closer must be tracked for health checker shutdown
• Client.Close() stops the health checker goroutine

Conventions

• Functional options for all configuration
• Test helpers: mockTransport(fn) wrapping middleware.RoundTripperFunc
• No external test frameworks — stdlib only
• Thread safety required (sync.Mutex/atomic)
• internal/clock for deterministic time testing