automata - v0.2.0

automata/retry

Types

Context

opaque </>

Stateful retry context.

Bundles the immutable Policy, the number of attempts already completed, the cumulative delay charged to the caller so far, and the deterministic PRNG state used by jittered policies. opaque because callers must not forge an attempt counter or rewind the PRNG mid-sequence.

pub opaque type Context

Decision

</>

Result of asking a Context what to do after a failure.

Retry carries the delay the caller should wait before the next attempt and the Context to use when calling decide again. GiveUp carries the structured reason the sequence ended.

pub type Decision {
  Retry(delay: ast.Duration, next: Context)
  GiveUp(reason: ast.GiveUpReason)
}

Constructors

Policy

opaque </>

A retry policy: pure data describing how to retry a failed operation without itself performing any I/O.

opaque so the only way to construct a value is through the validating smart constructors (no_retry, fixed, exponential, capped_exponential). This rules out impossible combinations such as max_attempts <= 0 or a cap below the initial delay, and lets us add new variants (decorrelated jitter, custom backoff, …) without breaking pattern matches in downstream code.

pub opaque type Policy

Values

capped_exponential

</> 
pub fn capped_exponential(
  initial initial: ast.Duration,
  multiplier multiplier: Int,
  cap cap: ast.Duration,
  max_attempts max_attempts: Int,
) -> Result(Policy, ast.RetryError)

Build an exponential backoff that saturates at cap. Equivalent to exponential with an extra ceiling applied to every computed delay.

cumulative_delay

</> 
pub fn cumulative_delay(ctx ctx: Context) -> ast.Duration

Total of the delays the policy has handed out so far. Useful for applying an upper-bound deadline at the call site.

current_attempt

</> 
pub fn current_attempt(ctx ctx: Context) -> Int

Number of attempts already completed in this sequence.

decide

</> 
pub fn decide(
  ctx ctx: Context,
  failure failure: ast.FailureKind,
) -> Decision

Decide what to do after a failed attempt.

Permanent short-circuits regardless of the policy. Transient consults the policy: it may yield a retry delay, the context to use next, or a structured reason to stop.

exponential

</> 
pub fn exponential(
  initial initial: ast.Duration,
  multiplier multiplier: Int,
  max_attempts max_attempts: Int,
) -> Result(Policy, ast.RetryError)

Build an unbounded exponential backoff: the next delay is initial * multiplier ^ (attempt - 1), where attempt is the upcoming try number (1-based).

fixed

</> 
pub fn fixed(
  delay delay: ast.Duration,
  max_attempts max_attempts: Int,
) -> Result(Policy, ast.RetryError)

Build a fixed-delay policy: every retry waits exactly delay, up to max_attempts total tries.

next_delay

</> 
pub fn next_delay(
  ctx ctx: Context,
  failure failure: ast.FailureKind,
) -> Result(ast.Duration, ast.GiveUpReason)

Convenience accessor: the delay component of decide, or the give-up reason as Error.

Does not advance the context — call decide if you intend to act on the answer.

no_retry

</> 
pub fn no_retry() -> Policy

Build a policy that never retries. Any failure (transient or permanent) ends the sequence on the first call to decide.

policy

</> 
pub fn policy(ctx ctx: Context) -> Policy

Recover the policy a context was started from.

should_retry

</> 
pub fn should_retry(
  ctx ctx: Context,
  failure failure: ast.FailureKind,
) -> Bool

Convenience predicate: True when decide would return Retry.

Does not advance the context — call decide if you intend to act on the answer.

start

</> 
pub fn start(policy policy: Policy, seed seed: Int) -> Context

Begin a new retry sequence.

seed deterministically drives any jitter the policy applies. Use the same seed twice and you get the same delay sequence, on the BEAM and on the JavaScript target alike.

with_jitter

</> 
pub fn with_jitter(
  policy policy: Policy,
  jitter jitter: ast.Jitter,
) -> Policy

Decorate an existing policy with a jitter strategy.

no_retry is unaffected (jitter has nothing to spread).

✨ Search Document