Control.Retry

module Control.Retry

Retry an operation after it returns an error.

Examples

Retry a request and handle the final result

using Control.Retry
using Net.HTTP

let result = Retry.run(attempts: 5) do
  HTTP.get("https://api.example.com/inventory")
end
match result do
  Ok(response) => IO.printLine(response.status.code)
  Error(error) => IO.printLine(error.message)
end

Fixed delays: three waits of 250 milliseconds

let schedule = Retry.Schedule {
  attempts: 4, delay: 250.milliseconds, backoff: 1.0,
  maximumDelay: 250.milliseconds, jitter: 0.0
}
Retry.run(schedule: schedule) do
  Error("not ready")
end
# => Error("not ready"), after four calls and 750 ms of sleep

Exponential delays: 200, 400, 800, 1600 milliseconds

let schedule = Retry.Schedule {
  attempts: 5, delay: 200.milliseconds, backoff: 2.0,
  maximumDelay: 5.seconds, jitter: 0.0
}
Retry.run(schedule: schedule) do
  Error("busy")
end
# => Error("busy"), after five calls and three seconds of sleep

Capped delays: 500 ms, 1 s, 2 s, 2 s, 2 s

Retry.Schedule {
  attempts: 6, delay: 500.milliseconds, backoff: 2.0,
  maximumDelay: 2.seconds, jitter: 0.0
}

Use one schedule for two requests

using Net.HTTP
let schedule = Retry.Schedule { attempts: 5 }
let inventory = Retry.run(schedule: schedule) do
  HTTP.get("https://api.example.com/inventory")
end
let orders = Retry.run(schedule: schedule) do
  HTTP.get("https://api.example.com/orders")
end
# Each request gets up to five attempts, independently.

Set retry options directly

Retry.run(attempts: 5, delay: 200.milliseconds, jitter: 0.0) do
  Ok("ready")
end
# => Ok("ready")

Limit the time spent sleeping

Retry.run(
  attempts: 5, delay: 1.seconds, backoff: 2.0,
  jitter: 0.0, maximumTotalDelay: Just(2.seconds)
) do
  Error("busy")
end
# => Error("busy"), two calls and one second of sleep

Test jitter without waiting

Retry.run(
  attempts: 2, delay: 4.seconds, jitter: 0.25,
  sleeper: { |wait| Assert.equal(wait, 3.seconds) },
  random: { 0.0 }
) do
  Error("temporary")
end
# => Error("temporary"), two calls and one fake sleep

Report progress

using Net.HTTP
Retry.run(attempts: 5, onRetry: { |info|
  let progress = "retrying ${info.nextAttempt}/${info.maximumAttempts}"
  IO.printLine("${progress} in ${info.delay.seconds} seconds")
}) do
  HTTP.get("https://api.example.com/inventory")
end

Retry temporary HTTP failures and selected statuses

using Net
using Net.HTTP
let schedule = Retry.Schedule { attempts: 5 }
let outcome = Retry.run(schedule: schedule) do
  let result = HTTP.get("https://api.example.com/inventory")
  match result do
    Error(error) => if error.kind == Timeout || error.kind == Connect
      Retry.again(result)
    else
      Retry.done(result)
    end
    Ok(response) => if [429, 502, 503, 504].contains?(response.status.code)
      Retry.again(result)
    else
      Retry.done(result)
    end
  end
end
match outcome do
  Done(result) => IO.printLine(result)
  Again(last) => IO.printLine("retry budget exhausted: ${last}")
end

module Control.Retry.Retry

run calls the block immediately. Ok stops; Error waits and retries. When the schedule runs out, it returns the last error unchanged. Use again and done when your application needs to choose what to retry.

HTTP 429 and 503 responses are Ok(response), so retrying those statuses requires an explicit decision. For writes, make sure repeating the request is safe, for example by using an idempotency key. Set request timeouts separately: the schedule limits sleep, not time spent inside the operation.

again(value: X) -> Decision<X>

done(value: X) -> Decision<X>

run : Block<X> -> Schedule -> Integer -> Duration -> Float -> Duration -> Float -> Duration? -> (Duration -> Void) -> Block<Float> -> (Info<X> -> Void) -> X

record Schedule

Timing and attempt limits for run.

Defaults: three attempts, starting with a 100 ms wait, doubling up to 5 seconds, with 20% jitter. All fields are optional. A schedule holds settings. Reusing it starts each run from attempt one.

• attempts: maximum executions, including the first; default 3. * delay: initial base wait; default 100 milliseconds. * backoff: base-delay multiplier; default 2.0, or 1.0 for fixed waits. * maximumDelay: cap on each actual wait, including jitter; default 5 seconds. * jitter: symmetric proportional variation; default 0.2, or 0.0 to disable. * maximumTotalDelay: cumulative sleep allowance; default None. Operation execution time is excluded. A wait that exceeds the remaining allowance ends the run without sleeping or calling the operation again.

Fields

attempts

Integer optional

delay

Duration optional

backoff

Float optional

maximumDelay

Duration optional

jitter

Float optional

maximumTotalDelay

Duration? optional

type Decision<X>

Whether to retry, together with the last result. Done(value) means the block stopped deliberately. Again(value) returned by run means the schedule was exhausted before completion. The value inside can be any application result, including an Error.

Variants

• Again(X)
• Done(X)

record Info<X>

Progress passed to onRetry before the next wait.

The callback runs only when another attempt is allowed. It does not run for the first call, a successful result, done, or exhaustion. Durations count scheduled sleep; they exclude time spent in the operation.

• attempt: the just-completed attempt, starting at 1. * nextAttempt: the attempt that follows the upcoming wait. * maximumAttempts: total permitted executions, including the first. * remainingAttempts: executions remaining, including the upcoming one. * delay: actual upcoming wait, after jitter and the delay cap. * totalDelay: sleep already performed, excluding the upcoming wait. * result: the last Error or Again, including its application payload.

Fields

attempt

Integer

nextAttempt

Integer

maximumAttempts

Integer

remainingAttempts

Integer

delay

Duration

totalDelay

Duration

result

X