backoff

README

backoff

backoff is a small Go library and CLI for calculating Fibonacci-based retry delays.

The project currently includes:

• A generic Backoff interface (backoff package)
• A FibonacciBackoff implementation (fibonacci package)
• Jitter helpers (utilities package)
• A command-line tool (cli)

Installation

Clone the repo and run commands from the project root.

git clone <your-repo-url>
cd backoff

Library Usage

Import the Fibonacci backoff package:

import "code.wmdillon.com/wmdillon/backoff/fibonacci"

Basic usage with Next()

package main

import (
	"fmt"
	"time"

	"code.wmdillon.com/wmdillon/backoff/fibonacci"
)

func main() {
	b := &fibonacci.FibonacciBackoff{
		PauseMultiplier: time.Millisecond, // 0ms, 1ms, 1ms, 2ms, 3ms, ...
	}

	for i := 0; i < 6; i++ {
		fmt.Println(b.Next())
	}
}

Waiting with context using After()

package main

import (
	"context"
	"fmt"
	"time"

	"code.wmdillon.com/wmdillon/backoff/fibonacci"
)

func main() {
	b := &fibonacci.FibonacciBackoff{
		PauseMultiplier: 250 * time.Millisecond,
		Jitter:          50 * time.Millisecond,
		MaxPause:        2 * time.Second,
	}

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	for i := 0; i < 5; i++ {
		start := time.Now()
		select {
		case <-b.After(ctx):
			fmt.Printf("slept: %s\n", time.Since(start))
		case <-ctx.Done():
			fmt.Println("stopped:", ctx.Err())
			return
		}
	}
}

FibonacciBackoff fields

• Iteration: Current sequence index.
• MaxIteration: Optional upper iteration cap.
• PauseMultiplier: Scales the Fibonacci number (defaults to 1ns when <= 0).
• Jitter: Randomizes each pause in a bounded range.
• MaxPause: Optional duration cap.

CLI Usage

Build:

go build -o backoff ./cli

Run:

./backoff -iteration 10 -multiplier 100ms

Common CLI flags

• -iteration: Fibonacci index to calculate from.
• -multiplier: Duration multiplier, like 250ms or 2s.
• -jitter: Jitter range.
• -format: Output format: string, s, ms, us, µs, ns.
• -sleep: Sleep for the computed delay and print actual run duration.
• -panic: Panic on invalid iteration instead of clamping.

CLI examples

Print one Fibonacci delay in milliseconds:

./backoff -iteration 12 -multiplier 1ms -format ms

Sleep for the computed delay:

./backoff -iteration 8 -multiplier 200ms -sleep

Use jitter:

./backoff -iteration 20 -multiplier 100ms -jitter 25ms -format string

Optional install to $GOBIN (or $GOPATH/bin) as backoff:

go build -o "$(go env GOPATH)/bin/backoff" ./cli

Development

Run tests:

go test ./...

Documentation

Index

• type Backoff

Types

type Backoff

type Backoff interface {
	Reset()
	Next() time.Duration
	After(context.Context) <-chan time.Time
}