automata/retry/ast

Types

Attempt

Position of a single try inside a retry sequence.

Counts start at 1: the very first invocation is attempt 1, the first retry is attempt 2, and so on. max_attempts therefore means “the total number of tries we are willing to perform” — a max_attempts: 5 policy gives up after the fifth failed attempt.

pub type Attempt =
  Int

Duration

opaque </>

A non-negative span of time, opaque so it can only be built through the validating from_* smart constructors.

Values are stored as integer milliseconds and are guaranteed to lie in [0, max_safe_milliseconds].

pub opaque type Duration

FailureKind

</>

Classification a caller assigns to a failed try.

automata/retry does not interpret error values. The caller decides whether a particular failure is worth re-trying (Transient) or hopeless (Permanent), and the retry module honours that decision.

pub type FailureKind {
  Transient
  Permanent
}

Constructors

```
Transient
```
```
Permanent
```

GiveUpReason

</>

Reason a retry sequence stops.

Each variant carries enough structured context that an LLM or a human operator can understand the decision without parsing prose.

pub type GiveUpReason {
  PolicyDisallowsRetry
  MaxAttemptsReached(attempts: Int, limit: Int)
  PermanentFailureSignaled(at_attempt: Int)
  DelayOverflow(at_attempt: Int)
}

Constructors

```
PolicyDisallowsRetry
```
The policy is no_retry; failure ends the sequence immediately.
```
MaxAttemptsReached(attempts: Int, limit: Int)
```
We have exhausted the policy’s max_attempts budget.

PermanentFailureSignaled(at_attempt: Int)

The caller signalled Permanent failure.

```
DelayOverflow(at_attempt: Int)
```
The next delay would exceed max_safe_milliseconds and was refused before any precision was lost.

Jitter

</>

Strategy used to spread the base delay computed by a policy.

Kept as a regular sum (not opaque) so that automata/retry can dispatch on it. New strategies (for example a bounded-percentage jitter) would be additive and require existing pattern matches to be exhaustive again.

pub type Jitter {
  NoJitter
  FullJitter
  EqualJitter
}

Constructors

```
NoJitter
```
Use the policy’s base delay as-is.
```
FullJitter
```
Spread uniformly across [0, base] (AWS “full jitter”).
```
EqualJitter
```
Spread uniformly across [base / 2, base] (AWS “equal jitter”).

RetryError

</>

Construction-time errors for Duration and Policy.

pub type RetryError {
  NegativeDuration(unit: String, actual: Int)
  DurationOverflow(unit: String, actual: Int)
  MaxAttemptsMustBePositive(actual: Int)
  MultiplierMustBeAtLeastTwo(actual: Int)
  InitialDelayMustBePositive(actual_milliseconds: Int)
  CapMustNotBeLessThanInitial(
    cap_milliseconds: Int,
    initial_milliseconds: Int,
  )
}

Constructors

NegativeDuration(unit: String, actual: Int)

DurationOverflow(unit: String, actual: Int)

```
MaxAttemptsMustBePositive(actual: Int)
```
```
MultiplierMustBeAtLeastTwo(actual: Int)
```

InitialDelayMustBePositive(actual_milliseconds: Int)

CapMustNotBeLessThanInitial(
  cap_milliseconds: Int,
  initial_milliseconds: Int,
)

Values

duration_milliseconds

</>

pub fn duration_milliseconds(duration duration: Duration) -> Int

Recover the raw millisecond value from a duration.

duration_seconds

</>

pub fn duration_seconds(duration duration: Duration) -> Int

Recover the duration in whole seconds, truncating any sub-second remainder.

duration_to_string

</>

pub fn duration_to_string(duration duration: Duration) -> String

Render a duration as "<n>ms".

from_milliseconds

</>

pub fn from_milliseconds(
  milliseconds milliseconds: Int,
) -> Result(Duration, RetryError)

Build a duration from milliseconds.

from_minutes

</>

pub fn from_minutes(
  minutes minutes: Int,
) -> Result(Duration, RetryError)

Build a duration from minutes.

from_seconds

</>

pub fn from_seconds(
  seconds seconds: Int,
) -> Result(Duration, RetryError)

Build a duration from seconds.