152 lines
2.7 KiB
Markdown
152 lines
2.7 KiB
Markdown
# 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 ./...
|
|
```
|