retry: Production Retry Logic for Go

Modern fork of avast/retry-go/v4 focused on correctness, reliability and efficiency. 100% API-compatible drop-in replacement.

Production guarantees:

• Memory bounded: Max 1000 errors stored (configurable via maxErrors constant)
• No goroutine leaks: Uses caller's goroutine exclusively
• Integer overflow safe: Backoff capped at 2^62 to prevent wraparound
• Context-aware: Cancellation checked before each attempt
• No panics: All edge cases return errors
• Predictable jitter: Uses math/rand/v2 for consistent performance
• Zero allocations after init in success path

Quick Start

Installation

go get github.com/codeGROOVE-dev/retry

Simple Retry

// Retry a flaky operation up to 10 times (default)err:=retry.Do(func() error {
returndoSomethingFlaky()
})

Retry with Custom Attempts

// Retry up to 5 times with exponential backofferr:=retry.Do(
func() error {
resp, err:=http.Get("https://api.example.com/data")
iferr!=nil {
returnerr
}
deferresp.Body.Close()
returnnil
},
retry.Attempts(5),
)

Overly-complicated production configuration

// Overly-complex production pattern: bounded retries with circuit breakingerr:=retry.Do(
func() error {
returnprocessPayment(ctx, req)
},
retry.Attempts(3), // Hard limitretry.Context(ctx), // Respect cancellationretry.MaxDelay(10*time.Second), // Cap backoffretry.AttemptsForError(0, ErrRateLimit), // Stop on rate limitretry.OnRetry(func(nuint, errerror) {
log.Printf("retry attempt %d: %v", n, err)
}),
retry.RetryIf(func(errerror) bool {
// Only retry on network errorsvarnetErr net.Errorreturnerrors.As(err, &netErr) &&netErr.Temporary()
}),
)

Preventing Cascading Failures

// Stop retry storms with Unrecoverableiferrors.Is(err, context.DeadlineExceeded) {
returnretry.Unrecoverable(err) // Don't retry timeouts
}
// Per-error type limits prevent thundering herdretry.AttemptsForError(0, ErrCircuitOpen) // Fail fast on circuit breakerretry.AttemptsForError(1, sql.ErrTxDone) // One retry for tx errorsretry.AttemptsForError(5, ErrServiceUnavailable) // More retries for 503s

Changes from avast/retry-go/v4

This fork will always be a 100% compatible drop-in replacement. There are some minor tweaks that have been made though:

New APIs added:

• UntilSucceeded() Option - Convenience wrapper for Attempts(0) (infinite retries)
• FullJitterBackoffDelay() Strategy - New delay type with full jitter exponential backoff
• WrapContextErrorWithLastError() Option - Wraps context errors with last function error
• IfFunc Type - New stutter-proof name (RetryIfFunc is now an alias)

Safety improvements:

• Memory bounded: Max 1000 errors (prevents OOM)
• Uses math/rand/v2 (no lock contention)
• Overflow protection: Backoff capped at 2^62
• Enhanced validation and nil checks
• Better context cancellation with context.Cause()

Documentation

• API Docs
• Examples
• Tests