improved README.md

README.md

@@ -1,2 +1,151 @@
-# package backoff
+# backoff
-Provides a simple Backoff interface, and currently a single Backoff type (FibonacciBackoff). This can be used to control backoff between requests. It includes a simple function for adding Jitter as well. The `cli` can be built with `go build -C cli`, and can be used for sleeping by scripts.
+
+`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 ./...
+```