github.com/cenkalti/backoff/v5 v5.0.3: BackOff

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/cenkalti/backoff/v5.BackOff in pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3
Demonstrate these symbols/APIs:
  - github.com/cenkalti/backoff/v5.BackOff

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:74725bc1c13fdbee7853f3e24d15efc016f300b4c3f3853c44a3cf0b15be237e","contract":["BackOff interface defines NextBackOff and Reset methods satisfied by custom retry strategies","BackOff implementations can return backoff.Stop to terminate retry loops","BackOff.Reset restores the initial backoff state allowing policy reuse","Built-in types ZeroBackOff, StopBackOff, and ConstantBackOff satisfy the BackOff interface","BackOff implementations control retry intervals and termination when used with backoff.WithBackOff"],"goal":"verify github.com/cenkalti/backoff/v5.BackOff in pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3","kind":"HOW","packages":["pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3"],"schemaVersion":1,"symbols":["github.com/cenkalti/backoff/v5.BackOff"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3"],"schemaVersion":1,"subject":"pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3","symbols":["github.com/cenkalti/backoff/v5.BackOff"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

require github.com/cenkalti/backoff/v5 v5.0.3

github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=
github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=

package main

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

	"github.com/cenkalti/backoff/v5"
)

// stepBackOff is a custom implementation of the backoff.BackOff interface.
type stepBackOff struct {
	attempts int
	maxSteps int
	step     time.Duration
}

func newStepBackOff(step time.Duration, maxSteps int) *stepBackOff {
	return &stepBackOff{
		attempts: 0,
		maxSteps: maxSteps,
		step:     step,
	}
}

func (s *stepBackOff) Reset() {
	s.attempts = 0
}

func (s *stepBackOff) NextBackOff() time.Duration {
	if s.attempts >= s.maxSteps {
		return backoff.Stop
	}
	s.attempts++
	return time.Duration(s.attempts) * s.step
}

// Compile-time check that stepBackOff implements backoff.BackOff.
var _ backoff.BackOff = (*stepBackOff)(nil)

func main() {
	policy := newStepBackOff(10*time.Millisecond, 5)

	attempt := 0
	op := func() (string, error) {
		attempt++
		if attempt < 3 {
			return "", errors.New("temporary service error")
		}
		return "operation completed successfully", nil
	}

	result, err := backoff.Retry(
		context.Background(),
		op,
		backoff.WithBackOff(policy),
	)
	if err != nil {
		fmt.Printf("operation failed: %v\n", err)
		return
	}

	fmt.Printf("result: %s (after %d attempts)\n", result, attempt)
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/cenkalti/backoff/v5.BackOff in pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/cenkalti/backoff/v5@v5.0.3"
  ],
  "symbols": [
    "github.com/cenkalti/backoff/v5.BackOff"
  ]
}

package main

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

	"github.com/cenkalti/backoff/v5"
)

// customTracker implements backoff.BackOff for contract validation.
type customTracker struct {
	resetCalled int
	nextCalled  int
	intervals   []time.Duration
	stopAt      int
}

func newCustomTracker(intervals []time.Duration, stopAt int) *customTracker {
	return &customTracker{
		intervals: intervals,
		stopAt:    stopAt,
	}
}

func (c *customTracker) Reset() {
	c.resetCalled++
	c.nextCalled = 0
}

func (c *customTracker) NextBackOff() time.Duration {
	c.nextCalled++
	if c.stopAt > 0 && c.nextCalled >= c.stopAt {
		return backoff.Stop
	}
	if len(c.intervals) > 0 {
		idx := c.nextCalled - 1
		if idx < len(c.intervals) {
			return c.intervals[idx]
		}
	}
	return 0
}

func main() {
	// Assertion 1: BackOff interface defines NextBackOff and Reset methods satisfied by custom retry strategies
	{
		var b backoff.BackOff = &customTracker{}
		b.Reset()
		d := b.NextBackOff()
		if d < 0 && d != backoff.Stop {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: invalid duration %v\n", d)
			os.Exit(1)
		}
	}

	// Assertion 2: BackOff implementations can return backoff.Stop to terminate retry loops
	{
		tracker := newCustomTracker(nil, 1)
		attempts := 0
		errExpected := errors.New("aborted")
		_, err := backoff.Retry(context.Background(), func() (int, error) {
			attempts++
			return 0, errExpected
		}, backoff.WithBackOff(tracker))

		if err == nil || !errors.Is(err, errExpected) {
			fmt.Fprintf(os.Stderr, "assertion 2 failed: expected error %v, got %v\n", errExpected, err)
			os.Exit(1)
		}
		if attempts != 1 {
			fmt.Fprintf(os.Stderr, "assertion 2 failed: expected 1 attempt when returning Stop, got %d\n", attempts)
			os.Exit(1)
		}
	}

	// Assertion 3: BackOff.Reset restores the initial backoff state allowing policy reuse
	{
		tracker := newCustomTracker([]time.Duration{10 * time.Millisecond, 20 * time.Millisecond, 40 * time.Millisecond}, 0)
		first := tracker.NextBackOff()
		second := tracker.NextBackOff()
		if first != 10*time.Millisecond || second != 20*time.Millisecond {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: unexpected initial sequence: %v, %v\n", first, second)
			os.Exit(1)
		}

		tracker.Reset()
		afterReset := tracker.NextBackOff()
		if afterReset != 10*time.Millisecond {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected 10ms after Reset, got %v\n", afterReset)
			os.Exit(1)
		}
	}

	// Assertion 4: Built-in types ZeroBackOff, StopBackOff, and ConstantBackOff satisfy the BackOff interface
	{
		var zero backoff.BackOff = &backoff.ZeroBackOff{}
		var stop backoff.BackOff = &backoff.StopBackOff{}
		var constant backoff.BackOff = backoff.NewConstantBackOff(25 * time.Millisecond)

		if zero.NextBackOff() != 0 {
			fmt.Fprintf(os.Stderr, "assertion 4 failed: ZeroBackOff did not return 0\n")
			os.Exit(1)
		}
		if stop.NextBackOff() != backoff.Stop {
			fmt.Fprintf(os.Stderr, "assertion 4 failed: StopBackOff did not return Stop\n")
			os.Exit(1)
		}
		if constant.NextBackOff() != 25*time.Millisecond {
			fmt.Fprintf(os.Stderr, "assertion 4 failed: ConstantBackOff did not return 25ms\n")
			os.Exit(1)
		}
	}

	// Assertion 5: BackOff implementations control retry intervals and termination when used with backoff.WithBackOff
	{
		tracker := newCustomTracker([]time.Duration{0, 0, 0}, 5)
		attempts := 0
		res, err := backoff.Retry(context.Background(), func() (string, error) {
			attempts++
			if attempts < 3 {
				return "", errors.New("temporary error")
			}
			return "success", nil
		}, backoff.WithBackOff(tracker))

		if err != nil {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: unexpected error: %v\n", err)
			os.Exit(1)
		}
		if res != "success" || attempts != 3 {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: expected success after 3 attempts, got res=%q, attempts=%d\n", res, attempts)
			os.Exit(1)
		}
		if tracker.resetCalled == 0 {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: expected Reset to be called by Retry\n")
			os.Exit(1)
		}
		if tracker.nextCalled != 2 {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: expected 2 calls to NextBackOff, got %d\n", tracker.nextCalled)
			os.Exit(1)
		}
	}

	fmt.Println("All contract assertions passed.")
}