Control.Retry

module Control.Retry

Runs bounded retries with a reusable schedule.

Retry.run executes the block immediately. An Ok stops the run; an Error schedules another attempt. When attempts or total sleep run out, the last error is returned unchanged. Runtime faults are not caught.

HTTP responses, including 429 and 503, are Ok(response). Automatic retries handle request failures, not response statuses. Use again and done to classify responses or stop on permanent errors. Repeat writes only when the application makes them safe, for example with idempotency keys. A schedule bounds retry sleep, not the operation's execution time; configure request timeouts separately.

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

module Control.Retry.Retry

Provides automatic error retries and explicit retry decisions.

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

Retry.again("pending")

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

Retry.done(Error("invalid credentials"))

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

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

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

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

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

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

record Schedule

Describes the timing and limits of one execution of run.

All fields are optional. Defaults allow three attempts with exponential backoff from 100 milliseconds, capped at 5 seconds, with 20% jitter. Creating a schedule performs no work. It is immutable configuration: each run starts a fresh attempt count and delay sequence.

• 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.

Examples

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
  Ok("ready")
end
# => Ok("ready"), immediately, without sleeping

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
}

Share settings, not an attempt budget

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.

Fields

attempts

Integer optional

delay

Duration optional

backoff

Float optional

maximumDelay

Duration optional

jitter

Float optional

maximumTotalDelay

Duration? optional

type Decision<X>

Carries an explicit decision and the last application value. Done(value) means the block stopped deliberately. Again(value) returned by run means the schedule was exhausted before completion. Neither form wraps the application value in an additional Result.

Variants

• Again(X)
• Done(X)

record Info<X>

Describes a retry that is about to wait and then execute another attempt.

Passed to onRetry only after the last outcome requests a retry and the schedule permits it. There is no notification for the initial call, success, explicit completion, or exhaustion. Reporting does not consume attempts. Durations describe scheduled sleep, not wall-clock elapsed time.

• 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