retry

Documentation

Overview

Package retry provides configurable HTTP request retry as client middleware.

The retry middleware wraps an http.RoundTripper and automatically retries failed requests based on a configurable policy, with exponential backoff and optional jitter.

Usage

mw := retry.Transport(
    retry.WithMaxAttempts(3),
    retry.WithBackoff(retry.ExponentialBackoff(100*time.Millisecond, 5*time.Second)),
)
transport := mw(http.DefaultTransport)

Retry-After

The retry middleware respects the Retry-After response header. If a server returns 429 or 503 with Retry-After, the delay from the header overrides the backoff strategy.

Request bodies

For requests with bodies to be retried, the request must have GetBody set. Use httpx.NewJSONRequest or httpx.NewFormRequest which set GetBody automatically.

Sentinel errors

ErrRetryExhausted is returned when all attempts fail. The original error is wrapped and accessible via errors.Unwrap.

Index

• Variables
• func ParseRetryAfter(resp *http.Response) (time.Duration, bool)
• func Transport(opts ...Option) middleware.Middleware
• type Backoff
  • func ConstantBackoff(d time.Duration) Backoff
  • func ExponentialBackoff(base, max time.Duration, withJitter bool) Backoff
• type Option
  • func WithBackoff(b Backoff) Option
  • func WithMaxAttempts(n int) Option
  • func WithPolicy(p Policy) Option
  • func WithRetryAfter(enable bool) Option
• type Policy

Variables

var ErrRetryExhausted = errors.New("httpx: all retry attempts exhausted")

ErrRetryExhausted is returned when all retry attempts have been exhausted and the last attempt also failed.

Functions

func ParseRetryAfter

func ParseRetryAfter(resp *http.Response) (time.Duration, bool)

ParseRetryAfter extracts the delay from a Retry-After header (RFC 7231). It supports both the delay-seconds format ("120") and the HTTP-date format ("Fri, 31 Dec 1999 23:59:59 GMT"). Returns the duration and true if the header was present and valid; otherwise returns 0 and false.

func Transport

func Transport(opts ...Option) middleware.Middleware

Transport returns a middleware that retries failed requests according to the provided options.

Types

type Backoff

type Backoff interface {
	// Delay returns the wait duration for the given attempt number (zero-based).
	Delay(attempt int) time.Duration
}

Backoff computes the delay before the next retry attempt.

func ConstantBackoff

func ConstantBackoff(d time.Duration) Backoff

ConstantBackoff returns a Backoff that always returns the same delay.

func ExponentialBackoff

func ExponentialBackoff(base, max time.Duration, withJitter bool) Backoff

ExponentialBackoff returns a Backoff that doubles the delay on each attempt. The delay is calculated as base * 2^attempt, capped at max. When withJitter is true, a random duration in [0, delay*0.5) is added.

type Option

type Option func(*options)

Option configures the retry transport.

func WithBackoff

func WithBackoff(b Backoff) Option

WithBackoff sets the backoff strategy used to compute delays between retries.

func WithMaxAttempts

func WithMaxAttempts(n int) Option

WithMaxAttempts sets the maximum number of attempts (including the first). Values less than 1 are treated as 1 (no retries).

func WithPolicy

func WithPolicy(p Policy) Option

WithPolicy sets the retry policy that decides whether to retry a request.

func WithRetryAfter

func WithRetryAfter(enable bool) Option

WithRetryAfter controls whether the Retry-After response header is respected. When enabled and present, the Retry-After delay is used if it exceeds the backoff delay.

type Policy

type Policy interface {
	// ShouldRetry reports whether the request should be retried. The extra
	// duration, if non-zero, is a policy-suggested delay that overrides the
	// backoff strategy.
	ShouldRetry(attempt int, req *http.Request, resp *http.Response, err error) (bool, time.Duration)
}

Policy decides whether a failed request should be retried.