README
¶
exponential-backoff
A Go package for computing exponential backoff delays with optional jitter and server delay support.
Installation
go get github.com/rohmanhakim/exponential-backoff
Usage
Basic Example
package main
import (
"fmt"
"time"
"github.com/rohmanhakim/exponential-backoff"
)
func main() {
// Create an immutable config (panics on invalid values)
config := exponentialbackoff.MustConfig(1*time.Second, 1*time.Minute, 2.0)
// Calculate delays for successive backoff attempts
for count := 1; count <= 5; count++ {
delay := exponentialbackoff.CalculateDelay(count, 0, config)
fmt.Printf("Attempt %d: %v\n", count, delay)
}
}
Output:
Attempt 1: 1s
Attempt 2: 2s
Attempt 3: 4s
Attempt 4: 8s
Attempt 5: 16s
Creating Config
The Config struct is immutable and must be created using constructors:
// MustConfig panics on invalid values - use for static configurations
config := exponentialbackoff.MustConfig(1*time.Second, 1*time.Minute, 2.0)
// NewConfig returns an error - use for dynamic configurations
config, err := exponentialbackoff.NewConfig(1*time.Second, 1*time.Minute, 2.0)
if err != nil {
// handle error
}
Validation rules:
initialDurationmust be >= 0maxDurationmust be > 0multipliermust be > 0initialDurationmust be <=maxDuration
With Jitter
Adding jitter helps avoid thundering herd problems in distributed systems:
config := exponentialbackoff.MustConfig(1*time.Second, 1*time.Minute, 2.0)
jitter := 100 * time.Millisecond
delay := exponentialbackoff.CalculateDelay(1, jitter, config)
// delay will be 1s + random(0, 100ms)
With Server Delay
Use server-suggested delays (e.g., from Retry-After headers or whatever):
config := exponentialbackoff.MustConfig(1*time.Second, 1*time.Minute, 2.0)
// Server suggested a 5-second delay
serverDelay := 5 * time.Second
delay := exponentialbackoff.CalculateDelay(1, 0, config,
exponentialbackoff.WithServerDelay(serverDelay))
// delay will be max(1s, 5s) = 5s
API
NewConfig(initialDuration, maxDuration time.Duration, multiplier float64) (Config, error)
Creates a new immutable Config with validation. Returns an error if values are invalid.
MustConfig(initialDuration, maxDuration time.Duration, multiplier float64) Config
Creates a new Config, panicking on invalid values. Use for static configurations where errors are impossible.
Config Methods
| Method | Return Type | Description |
|---|---|---|
InitialDuration() |
time.Duration |
Returns the starting backoff duration |
Multiplier() |
float64 |
Returns the exponential growth factor |
MaxDuration() |
time.Duration |
Returns the maximum backoff cap |
Calculate Delay
CalculateDelay(backoffCount int, jitter time.Duration, config Config, opts ...DelayOption) time.Duration
Computes the delay for a given backoff count using exponential backoff.
Formula: initial * (multiplier ^ (count - 1)) + jitter
- First backoff (count=1):
max(serverDelay, InitialDuration)orInitialDuration - Second backoff (count=2):
initial * multiplier - Capped at
MaxDuration
ComputeJitter(max time.Duration) time.Duration
Returns a random duration between 0 and max (inclusive). Returns 0 if max ≤ 0.
WithServerDelay(d time.Duration) DelayOption
Functional option to set a server-suggested delay. The initial backoff uses max(serverDelay, InitialDuration) as the starting point.
License
MIT License
Documentation
¶
Overview ¶
Package exponentialbackoff provides utilities for computing exponential backoff delays.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CalculateDelay ¶
func CalculateDelay(backoffCount int, jitter time.Duration, config Config, opts ...DelayOption) time.Duration
CalculateDelay computes the delay for a given backoff count using exponential backoff with optional jitter.
The formula is: initial * (multiplier ^ (count - 1)) + jitter
- First backoff (count=1): max(serverDelay, InitialDuration) or InitialDuration
- Second backoff (count=2): initial * multiplier
- And so on, capped at MaxDuration
Parameters:
- backoffCount: The current backoff attempt number (1-indexed)
- jitter: Maximum random duration to add to the delay (0 for no jitter)
- config: Backoff configuration created with NewConfig or MustConfig
- opts: Optional functional options (e.g., WithServerDelay)
Example:
config := exponentialbackoff.MustConfig(1*time.Second, 1*time.Minute, 2.0)
// Basic usage
delay := exponentialbackoff.CalculateDelay(1, 100*time.Millisecond, config)
// With server delay from Retry-After header
delay = exponentialbackoff.CalculateDelay(1, 100*time.Millisecond, config,
exponentialbackoff.WithServerDelay(5*time.Second))
func ComputeJitter ¶
ComputeJitter returns a pseudo-random duration between 0 and max (inclusive). Uses the global rand which is automatically seeded with a random value at startup (Go 1.20+), ensuring different jitter values across concurrent calls. Returns 0 if max is less than or equal to 0.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config holds the immutable configuration for exponential backoff. Create instances using NewConfig or MustConfig.
func MustConfig ¶
MustConfig creates a new Config, panicking on invalid values. Use for static configurations where errors are impossible.
func NewConfig ¶
NewConfig creates a new Config with validation. Returns error if values are invalid:
- initialDuration must be >= 0
- multiplier must be > 0
- maxDuration must be > 0
- initialDuration must be <= maxDuration
func (Config) InitialDuration ¶
InitialDuration returns the starting backoff duration.
func (Config) MaxDuration ¶
MaxDuration returns the maximum backoff duration cap.
func (Config) Multiplier ¶
Multiplier returns the factor by which the backoff increases each attempt.
type DelayOption ¶
type DelayOption func(*delayOptions)
DelayOption is a functional option for CalculateDelay.
func WithServerDelay ¶
func WithServerDelay(d time.Duration) DelayOption
WithServerDelay sets a server-suggested delay (e.g., from Retry-After header). The initial backoff will use max(serverDelay, InitialDuration) as the starting point.
Source Files
Directories