Rene Nochebuena
caa397591e
Introduces code.nochebuena.dev/einherjar/httpclient — the outbound HTTP client starter for the Einherjar framework. Absorbs the httpclient package from micro-lib, replacing fmt.Errorf wrapping with core/xerrors and adding generic JSON helpers. Interfaces: - Provider — Do(req *http.Request) (*http.Response, error) Implementation: - New(logger, cfg) Provider — configures net.Dialer + retry + circuit breaker - NewWithDefaults(logger) Provider — convenience constructor with default config - Retry: avast/retry-go; configurable MaxRetries and RetryDelay; retries on network errors and 5xx responses; logs each retry attempt at Warn level - Circuit breaker: sony/gobreaker; opens after CBThreshold consecutive failures within CBTimeout window; returns ErrUnavailable when open - DoJSON[T](ctx, client, req) (*T, error) — executes request, decodes JSON body - DoJSONRequest[Req, Resp](ctx, client, method, rawURL, body) (*Resp, error) — marshals body, builds request, executes, decodes response - MapStatusToError(code, msg) error — maps HTTP status codes to xerrors values Config (EINHERJAR_HTTP_* env vars): Name(http), Timeout(30s), DialTimeout(5s), MaxRetries(3), RetryDelay(1s), CBThreshold(10), CBTimeout(1m) - identifiable.go: package-level Module variable (observability.Identifiable) for version identification — httpclient is a stateless provider; not registered with the launcher
45 lines
1.8 KiB
Go
45 lines
1.8 KiB
Go
// Package httpclient provides a resilient HTTP client with automatic retry,
|
|
// circuit breaking, request-ID propagation, and typed JSON helpers.
|
|
//
|
|
// # Basic Usage
|
|
//
|
|
// client := httpclient.NewWithDefaults(logger)
|
|
// resp, err := client.Do(req)
|
|
//
|
|
// # Typed JSON Helpers
|
|
//
|
|
// DoJSON decodes the response body into T without needing a manual http.Request:
|
|
//
|
|
// type UserResp struct{ ID, Name string }
|
|
// req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
|
|
// user, err := httpclient.DoJSON[UserResp](ctx, client, req)
|
|
//
|
|
// DoJSONRequest marshals a request body, sends it, and decodes the response:
|
|
//
|
|
// result, err := httpclient.DoJSONRequest[CreateReq, CreateResp](
|
|
// ctx, client, http.MethodPost, url, createReq)
|
|
//
|
|
// # Request ID Propagation
|
|
//
|
|
// If the context carries a request ID (set by core/logz.WithRequestID or the
|
|
// web/mw.RequestID middleware), it is forwarded as X-Request-ID on every
|
|
// outbound attempt, including retries.
|
|
//
|
|
// # Resilience
|
|
//
|
|
// The retry loop (avast/retry-go) wraps individual HTTP attempts. The circuit
|
|
// breaker (sony/gobreaker) wraps the entire retry sequence, so the breaker
|
|
// opens after CBThreshold fully-exhausted retry sequences fail — not after
|
|
// CBThreshold individual HTTP errors.
|
|
//
|
|
// # Configuration
|
|
//
|
|
// EINHERJAR_HTTP_CLIENT_NAME — circuit breaker label; default "http"
|
|
// EINHERJAR_HTTP_TIMEOUT — total request timeout; default 30s
|
|
// EINHERJAR_HTTP_DIAL_TIMEOUT — TCP dial timeout; default 5s
|
|
// EINHERJAR_HTTP_MAX_RETRIES — attempts per request; default 3
|
|
// EINHERJAR_HTTP_RETRY_DELAY — base delay between retries; default 1s
|
|
// EINHERJAR_HTTP_CB_THRESHOLD — consecutive failures to open breaker; default 10
|
|
// EINHERJAR_HTTP_CB_TIMEOUT — breaker half-open probe interval; default 1m
|
|
package httpclient
|