rate_limiter

Token-bucket retry rate limiter, port of the AWS Smithy runtime’s TokenBucket (aws-sdk-rust/…/client/retries/token_bucket.rs).

Semantics:

Each retry attempt acquires tokens. The cost depends on the error class (see retry.gleam: retry_cost 5 for normal retryable, timeout_retry_cost 10 for timeouts / transient).
The acquired tokens are HELD as a Permit while the retry is in flight. On success or final non-retryable outcome the caller releases the permit, returning the tokens. On retry-failure-then- -retry, the caller releases the prior permit before acquiring the next (Rust does this via permit drop on set_retry_permit).
reward_success additionally tops up the bucket by success_reward tokens. Rust’s default is 0 — the bucket is a concurrent-retry semaphore, not an AIMD-style limiter; the time-based refill_rate handles long-term recovery in Rust. We follow Rust’s default.

Concurrency: messages are processed sequentially per gleam_otp actor semantics.

Types

AcquireResult

</>

pub type AcquireResult {
  Acquired(permit: Permit)
  Empty
}

Constructors

```
Acquired(permit: Permit)
```
```
Empty
```

Bucket

opaque </>

Opaque bucket handle.

pub opaque type Bucket

BucketState

</>

pub type BucketState {
  BucketState(available: Int, capacity: Int)
}

Constructors

BucketState(available: Int, capacity: Int)

Permit

opaque </>

An acquired set of tokens. Hold this until success or final outcome, then release it to return the tokens to the bucket.

pub opaque type Permit

StartError

</>

pub type StartError {
  StartFailed(actor.StartError)
}

Constructors

```
StartFailed(actor.StartError)
```

Values

current

</>

pub fn current(bucket: Bucket) -> BucketState

Read the current bucket state. Tests only.

default_capacity

</>

pub const default_capacity: Int

Rust SDK default capacity. See DEFAULT_CAPACITY in token_bucket.rs.

default_success_reward

</>

pub const default_success_reward: Int

Rust SDK default success reward. See DEFAULT_SUCCESS_REWARD.

The bucket relies on permit RAII for normal recovery; success_reward is the additional top-up on success and defaults to 0.

permit_cost

</>

pub fn permit_cost(p: Permit) -> Int

release

</>

pub fn release(bucket: Bucket, permit permit: Permit) -> Nil

Return the permit’s tokens to the bucket. Called on success, on a final non-retryable response, and before replacing one held permit with a new one mid-retry-loop.

reward_success

</>

pub fn reward_success(bucket: Bucket) -> Nil

Top up the bucket by success_reward tokens, capped at capacity. Called once per successful operation.

shutdown

</>

pub fn shutdown(bucket: Bucket) -> Nil

Tell the bucket actor to exit. Fire-and-forget. Mirrors credentials_cache.shutdown; both call into aws/internal/actor_lifecycle.shutdown_via_stop. Safe to call multiple times.

shutdown_sync

</>

pub fn shutdown_sync(
  bucket: Bucket,
  timeout_ms: Int,
) -> Result(Nil, Nil)

Synchronous teardown — monitors the actor, sends Stop, waits for DOWN. Ok(Nil) on clean exit, Error(Nil) on real timeout. Idempotent for already-dead actors.

start

</>

pub fn start(
  capacity capacity: Int,
  success_reward success_reward: Int,
) -> Result(Bucket, StartError)

Start a bucket with explicit capacity + reward.

start_default

</>

pub fn start_default() -> Result(Bucket, StartError)

Start a bucket with Rust SDK defaults (500 / 0).

try_acquire

</>

pub fn try_acquire(
  bucket: Bucket,
  cost cost: Int,
) -> AcquireResult

Try to acquire cost tokens. Returns Acquired(permit) if the bucket can pay; Empty if not (caller must NOT retry).