pkg/httpx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation with server package details
All checks were successful
CI / test (push) Successful in 30s
Details

Browse Source 
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>
This commit is contained in:
Alexey Shakhmatov
2026-03-21 22:56:12 +03:00
parent 7fae6247d5
commit 4d47918a66
2 changed files with 55 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@@ -1,6 +1,6 @@
# httpx
HTTP client for Go microservices. Retry, load balancing, circuit breaking, all as `http.RoundTripper` middleware. stdlib only, zero external deps.
HTTP client and server toolkit for Go microservices. Client side: retry, load balancing, circuit breaking — all as `http.RoundTripper` middleware. Server side: routing, middleware (request ID, recovery, logging), health checks, graceful shutdown. stdlib only, zero external deps.
```
go get git.codelab.vc/pkg/httpx
@@ -33,7 +33,9 @@ resp.JSON(&user)
## Packages
Everything is a `func(http.RoundTripper) http.RoundTripper`. Use them with `httpx.Client` or plug into a plain `http.Client`.
### Client
Client middleware is `func(http.RoundTripper) http.RoundTripper`. Use them with `httpx.Client` or plug into a plain `http.Client`.
| Package | What it does |
|---------|-------------|
@@ -42,6 +44,20 @@ Everything is a `func(http.RoundTripper) http.RoundTripper`. Use them with `http
| `circuitbreaker` | Per-host state machine (closed/open/half-open). Stops hammering dead endpoints. |
| `middleware` | Logging (slog), default headers, bearer/basic auth, panic recovery. |
### Server
Server middleware is `func(http.Handler) http.Handler`. The `server` package provides a production-ready HTTP server.
| Component | What it does |
|-----------|-------------|
| `server.Server` | Wraps `http.Server` with graceful shutdown, signal handling, lifecycle logging. |
| `server.Router` | Lightweight wrapper around `http.ServeMux` with groups, prefix routing, sub-router mounting. |
| `server.RequestID` | Assigns/propagates `X-Request-Id` (UUID v4 via `crypto/rand`). |
| `server.Recovery` | Recovers panics, returns 500, logs stack trace. |
| `server.Logging` | Structured request logging (method, path, status, duration, request ID). |
| `server.HealthHandler` | Liveness (`/healthz`) and readiness (`/readyz`) endpoints with pluggable checkers. |
| `server.Defaults` | Production preset: RequestID → Recovery → Logging + sensible timeouts. |
The client assembles them in this order:
```
@@ -90,6 +106,29 @@ httpClient := &http.Client{
}
```
## Server
```go
logger := slog.Default()
r := server.NewRouter()
r.HandleFunc("GET /hello", func(w http.ResponseWriter, _ *http.Request) {
w.Write([]byte("world"))
})
// Groups with middleware
api := r.Group("/api/v1", authMiddleware)
api.HandleFunc("GET /users/{id}", getUser)
// Health checks
r.Mount("/", server.HealthHandler(
func() error { return db.Ping() },
))
srv := server.New(r, server.Defaults(logger)...)
log.Fatal(srv.ListenAndServe()) // graceful shutdown on SIGINT/SIGTERM
```
## Requirements
Go 1.24+, stdlib only.