Rename maxRepeats to maxAttempts, change semantics (#340)

maxRepeats had unclear semantics as to the total number of invocations
when using with retry or repeat. maxAttempts clarifies this, and the
number of invocations of the function is always capped at the number
given to maxAttempts

Author: adamw

README.md

@@ -93,7 +93,7 @@ supervised {
 
 ```scala mdoc:compile-only
 def computationR: Int = ???
-retry(Schedule.exponentialBackoff(100.millis).maxRepeats(5)
+retry(Schedule.exponentialBackoff(100.millis).maxRetries(4)
   .jitter().maxInterval(5.minutes))(computationR)
 ```
 

core/src/main/scala/ox/scheduling/Schedule.scala

@@ -19,11 +19,20 @@ case class Schedule(intervals: () => LazyList[FiniteDuration], initialDelay: Opt
   /** Caps the intervals to the given maximum. */
   def maxInterval(max: FiniteDuration): Schedule = copy(intervals = () => intervals().map(_.min(max)))
 
-  /** Caps the number of repeats to the given maximum, creating a finite schedule. */
-  def maxRepeats(max: Int): Schedule = copy(intervals = () => intervals().take(max))
+  /** Caps the number of attempts to the given maximum, creating a finite schedule. The provided value specifies the total number of
+    * invocations (attempts) of the operation, including the initial invocation.
+    */
+  def maxAttempts(max: Int): Schedule = copy(intervals = () => intervals().take(max - 1))
+
+  /** Caps the number of retries to the given maximum, creating a finite schedule. The provided value specifies the number of retries after
+    * the initial attempt. The total number of invocations will be `retries + 1`.
+    */
+  def maxRetries(retries: Int): Schedule = maxAttempts(retries + 1)
 
-  /** Caps the total delay to the given maximum. The resulting schedule might still be infinite, if the intervals are originally 0. */
-  def maxRepeatsByCumulativeDelay(upTo: FiniteDuration): Schedule = copy(intervals = () =>
+  /** Caps the total delay (cumulative time between attempts) to the given maximum. The resulting schedule might still be infinite, if the
+    * intervals are originally 0.
+    */
+  def maxCumulativeDelay(upTo: FiniteDuration): Schedule = copy(intervals = () =>
     val d = intervals()
     d
       .scanLeft(0.seconds)((cumulative, next) => cumulative + next)

core/src/test/scala/ox/flow/FlowOpsRetryTest.scala

@@ -21,7 +21,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     val flow = Flow.fromValues(1, 2, 3)
 
     // when
-    val result = flow.retry(Schedule.immediate.maxRepeats(3)).runToList()
+    val result = flow.retry(Schedule.immediate.maxRetries(3)).runToList()
 
     // then
     result shouldBe List(1, 2, 3)
@@ -38,7 +38,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     }
 
     // when
-    val result = flow.retry(Schedule.immediate.maxRepeats(maxRetries)).runToList()
+    val result = flow.retry(Schedule.immediate.maxRetries(maxRetries)).runToList()
 
     // then
     result shouldBe List(42)
@@ -58,7 +58,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
 
     // when
     val (result, elapsedTime) = measure {
-      flow.retry(Schedule.fixedInterval(interval).maxRepeats(maxRetries)).runToList()
+      flow.retry(Schedule.fixedInterval(interval).maxRetries(maxRetries)).runToList()
     }
 
     // then
@@ -74,7 +74,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     val flow = Flow
       .fromValues(1, 2, 3)
       .tap(_ => upstreamInvocationCounter.incrementAndGet().discard)
-      .retry(Schedule.immediate.maxRepeats(3))
+      .retry(Schedule.immediate.maxRetries(3))
       .tap { value =>
         downstreamInvocationCounter.incrementAndGet().discard
         if value == 2 then throw new RuntimeException("downstream failure")
@@ -101,7 +101,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
 
     // when/then
     val exception = the[ChannelClosedException.Error] thrownBy {
-      flow.retry(Schedule.immediate.maxRepeats(maxRetries)).runToList()
+      flow.retry(Schedule.immediate.maxRetries(maxRetries)).runToList()
     }
 
     exception.getCause.getMessage shouldBe errorMessage
@@ -122,7 +122,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     }
 
     val config = RetryConfig[Throwable, Unit](
-      Schedule.immediate.maxRepeats(maxRetries),
+      Schedule.immediate.maxRetries(maxRetries),
       ResultPolicy.retryWhen[Throwable, Unit](_.getMessage != fatalErrorMessage)
     )
 
@@ -139,7 +139,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     val flow = Flow.empty[Int]
 
     // when
-    val result = flow.retry(Schedule.immediate.maxRepeats(3)).runToList()
+    val result = flow.retry(Schedule.immediate.maxRetries(3)).runToList()
 
     // then
     result shouldBe List.empty
@@ -153,7 +153,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     }
 
     // when
-    val result = flow.retry(Schedule.immediate.maxRepeats(5)).runToList()
+    val result = flow.retry(Schedule.immediate.maxRetries(5)).runToList()
 
     // then
     result shouldBe List("first try success")
@@ -169,7 +169,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     }
 
     // when
-    val result = flow.retry(Schedule.immediate.maxRepeats(2)).runToList()
+    val result = flow.retry(Schedule.immediate.maxRetries(2)).runToList()
 
     // then
     result shouldBe List(2, 4, 6)
@@ -188,7 +188,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
       }
 
     // when
-    val result = flow.retry(Schedule.immediate.maxRepeats(1)).runToList()
+    val result = flow.retry(Schedule.immediate.maxRetries(1)).runToList()
 
     // then
     result shouldBe List(20, 40)
@@ -199,7 +199,7 @@ class FlowOpsRetryTest extends AnyFlatSpec with Matchers with ElapsedTime:
     val invocationCounter = new AtomicInteger(0)
 
     val flow =
-      Flow.fromValues(1 to 10*).tap(_ => invocationCounter.incrementAndGet().discard).take(3).retry(Schedule.immediate.maxRepeats(3))
+      Flow.fromValues(1 to 10*).tap(_ => invocationCounter.incrementAndGet().discard).take(3).retry(Schedule.immediate.maxRetries(3))
 
     // when
     val result = flow.runToList()

core/src/test/scala/ox/resilience/AfterAttemptTest.scala

@@ -26,7 +26,7 @@ class AfterAttemptTest extends AnyFlatSpec with Matchers with EitherValues with
       returnedResult = result
 
     // when
-    val result = retry(RetryConfig(Schedule.immediate.maxRepeats(3), afterAttempt = afterAttempt))(f)
+    val result = retry(RetryConfig(Schedule.immediate.maxRetries(3), afterAttempt = afterAttempt))(f)
 
     // then
     result shouldBe successfulResult
@@ -52,7 +52,7 @@ class AfterAttemptTest extends AnyFlatSpec with Matchers with EitherValues with
       returnedResult = result
 
     // when
-    val result = the[RuntimeException] thrownBy retry(RetryConfig(Schedule.immediate.maxRepeats(3), afterAttempt = afterAttempt))(f)
+    val result = the[RuntimeException] thrownBy retry(RetryConfig(Schedule.immediate.maxRetries(3), afterAttempt = afterAttempt))(f)
 
     // then
     result shouldBe failedResult

core/src/test/scala/ox/resilience/BackoffRetryTest.scala

@@ -25,7 +25,7 @@ class BackoffRetryTest extends AnyFlatSpec with Matchers with EitherValues with
 
     // when
     val (result, elapsedTime) =
-      measure(the[RuntimeException] thrownBy retry(Schedule.exponentialBackoff(initialDelay).maxRepeats(maxRetries))(f))
+      measure(the[RuntimeException] thrownBy retry(Schedule.exponentialBackoff(initialDelay).maxRetries(maxRetries))(f))
 
     // then
     result should have message "boom"
@@ -63,7 +63,7 @@ class BackoffRetryTest extends AnyFlatSpec with Matchers with EitherValues with
     // when
     val (result, elapsedTime) =
       measure(
-        the[RuntimeException] thrownBy retry(Schedule.exponentialBackoff(initialDelay).maxRepeats(maxRetries).maxInterval(maxDelay))(f)
+        the[RuntimeException] thrownBy retry(Schedule.exponentialBackoff(initialDelay).maxRetries(maxRetries).maxInterval(maxDelay))(f)
       )
 
     // then
@@ -86,7 +86,7 @@ class BackoffRetryTest extends AnyFlatSpec with Matchers with EitherValues with
     val (result, elapsedTime) =
       measure(
         the[RuntimeException] thrownBy retry(
-          Schedule.exponentialBackoff(initialDelay).maxRepeats(maxRetries).maxInterval(maxDelay).jitter(Jitter.Equal)
+          Schedule.exponentialBackoff(initialDelay).maxRetries(maxRetries).maxInterval(maxDelay).jitter(Jitter.Equal)
         )(f)
       )
 
@@ -108,7 +108,7 @@ class BackoffRetryTest extends AnyFlatSpec with Matchers with EitherValues with
       Left(errorMessage)
 
     // when
-    val (result, elapsedTime) = measure(retryEither(Schedule.exponentialBackoff(initialDelay).maxRepeats(maxRetries))(f))
+    val (result, elapsedTime) = measure(retryEither(Schedule.exponentialBackoff(initialDelay).maxRetries(maxRetries))(f))
 
     // then
     result.left.value shouldBe errorMessage

core/src/test/scala/ox/resilience/FixedIntervalRetryTest.scala

@@ -24,7 +24,7 @@ class DelayedRetryTest extends AnyFlatSpec with Matchers with EitherValues with
 
     // when
     val (result, elapsedTime) =
-      measure(the[RuntimeException] thrownBy retry(Schedule.fixedInterval(sleep).maxRepeats(maxRetries))(f))
+      measure(the[RuntimeException] thrownBy retry(Schedule.fixedInterval(sleep).maxRetries(maxRetries))(f))
 
     // then
     result should have message "boom"
@@ -61,7 +61,7 @@ class DelayedRetryTest extends AnyFlatSpec with Matchers with EitherValues with
       Left(errorMessage)
 
     // when
-    val (result, elapsedTime) = measure(retryEither(Schedule.fixedInterval(sleep).maxRepeats(maxRetries))(f))
+    val (result, elapsedTime) = measure(retryEither(Schedule.fixedInterval(sleep).maxRetries(maxRetries))(f))
 
     // then
     result.left.value shouldBe errorMessage

core/src/test/scala/ox/resilience/ImmediateRetryTest.scala

@@ -20,7 +20,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
       successfulResult
 
     // when
-    val result = retry(Schedule.immediate.maxRepeats(3))(f)
+    val result = retry(Schedule.immediate.maxRetries(3))(f)
 
     // then
     result shouldBe successfulResult
@@ -30,7 +30,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
     // given
     var counter = 0
     val errorMessage = "boom"
-    val policy = RetryConfig[Throwable, Unit](Schedule.immediate.maxRepeats(3), ResultPolicy.retryWhen(_.getMessage != errorMessage))
+    val policy = RetryConfig[Throwable, Unit](Schedule.immediate.maxRetries(3), ResultPolicy.retryWhen(_.getMessage != errorMessage))
 
     def f =
       counter += 1
@@ -44,7 +44,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
     // given
     var counter = 0
     val unsuccessfulResult = -1
-    val policy = RetryConfig[Throwable, Int](Schedule.immediate.maxRepeats(3), ResultPolicy.successfulWhen(_ > 0))
+    val policy = RetryConfig[Throwable, Int](Schedule.immediate.maxRetries(3), ResultPolicy.successfulWhen(_ > 0))
 
     def f =
       counter += 1
@@ -67,7 +67,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
       if true then throw new RuntimeException(errorMessage)
 
     // when/then
-    the[RuntimeException] thrownBy retry(Schedule.immediate.maxRepeats(3))(f) should have message errorMessage
+    the[RuntimeException] thrownBy retry(Schedule.immediate.maxRetries(3))(f) should have message errorMessage
     counter shouldBe 4
 
   it should "retry a failing function forever" in:
@@ -97,7 +97,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
       Right(successfulResult)
 
     // when
-    val result = retryEither(Schedule.immediate.maxRepeats(3))(f)
+    val result = retryEither(Schedule.immediate.maxRetries(3))(f)
 
     // then
     result.value shouldBe successfulResult
@@ -107,7 +107,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
     // given
     var counter = 0
     val errorMessage = "boom"
-    val policy: RetryConfig[String, Int] = RetryConfig(Schedule.immediate.maxRepeats(3), ResultPolicy.retryWhen(_ != errorMessage))
+    val policy: RetryConfig[String, Int] = RetryConfig(Schedule.immediate.maxRetries(3), ResultPolicy.retryWhen(_ != errorMessage))
 
     def f: Either[String, Int] =
       counter += 1
@@ -124,7 +124,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
     // given
     var counter = 0
     val unsuccessfulResult = -1
-    val policy: RetryConfig[String, Int] = RetryConfig(Schedule.immediate.maxRepeats(3), ResultPolicy.successfulWhen(_ > 0))
+    val policy: RetryConfig[String, Int] = RetryConfig(Schedule.immediate.maxRetries(3), ResultPolicy.successfulWhen(_ > 0))
 
     def f: Either[String, Int] =
       counter += 1
@@ -147,7 +147,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
       Left(errorMessage)
 
     // when
-    val result = retryEither(Schedule.immediate.maxRepeats(3))(f)
+    val result = retryEither(Schedule.immediate.maxRetries(3))(f)
 
     // then
     result.left.value shouldBe errorMessage
@@ -167,7 +167,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
 
     val adaptive = AdaptiveRetry(TokenBucket(5), 1, 1)
     // when
-    val result = adaptive.retryEither(Schedule.immediate.maxRepeats(5))(f)
+    val result = adaptive.retryEither(Schedule.immediate.maxRetries(5))(f)
 
     // then
     result.value shouldBe "Success"
@@ -184,7 +184,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
 
     val adaptive = AdaptiveRetry(TokenBucket(2), 1, 1)
     // when
-    val result = adaptive.retryEither(Schedule.immediate.maxRepeats(5))(f)
+    val result = adaptive.retryEither(Schedule.immediate.maxRetries(5))(f)
 
     // then
     result.left.value shouldBe errorMessage
@@ -202,7 +202,7 @@ class ImmediateRetryTest extends AnyFlatSpec with EitherValues with TryValues wi
 
     val adaptive = AdaptiveRetry(TokenBucket(2), 1, 1)
     val retryConfig =
-      RetryConfig(Schedule.immediate.maxRepeats(5)).copy(resultPolicy = ResultPolicy.successfulWhen[String, String](_ => false))
+      RetryConfig(Schedule.immediate.maxRetries(5)).copy(resultPolicy = ResultPolicy.successfulWhen[String, String](_ => false))
     // when
     val result = adaptive.retryEither(retryConfig, _ => false)(f)
 

core/src/test/scala/ox/resilience/ScheduleFallingBackRetryTest.scala

@@ -21,7 +21,8 @@ class ScheduleFallingBackRetryTest extends AnyFlatSpec with Matchers with Elapse
       counter += 1
       throw new RuntimeException("boom")
 
-    val schedule = Schedule.immediate.maxRepeats(immediateRetries).andThen(Schedule.fixedInterval(sleep).maxRepeats(delayedRetries))
+    val schedule =
+      Schedule.immediate.maxRetries(immediateRetries).andThen(Schedule.fixedInterval(sleep).maxRetries(delayedRetries))
 
     // when
     val (result, elapsedTime) = measure(the[RuntimeException] thrownBy retry(RetryConfig(schedule))(f))
@@ -41,7 +42,7 @@ class ScheduleFallingBackRetryTest extends AnyFlatSpec with Matchers with Elapse
       counter += 1
       if counter <= retriesUntilSuccess then throw new RuntimeException("boom") else successfulResult
 
-    val schedule = Schedule.immediate.maxRepeats(100).andThen(Schedule.fixedInterval(2.millis))
+    val schedule = Schedule.immediate.maxRetries(100).andThen(Schedule.fixedInterval(2.millis))
 
     // when
     val result = retry(RetryConfig(schedule))(f)

core/src/test/scala/ox/scheduling/FixedRateRepeatTest.scala

@@ -14,7 +14,7 @@ class FixedRateRepeatTest extends AnyFlatSpec with Matchers with EitherValues wi
 
   it should "repeat a function at fixed rate" in:
     // given
-    val repeats = 3
+    val attempts = 3
     val funcSleepTime = 30.millis
     val interval = 100.millis
     var counter = 0
@@ -24,17 +24,17 @@ class FixedRateRepeatTest extends AnyFlatSpec with Matchers with EitherValues wi
       counter
 
     // when
-    val (result, elapsedTime) = measure(repeat(Schedule.fixedInterval(interval).maxRepeats(repeats))(f))
+    val (result, elapsedTime) = measure(repeat(Schedule.fixedInterval(interval).maxAttempts(attempts))(f))
 
     // then
-    elapsedTime.toMillis should be >= 3 * interval.toMillis + funcSleepTime.toMillis - 5 // tolerance
-    elapsedTime.toMillis should be < 4 * interval.toMillis
-    result shouldBe 4
-    counter shouldBe 4
+    elapsedTime.toMillis should be >= 2 * interval.toMillis + funcSleepTime.toMillis - 5 // tolerance
+    elapsedTime.toMillis should be < 3 * interval.toMillis
+    result shouldBe 3
+    counter shouldBe 3
 
   it should "repeat a function at fixed rate with initial delay" in:
     // given
-    val repeats = 3
+    val attempts = 3
     val initialDelay = 50.millis
     val interval = 100.millis
     var counter = 0
@@ -44,13 +44,13 @@ class FixedRateRepeatTest extends AnyFlatSpec with Matchers with EitherValues wi
       counter
 
     // when
-    val (result, elapsedTime) = measure(repeat(Schedule.fixedInterval(interval).maxRepeats(repeats).withInitialDelay(initialDelay))(f))
+    val (result, elapsedTime) = measure(repeat(Schedule.fixedInterval(interval).maxAttempts(attempts).withInitialDelay(initialDelay))(f))
 
     // then
-    elapsedTime.toMillis should be >= 3 * interval.toMillis + initialDelay.toMillis - 5 // tolerance
-    elapsedTime.toMillis should be < 4 * interval.toMillis
-    result shouldBe 4
-    counter shouldBe 4
+    elapsedTime.toMillis should be >= 2 * interval.toMillis + initialDelay.toMillis - 5 // tolerance
+    elapsedTime.toMillis should be < 3 * interval.toMillis
+    result shouldBe 3
+    counter shouldBe 3
 
   it should "repeat a function forever at fixed rate" in:
     // given