backoff

Documentation

Overview

Package backoff computes retry delays for failed task executions. The delay grows with the retry count according to the chosen Kind: exponential (base*2^retried) and linear (base*(retried+1)) grow a ceiling and draw the delay uniformly from [0, ceiling) (full jitter, which spreads retry storms), while fixed returns base exactly, for predictable spacing such as a rate-limited downstream. Every delay is bounded by the configured maximum.

Index

• Constants
• type Kind
  • func ParseKind(name string) (Kind, bool)
• type Strategy
  • func New(base, maxDelay time.Duration) Strategy
  • func NewWithKind(kind Kind, base, maxDelay time.Duration) Strategy
  • func (s Strategy) Base() time.Duration
  • func (s Strategy) Cap() time.Duration
  • func (s Strategy) Delay(retried int32) time.Duration
  • func (s Strategy) Kind() Kind

Constants

const (
	// DefaultBase is the backoff ceiling of the first retry.
	DefaultBase = 2 * time.Second
	// DefaultCap bounds the backoff ceiling regardless of retry count.
	DefaultCap = 15 * time.Minute
)

Server-side retry backoff defaults.

Types

type Kind

type Kind uint8

Kind selects how a Strategy's delay ceiling grows with the retry count.

const (
	// Exponential doubles the ceiling each retry: base*2^retried.
	Exponential Kind = iota
	// Linear grows the ceiling linearly: base*(retried+1).
	Linear
	// Fixed returns base exactly on every retry (no jitter), for predictable
	// spacing such as a steady interval against a rate-limited downstream.
	Fixed
)

func ParseKind

func ParseKind(name string) (Kind, bool)

ParseKind maps a configuration string ("exponential", "linear", "fixed") to a Kind. It returns false for an unrecognized value.

type Strategy

type Strategy struct {
	// contains filtered or unexported fields
}

Strategy computes full-jitter retry delays. The zero value is unusable; build one with New or NewWithKind.

func New

func New(base, maxDelay time.Duration) Strategy

New builds a full-jitter exponential Strategy with the given first-retry ceiling and overall maximum delay.

func NewWithKind

func NewWithKind(kind Kind, base, maxDelay time.Duration) Strategy

NewWithKind builds a Strategy with an explicit growth kind.

func (Strategy) Base

func (s Strategy) Base() time.Duration

Base returns the first-retry delay ceiling.

func (Strategy) Cap

func (s Strategy) Cap() time.Duration

Cap returns the overall maximum delay ceiling.

func (Strategy) Delay

func (s Strategy) Delay(retried int32) time.Duration

Delay returns the retry delay for the attempt. For the growing kinds it is a uniformly random value in [0, ceiling) (full jitter); for Fixed it is base exactly. The ceiling is bounded by maxDelay, and a negative retried counts as zero.

func (Strategy) Kind

func (s Strategy) Kind() Kind

Kind returns the strategy's ceiling-growth kind.