# 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

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