Aleksey Shakhmatov
4d47918a66
All checks were successful
CI / test (push) Successful in 30s
Add server package description, component table, and usage example to README. Document server architecture, middleware chain, and test conventions in CLAUDE.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
43 lines
2.1 KiB
Markdown
43 lines
2.1 KiB
Markdown
# CLAUDE.md — httpx
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
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
|
|
|
|
### Client
|
|
- **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
|
|
|
|
### Server (`server/`)
|
|
- **Core pattern**: middleware is `func(http.Handler) http.Handler`
|
|
- **Server** wraps `http.Server` with `net.Listener`, graceful shutdown via signal handling, lifecycle hooks
|
|
- **Router** wraps `http.ServeMux` — supports groups with prefix + middleware inheritance, `Mount` for sub-handlers
|
|
- **Middleware chain** via `Chain(A, B, C)` — A outermost, C innermost (same as client side)
|
|
- **statusWriter** wraps `http.ResponseWriter` to capture status; implements `Unwrap()` for `http.ResponseController`
|
|
- **Defaults()** preset: RequestID → Recovery → Logging + production timeouts
|
|
- **HealthHandler** exposes `GET /healthz` (liveness) and `GET /readyz` (readiness with pluggable checkers)
|
|
|
|
## Conventions
|
|
|
|
- Functional options for all configuration (client and server)
|
|
- Test helpers: `mockTransport(fn)` wrapping `middleware.RoundTripperFunc` (client), `httptest.NewRecorder`/`httptest.NewRequest` (server)
|
|
- Server tests use `waitForAddr(t, srv)` helper to poll until server is ready
|
|
- No external test frameworks — stdlib only
|
|
- Thread safety required (`sync.Mutex`/`atomic`)
|
|
- `internal/clock` for deterministic time testing
|