Documentation
¶
Overview ¶
Package retry is an http.RoundTripper middleware that provides automatic, policy-driven retries for HTTP requests.
It wraps an existing http.RoundTripper (such as http.DefaultTransport) and intercepts requests to apply retry logic. The decision to retry is controlled by a Policy, and the delay between attempts is determined by a backoff.Strategy.
Usage ¶
A new transport is created with NewTransport, configured with functional options like WithAttemptLimit and WithBackoff.
Example:
// Retry up to 3 times with exponential backoff starting at 1 second.
transport := retry.NewTransport(
http.DefaultTransport,
retry.WithAttemptLimit(3),
retry.WithBackoff(backoff.New(
backoff.WithMinDelay(1*time.Second),
)),
)
client := &http.Client{Transport: transport}
// This request will be retried automatically on temporary failures.
res, err := client.Get("http://example.com/flaky")
if err != nil {
slog.Error("Request failed after all retries", "error", err)
return
}
defer res.Body.Close()
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewTransport ¶
func NewTransport( next http.RoundTripper, opts ...Option, ) http.RoundTripper
NewTransport creates and returns a new retrying http.RoundTripper. It wraps an existing transport and retries requests based on the configured policy and backoff strategy.
Types ¶
type Attempt ¶
Attempt encapsulates the state of a single HTTP request attempt. It is passed to a Policy to determine if a retry is warranted.
func (Attempt) Idempotent ¶
Idempotent reports whether the request can be safely retried without unintended side effects. It considers standard HTTP methods that are idempotent according to RFC 7231.
func (Attempt) Temporary ¶
Temporary reports whether the response indicates a server-side temporary failure. This is determined by specific HTTP status codes that suggest the request might succeed if retried.
func (Attempt) Transient ¶
Transient reports whether the error suggests a temporary network-level issue that might be resolved on a subsequent attempt. It returns true for network timeouts and unexpected EOF errors.
It returns false for context cancellations (context.Canceled, context.DeadlineExceeded), as these are intentional and should not be retried.
type Option ¶
type Option func(*config)
Option is a function that configures the retry transport.
func WithAttemptLimit ¶
WithAttemptLimit sets the maximum number of attempts for a request, including the initial one. A value of 3 means one initial attempt and up to two retries. A value of 1 effectively disables retries. If the value is 0 or less, no limit is enforced and retries are governed solely by the policy.
func WithBackoff ¶
WithBackoff sets the backoff strategy for calculating the delay between retries. If not provided, there is no delay between attempts. A nil value is ignored.
func WithClock ¶
WithClock provides a custom time source, primarily for testing. If not provided, time.Now is used. A nil value is ignored.
func WithLogger ¶
WithLogger sets the logger for debug messages. If not provided, slog.Default() is used. A nil value is ignored.
func WithPolicy ¶
WithPolicy sets the retry policy used by the transport. If not provided, DefaultPolicy is used. A nil value is ignored.
type Policy ¶
Policy is the central decision-making function that determines whether a request should be retried. It is invoked after each attempt with the corresponding Attempt details. It returns true to schedule a retry or false to stop and return the last response/error.
func DefaultPolicy ¶
func DefaultPolicy() Policy
DefaultPolicy provides a safe and sensible default retry strategy. It enters the retry loop only for idempotent requests that have resulted in a temporary server error or a transient network error such as a timeout.
func (Policy) LimitAttempts ¶
LimitAttempts decorates a Policy to enforce a maximum attempt limit.
It short-circuits the decision, returning false if the attempt count has reached the limit n. Otherwise, it delegates the decision to the wrapped policy. A limit of n means a request will be attempted at most n times (e.g., an initial attempt and n-1 retries). A limit of 1 disables retries.
Source Files