51 lines
2.1 KiB
Markdown
51 lines
2.1 KiB
Markdown
# 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
|
|
```
|