feat(delay): add IncrementalDelayMax method

This method will help in situations that the user want a more flexible
delays between retries. For example, if the user wants to delay up to 10
seconds for some reason.

Author: arsham

retry.go

@@ -7,6 +7,9 @@
 // attempts. You can use the IncrementalDelay method to increment the delays
 // between attempts. It gives a jitter to the delay to prevent Thundering herd
 // problems. If the delay is 0 in either case, it does not sleep between tries.
+// The IncrementalDelay has a maximum delay of 1 second, but if you need a more
+// flexible delay, you can use the IncrementalDelayMax method and give it a max
+// delay.
 package retry
 
 import (
@@ -38,6 +41,7 @@ func (s StopError) Unwrap() error { return s.Err }
 type Retry struct {
 	Method   DelayMethod
 	Delay    time.Duration
+	MaxDelay time.Duration
 	Attempts int
 }
 
@@ -97,14 +101,23 @@ func StandardDelay(_ int, delay time.Duration) time.Duration { return delay }
 // adds a jitter to prevent Thundering herd. If the delay is 0, it always
 // returns 0.
 func IncrementalDelay(attempt int, delay time.Duration) time.Duration {
-	if delay == 0 {
-		return 0
-	}
-	if delay > time.Second {
-		delay = time.Second
+	return IncrementalDelayMax(time.Second)(attempt, delay)
+}
+
+// IncrementalDelayMax returns a DelayMethod that increases the delay between
+// attempts up to the given max duration. It adds a jitter to prevent
+// Thundering herd. If the delay is 0, it always returns 0.
+func IncrementalDelayMax(max time.Duration) func(int, time.Duration) time.Duration {
+	return func(attempt int, delay time.Duration) time.Duration {
+		if delay == 0 {
+			return 0
+		}
+		if delay > max {
+			delay = max
+		}
+		d := int64(delay)
+		// nolint:gosec // the rand package is used for fast random number generation.
+		jitter := rand.Int63n(d) / 2
+		return (delay * time.Duration(attempt)) + time.Duration(jitter)
 	}
-	d := int64(delay)
-	// nolint:gosec // the rand package is used for fast random number generation.
-	jitter := rand.Int63n(d) / 2
-	return (delay * time.Duration(attempt)) + time.Duration(jitter)
 }

retry_example_test.go

@@ -137,6 +137,28 @@ func ExampleIncrementalDelay() {
 	// Error: <nil>
 }
 
+func ExampleIncrementalDelayMax() {
+	// This setup will delay 20ms + 40ms + 50ms + 50ms, and a jitters at 5
+	// attempts, until on the 6th attempt that it would succeed.
+	l := &retry.Retry{
+		Attempts: 6,
+		Delay:    20 * time.Millisecond,
+		Method:   retry.IncrementalDelayMax(50 * time.Millisecond),
+	}
+	i := 0
+	err := l.Do(func() error {
+		i++
+		if i < l.Attempts {
+			return errors.New("ignored error")
+		}
+		return nil
+	})
+	fmt.Println("Error:", err)
+
+	// Output:
+	// Error: <nil>
+}
+
 func ExampleRetry_Do_multipleFuncs() {
 	l := &retry.Retry{
 		Attempts: 4,

retry_test.go

@@ -120,6 +120,7 @@ func testLoopDoPanic(t *testing.T) {
 func testLoopDoSleep(t *testing.T) {
 	t.Run("StandardMethod", testLoopDoSleepStandardMethod)
 	t.Run("IncrementalMethod", testLoopDoSleepIncrementalMethod)
+	t.Run("IncrementalMaxMethod", testLoopDoSleepIncrementalMaxMethod)
 }
 
 func testLoopDoSleepStandardMethod(t *testing.T) {
@@ -179,7 +180,7 @@ func testLoopDoSleepIncrementalMethodUnderSecond(t *testing.T) {
 		fmt.Sprintf("wanted to take more than %s, took %s", expected.Sub(started), finished.Sub(started)),
 	)
 	assert.True(t, finished.Before(expected.Add(6*delay)),
-		fmt.Sprintf("take (%s) more than expected: %s", finished.Sub(started), expected.Add(6*delay)),
+		fmt.Sprintf("took (%s) more than expected: %s", finished.Sub(started), expected.Add(6*delay)),
 	)
 }
 
@@ -210,7 +211,7 @@ func testLoopDoSleepIncrementalMethodOverSecond(t *testing.T) {
 		fmt.Sprintf("wanted to take more than %s, took %s", expected.Sub(started), finished.Sub(started)),
 	)
 	assert.True(t, finished.Before(expected.Add(2*time.Second)),
-		fmt.Sprintf("take (%s) more than expected: %s", finished.Sub(started), 4*time.Second),
+		fmt.Sprintf("took (%s) more than expected: %s", finished.Sub(started), 4*time.Second),
 	)
 }
 
@@ -233,7 +234,98 @@ func testLoopDoSleepIncrementalMethodZero(t *testing.T) {
 
 	expected := started.Add(time.Second)
 	assert.True(t, finished.Before(expected),
-		fmt.Sprintf("take (%s) more than expected: %s", finished.Sub(started), time.Second),
+		fmt.Sprintf("took (%s) more than expected: %s", finished.Sub(started), time.Second),
+	)
+}
+
+func testLoopDoSleepIncrementalMaxMethod(t *testing.T) {
+	t.Run("UnderSecond", testLoopDoSleepIncrementalMaxMethodUnderSecond)
+	t.Run("OverSecond", testLoopDoSleepIncrementalMaxMethodOverTwoSeconds)
+	t.Run("Zero", testLoopDoSleepIncrementalMaxMethodZero)
+}
+
+func testLoopDoSleepIncrementalMaxMethodUnderSecond(t *testing.T) {
+	t.Parallel()
+	// In this setup, the delays would be (almost) 100, 200, 300, 300. So in
+	// almost 900 ms there would be 4 calls. There is a 4*delay amount of
+	// wiggle added.
+	delay := 100 * time.Millisecond
+	l := &retry.Retry{
+		Attempts: 4,
+		Delay:    delay,
+		Method:   retry.IncrementalDelayMax(delay * 3),
+	}
+
+	count := 0
+	started := time.Now()
+	err := l.Do(func() error {
+		count++
+		return assert.AnError
+	})
+	finished := time.Now()
+	expected := started.Add(900 * time.Millisecond)
+
+	assert.Equal(t, l.Attempts, count)
+	assert.ErrorIs(t, err, assert.AnError)
+	assert.True(t, finished.After(expected),
+		fmt.Sprintf("wanted to take more than %s, took %s", expected.Sub(started), finished.Sub(started)),
+	)
+	assert.True(t, finished.Before(expected.Add(6*delay)),
+		fmt.Sprintf("took (%s) more than expected: %s", finished.Sub(started), expected.Add(6*delay)),
+	)
+}
+
+func testLoopDoSleepIncrementalMaxMethodOverTwoSeconds(t *testing.T) {
+	t.Parallel()
+	if testing.Short() {
+		t.Skip("slow test")
+	}
+	l := &retry.Retry{
+		Attempts: 2,
+		Delay:    10 * time.Second,
+		Method:   retry.IncrementalDelayMax(2 * time.Second),
+	}
+
+	count := 0
+	started := time.Now()
+	err := l.Do(func() error {
+		count++
+		return assert.AnError
+	})
+	finished := time.Now()
+	expected := started.Add(4 * time.Second)
+
+	assert.ErrorIs(t, err, assert.AnError)
+	assert.Equal(t, l.Attempts, count)
+
+	assert.True(t, finished.After(expected),
+		fmt.Sprintf("wanted to take more than %s, took %s", expected.Sub(started), finished.Sub(started)),
+	)
+	assert.True(t, finished.Before(expected.Add(2*2*time.Second)),
+		fmt.Sprintf("took (%s) more than expected: %s", finished.Sub(started), 4*time.Second),
+	)
+}
+
+func testLoopDoSleepIncrementalMaxMethodZero(t *testing.T) {
+	t.Parallel()
+	l := &retry.Retry{
+		Attempts: 50,
+		Method:   retry.IncrementalDelayMax(time.Second / 2),
+	}
+
+	count := 0
+	started := time.Now()
+	err := l.Do(func() error {
+		count++
+		return assert.AnError
+	})
+	finished := time.Now()
+	assert.ErrorIs(t, err, assert.AnError)
+	assert.Equal(t, l.Attempts, count)
+
+	expected := started.Add(time.Second)
+	assert.True(t, finished.Before(expected),
+		fmt.Sprintf("took (%s) more than expected: %s", finished.Sub(started), time.Second),
 	)
 }