The highest tagged major version is
Documentation
¶
Overview ¶
Package call provides a resilient HTTP client with retry, circuit breaker, and timeout support using a composable builder pattern.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCircuitOpen = errors.New("circuit breaker is open")
ErrCircuitOpen is returned when a circuit breaker is in the Open state and rejects requests.
Functions ¶
This section is empty.
Types ¶
type Breaker ¶
type Breaker interface {
// Allow checks whether a request may proceed. Returns ErrCircuitOpen
// (or similar) when the circuit is open.
Allow() error
// Record reports the outcome of a request so the breaker can update state.
Record(success bool)
}
Breaker defines the circuit breaker behavior. Consumers can provide their own implementation (e.g., wrapping sony/gobreaker) via WithBreaker.
type CircuitBreaker ¶
type CircuitBreaker struct {
// contains filtered or unexported fields
}
CircuitBreaker implements the circuit breaker pattern. It tracks consecutive failures and short-circuits requests when the failure threshold is reached, giving the downstream service time to recover.
func GetBreaker ¶
func GetBreaker(name string, threshold int, resetTimeout time.Duration) *CircuitBreaker
GetBreaker returns an existing circuit breaker for the given name or creates a new one with the provided threshold and reset timeout. Breakers are singletons keyed by name.
func (*CircuitBreaker) Allow ¶
func (cb *CircuitBreaker) Allow() error
Allow checks whether a request is permitted through the breaker. It returns nil when the request may proceed or ErrCircuitOpen when it must be rejected.
func (*CircuitBreaker) Record ¶
func (cb *CircuitBreaker) Record(success bool)
Record reports the outcome of a request to the breaker so it can update its internal state accordingly.
func (*CircuitBreaker) State ¶
func (cb *CircuitBreaker) State() State
State returns the current state of the circuit breaker. The internal probing state is reported as StateHalfOpen to external consumers.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a resilient HTTP client that wraps the standard http.Client with optional retry, circuit breaker, and timeout middleware. Construct one using New with functional options.
func New ¶
New creates a Client with the given options applied. Without options it behaves like a default http.Client with a 30-second timeout.
func (*Client) Batch ¶ added in v1.4.0
func (c *Client) Batch(ctx context.Context, requests []*http.Request, opts ...work.Option) ([]*http.Response, error)
Batch executes multiple requests concurrently with bounded concurrency using work.Map. Results are returned in the same order as the input requests.
func (*Client) Do ¶
Do executes an HTTP request with all configured middleware applied. The middleware order is: circuit breaker check, retry loop, execute.
If the request does not carry a context, one is created with the configured timeout. If a context is already present its deadline is respected.
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithBreaker ¶
WithBreaker sets a custom circuit breaker implementation.
func WithCircuitBreaker ¶
WithCircuitBreaker protects the client with a named circuit breaker that opens after threshold consecutive failures and resets after resetTimeout.
func WithRetry ¶
WithRetry enables automatic retries for transient (5xx) errors using exponential backoff with jitter. MaxAttempts is clamped to a minimum of 1.
Note: retries re-send the same *http.Request. For requests with a non-nil Body, the body must be rewindable (implement GetBody) or the retry will send an empty/consumed body. Requests with nil Body (GET, DELETE, HEAD) are always safe to retry.
func WithTimeout ¶
WithTimeout sets the maximum duration for a single HTTP request attempt.
type Retrier ¶
Retrier provides retry logic with exponential backoff and jitter for transient server errors (5xx). It never retries client errors (4xx).
func (*Retrier) Do ¶
func (r *Retrier) Do(ctx context.Context, fn func() (*http.Response, error)) (*http.Response, error)
Do executes fn up to MaxAttempts times, retrying only when a 5xx status code is returned. Between attempts it sleeps with exponential backoff plus random jitter of up to 50% of the calculated delay. It respects context cancellation and deadline, stopping immediately when the context is done.
Source Files