example_test.go

package retry_test

import (
	"context"
	"errors"
	"fmt"
	"time"

	"lowbit.dev/retry"
)

// Example demonstrates the most common pattern: exponential back-off with a
// hard limit on total attempts.
func Example() {
	ctx := context.Background()

	err := retry.Do(ctx, retry.MaxAttempts(5, retry.Exponential(100*time.Millisecond, 30*time.Second)), func() error {
		// replace with a real network call, database query, etc.
		return nil
	})
	if err != nil {
		fmt.Println("all attempts failed:", err)
	}
}

// ExampleDo demonstrates retrying a function until it succeeds.
func ExampleDo() {
	calls := 0
	err := retry.Do(context.Background(), retry.MaxAttempts(5, retry.Constant(0)), func() error {
		calls++
		if calls < 3 {
			return errors.New("transient error")
		}
		return nil
	})
	fmt.Println(err)
	fmt.Println("calls:", calls)
	// Output:
	// <nil>
	// calls: 3
}

// ExampleDo_doNotRetry shows that wrapping ErrDoNotRetry stops the loop
// immediately without consulting the strategy.
func ExampleDo_doNotRetry() {
	calls := 0
	err := retry.Do(context.Background(), retry.MaxAttempts(5, retry.Constant(0)), func() error {
		calls++
		return fmt.Errorf("permanent failure: %w", retry.ErrDoNotRetry)
	})
	fmt.Println(errors.Is(err, retry.ErrDoNotRetry))
	fmt.Println("calls:", calls)
	// Output:
	// true
	// calls: 1
}

// ExampleDo_limitExceeded shows that exhausting the strategy wraps the last
// error with ErrRetryLimitExceeded.
func ExampleDo_limitExceeded() {
	calls := 0
	err := retry.Do(context.Background(), retry.MaxAttempts(3, retry.Constant(0)), func() error {
		calls++
		return errors.New("always fails")
	})
	fmt.Println(errors.Is(err, retry.ErrRetryLimitExceeded))
	fmt.Println("calls:", calls)
	// Output:
	// true
	// calls: 3
}

// ExampleStrategy_Do shows calling Do as a method on a Strategy value.
func ExampleStrategy_Do() {
	p := retry.MaxAttempts(3, retry.Constant(0))
	calls := 0
	err := p.Do(context.Background(), func() error {
		calls++
		return errors.New("fail")
	})
	fmt.Println(errors.Is(err, retry.ErrRetryLimitExceeded))
	fmt.Println("calls:", calls)
	// Output:
	// true
	// calls: 3
}

// ExampleExponential shows composition of Exponential with MaxAttempts.
// No Output: the jitter-based delays are non-deterministic.
func ExampleExponential() {
	strategy := retry.MaxAttempts(5, retry.Exponential(100*time.Millisecond, 30*time.Second))
	_ = strategy
}

// ExampleConstant shows that every retry waits the same duration.
func ExampleConstant() {
	p := retry.Constant(500 * time.Millisecond)
	fmt.Println(p(1))
	fmt.Println(p(2))
	fmt.Println(p(3))
	// Output:
	// 500ms
	// 500ms
	// 500ms
}

// ExampleLinear shows that the wait grows linearly: base × attempt.
func ExampleLinear() {
	p := retry.Linear(100 * time.Millisecond)
	fmt.Println(p(1))
	fmt.Println(p(2))
	fmt.Println(p(3))
	// Output:
	// 100ms
	// 200ms
	// 300ms
}

// ExampleMaxAttempts shows that the wrapped strategy returns -1 once n calls
// have been made, signalling Do to stop retrying.
func ExampleMaxAttempts() {
	p := retry.MaxAttempts(3, retry.Constant(0))
	fmt.Println(p(1)) // within limit
	fmt.Println(p(2)) // within limit
	fmt.Println(p(3)) // limit reached
	// Output:
	// 0s
	// 0s
	// -1ns
}

// ExampleNever shows that the strategy stops after the very first failure.
func ExampleNever() {
	calls := 0
	err := retry.Do(context.Background(), retry.Never, func() error {
		calls++
		return errors.New("fail")
	})
	fmt.Println(errors.Is(err, retry.ErrRetryLimitExceeded))
	fmt.Println("calls:", calls)
	// Output:
	// true
	// calls: 1
}

// ExampleAlways shows Always retrying immediately; compose with MaxAttempts
// to add an upper bound.
func ExampleAlways() {
	calls := 0
	err := retry.Do(context.Background(), retry.MaxAttempts(3, retry.Always), func() error {
		calls++
		return errors.New("fail")
	})
	fmt.Println(errors.Is(err, retry.ErrRetryLimitExceeded))
	fmt.Println("calls:", calls)
	// Output:
	// true
	// calls: 3
}