Add new backoff package with functional strategies.

Author: jmalloc

Diff for: backoff/doc.go

@@ -0,0 +1,3 @@
+// Package backoff provides a system for introducing delays between retries of
+// an operation.
+package backoff

Diff for: backoff/ginkgo_test.go

@@ -0,0 +1,15 @@
+package backoff_test
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/onsi/ginkgo"
+	"github.com/onsi/gomega"
+)
+
+func TestSuite(t *testing.T) {
+	type tag struct{}
+	gomega.RegisterFailHandler(ginkgo.Fail)
+	ginkgo.RunSpecs(t, reflect.TypeOf(tag{}).PkgPath())
+}

Diff for: backoff/strategy.go

@@ -0,0 +1,75 @@
+package backoff
+
+import (
+	"math"
+	"time"
+
+	"github.com/dogmatiq/linger"
+)
+
+// DefaultStrategy is the default strategy used if none is specified.
+//
+// It is a conservative policy favouring large delay times under the assumption
+// that the operation is expensive.
+var DefaultStrategy Strategy = WithTransforms(
+	Exponential(3*time.Second),
+	linger.FullJitter,
+	linger.Limiter(0, 1*time.Hour),
+)
+
+// Strategy is a function for computing delays between attempts to perform some
+// application-defined operation.
+//
+// n is the number of successive failures since the last success.
+//
+// err is the error describing the operation's failure, if known. A nil error
+// does not indicate a success.
+type Strategy func(n int, err error) time.Duration
+
+// Exponential returns a Strategy that uses binary exponential backoff (BEB).
+//
+// The unit delay is doubled after each successive failure.
+func Exponential(unit time.Duration) Strategy {
+	if unit <= 0 {
+		panic("the unit duration must be postive")
+	}
+
+	u := unit.Seconds()
+
+	return func(n int, _ error) time.Duration {
+		scale := math.Pow(2, float64(n-1))
+		seconds := u * scale
+
+		return linger.FromSeconds(seconds)
+	}
+}
+
+// Constant returns a Strategy that returns a fixed wait duration.
+func Constant(d time.Duration) Strategy {
+	return func(_ int, _ error) time.Duration {
+		return d
+	}
+}
+
+// Linear returns a Strategy that increases the wait duration linearly.
+//
+// The unit delay is multiplied by the number of successive failures.
+func Linear(unit time.Duration) Strategy {
+	return func(n int, _ error) time.Duration {
+		return time.Duration(n) * unit
+	}
+}
+
+// WithTransforms returns a strategy that transforms the result of s using each
+// of the given transforms in order.
+func WithTransforms(s Strategy, transforms ...linger.DurationTransform) Strategy {
+	return func(n int, err error) time.Duration {
+		d := s(n, err)
+
+		for _, x := range transforms {
+			d = x(d)
+		}
+
+		return d
+	}
+}

Diff for: backoff/strategy_test.go

@@ -0,0 +1,62 @@
+package backoff
+
+import (
+	"time"
+
+	"github.com/dogmatiq/linger"
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("func Exponential()", func() {
+	It("returns a strategy that backs-off exponentially", func() {
+		strategy := Exponential(3 * time.Second)
+
+		Expect(strategy(5, nil)).To(Equal(48 * time.Second))
+		Expect(strategy(6, nil)).To(Equal(96 * time.Second))
+	})
+
+	It("panics if the unit is zero", func() {
+		Expect(func() {
+			Exponential(0)
+		}).To(Panic())
+	})
+
+	It("panics if the unit is negative", func() {
+		Expect(func() {
+			Exponential(-1)
+		}).To(Panic())
+	})
+})
+
+var _ = Describe("func Constant()", func() {
+	It("returns a strategy that returns a fixed duration", func() {
+		strategy := Constant(3 * time.Second)
+
+		Expect(strategy(5, nil)).To(Equal(3 * time.Second))
+		Expect(strategy(6, nil)).To(Equal(3 * time.Second))
+	})
+})
+
+var _ = Describe("func Linear()", func() {
+	It("returns a strategy that returns a fixed duration", func() {
+		strategy := Linear(3 * time.Second)
+
+		Expect(strategy(5, nil)).To(Equal(15 * time.Second))
+		Expect(strategy(6, nil)).To(Equal(18 * time.Second))
+	})
+})
+
+var _ = Describe("func WithTransform()", func() {
+	It("returns a strategy that that transforms the result of the input strategy", func() {
+		s := WithTransforms(
+			Linear(10*time.Second),
+			linger.Limiter(15*time.Second, linger.MaxDuration),
+			linger.Limiter(0, 25*time.Second),
+		)
+
+		Expect(s(1, nil)).To(Equal(15 * time.Second))
+		Expect(s(2, nil)).To(Equal(20 * time.Second))
+		Expect(s(3, nil)).To(Equal(25 * time.Second))
+	})
+})