backoff/README.md

# 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.

```bash
git clone <your-repo-url>
cd backoff
```

## Library Usage

Import the Fibonacci backoff package:

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

### Basic usage with `Next()`

```go
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()`

```go
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:

```bash
go build -o backoff ./cli
```

Run:

```bash
./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:

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

Sleep for the computed delay:

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

Use jitter:

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

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

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

## Development

Run tests:

```bash
go test ./...
```