Documentation
¶
Overview ¶
Package backoff provides centralized retry and backoff utilities using github.com/cenkalti/backoff/v5.
This package offers helpers for exponential backoff with jitter, context cancellation, structured logging, and metrics hooks. It unifies retry logic across the codebase, replacing bespoke implementations in rollouts, nodeagent, and SSE clients.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Permanent ¶
Permanent wraps the given error in a *PermanentError to prevent retries. Use this to signal that an error should not be retried (e.g., validation errors, 4xx HTTP status). The underlying backoff.Retry will stop immediately when encountering a permanent error.
func PollWithBackoff ¶
func PollWithBackoff(ctx context.Context, policy Policy, logger *slog.Logger, condition func() (bool, error)) error
PollWithBackoff polls a condition function with exponential backoff until it returns true. Similar to RunWithBackoff but designed for polling: retries when condition returns (false, nil). Logs each poll attempt with structured fields (attempt, status, backoff_duration). Returns nil if condition succeeds, or error if max attempts exhausted or operation fails.
func RunWithBackoff ¶
RunWithBackoff executes an operation with exponential backoff and retries. Uses the configured policy to determine intervals, max attempts, and jitter. Logs each retry attempt with structured fields (attempt, backoff_duration). Honors context cancellation and returns early if context is done. Returns nil if the operation succeeds, or the last error if max attempts exhausted.
Types ¶
type Policy ¶
type Policy struct {
InitialInterval types.Duration
MaxInterval types.Duration
Multiplier float64
MaxElapsedTime types.Duration
MaxAttempts int
}
Policy encapsulates exponential backoff configuration. Used to create backoff instances for retry operations.
func CertificateBootstrapPolicy ¶
func CertificateBootstrapPolicy() Policy
CertificateBootstrapPolicy returns a policy for nodeagent certificate request retries. Starts at 1s with 2x multiplier and 5 total attempts (initial + 4 retries). Matches existing certificate bootstrap retry behavior (1s, 2s, 4s, 8s, 16s).
func ClaimLoopPolicy ¶
func ClaimLoopPolicy() Policy
ClaimLoopPolicy returns a policy for nodeagent claim loop polling. Starts at 250ms and caps at 5s to match existing claim loop behavior.
func HeartbeatPolicy ¶
func HeartbeatPolicy() Policy
HeartbeatPolicy returns a policy for nodeagent heartbeat backoff. Starts at 5s and caps at 5m to match existing heartbeat behavior.
func RolloutPolicy ¶
func RolloutPolicy() Policy
RolloutPolicy returns a policy configured for rollout operations. Matches existing rollout backoff defaults: 2s initial, 30s max, 2.0 multiplier.
func SSEStreamPolicy ¶
func SSEStreamPolicy() Policy
SSEStreamPolicy returns a policy for SSE stream reconnect backoff. Starts at 250ms with 2x multiplier, matching existing SSE default. Uses unlimited retries (-1) unless caller configures MaxRetries. This policy provides a base configuration; callers override MaxAttempts via Client.MaxRetries.
func StatusUploaderPolicy ¶
func StatusUploaderPolicy() Policy
StatusUploaderPolicy returns a policy for nodeagent status upload retries. Starts at 100ms with 2x multiplier and 4 total attempts (initial + 3 retries). Matches existing status uploader retry behavior.
func (Policy) NewExponentialBackoff ¶
func (p Policy) NewExponentialBackoff() *backoff.ExponentialBackOff
NewExponentialBackoff creates a backoff.ExponentialBackOff from the policy. Configures initial interval, max interval, multiplier, randomization factor (jitter). Callers use this with backoff.Retry and options like WithMaxTries, WithMaxElapsedTime.
type StatefulBackoff ¶
type StatefulBackoff struct {
// contains filtered or unexported fields
}
StatefulBackoff manages exponential backoff state for scenarios where backoff needs to persist across events (e.g., heartbeat failures, claim loop polling). Callers trigger backoff via Apply() on errors and reset via Reset() on success. GetDuration() returns the current or next backoff interval.
func NewStatefulBackoff ¶
func NewStatefulBackoff(policy Policy) *StatefulBackoff
NewStatefulBackoff creates a StatefulBackoff from a policy. Useful for long-running loops that maintain backoff state across iterations.
func (*StatefulBackoff) Apply ¶
func (s *StatefulBackoff) Apply() types.Duration
Apply triggers backoff, advancing to the next interval. Should be called on retry-triggering events (errors, no work available). Returns the new backoff duration.
func (*StatefulBackoff) GetDuration ¶
func (s *StatefulBackoff) GetDuration() types.Duration
GetDuration returns the current backoff duration. If backoff has not been applied, returns the initial interval.
func (*StatefulBackoff) Reset ¶
func (s *StatefulBackoff) Reset()
Reset clears backoff state, returning to the initial interval. Should be called on successful operations to reset exponential growth.
Source Files