httpx/.github/copilot-instructions.md

Copilot instructions — httpx

Project

git.codelab.vc/pkg/httpx is a Go 1.24 HTTP client and server library with zero external dependencies.

Architecture

Client (httpx root package)

• Middleware type: func(http.RoundTripper) http.RoundTripper
• Chain assembly (outermost → innermost): Logging → User MW → Retry → Circuit Breaker → Balancer → Transport
• Retry wraps CB+Balancer so each attempt can hit a different endpoint
• Circuit breaker is per-host (sync.Map of host → Breaker)
• Client.Close() required when using WithEndpoints() — stops health checker goroutine

Server (server/ package)

• Middleware type: func(http.Handler) http.Handler
• Router wraps http.ServeMux with groups, prefix routing, Mount for sub-handlers
• Defaults() preset: RequestID → Recovery → Logging + production timeouts
• Available middleware: RequestID, Recovery, Logging, CORS, RateLimit, MaxBodySize, Timeout
• WriteJSON/WriteError for JSON responses

Sub-packages

• middleware/ — client-side middleware (Logging, Recovery, Auth, Headers, RequestID)
• retry/ — retry with exponential backoff and Retry-After
• circuitbreaker/ — per-host circuit breaker
• balancer/ — load balancing with health checking
• internal/requestid/ — shared context key between server and middleware
• internal/clock/ — deterministic time for tests

Conventions

• All configuration uses functional options (WithXxx functions)
• Zero external dependencies — do not add requires to go.mod
• Tests use stdlib only (testing, httptest) — no testify or gomock
• Thread safety with sync.Mutex, sync.Map, or atomic
• Client test mock: mockTransport(fn) using middleware.RoundTripperFunc
• Server test helpers: httptest.NewRecorder, httptest.NewRequest
• Do NOT import server from middleware or vice versa — use internal/requestid for shared context
• Sentinel errors in sub-packages, re-exported in root package
• Use internal/clock for time-dependent tests

Commands

go build ./...           # compile
go test ./...            # test
go test -race ./...      # test with race detector
go vet ./...             # static analysis