glimit/bucket

This module contains pure token-bucket functions used by the rate limiter actor.

Types

BucketState

The state of a single token bucket.

pub type BucketState {
  BucketState(
    max_token_count: Int,
    token_rate: Int,
    token_count: Float,
    last_update: option.Option(Int),
  )
}

Constructors

```
BucketState(
  max_token_count: Int,
  token_rate: Int,
  token_count: Float,
  last_update: option.Option(Int),
)
```
Arguments

max_token_count

The maximum number of tokens.

token_rate

The rate of token generation per second.

token_count

The number of tokens available.

last_update

Monotonic timestamp (milliseconds) of the last time the bucket was updated.

Store

</>

A pluggable storage backend for distributed rate limiting.

All token bucket logic is handled by glimit — store adapters only need to implement simple get/set/lock/unlock operations on string-keyed bucket state.

get: Retrieve bucket state by key. Return Ok(None) for a new/missing key.
set: Persist bucket state with a TTL in seconds for automatic expiry.
lock: Acquire an exclusive lock for the key. Return Error(Nil) if unavailable.
unlock: Release the lock for the key.

When a lock or get fails, the rate limiter fails open (allows the request).

pub type Store {
  Store(
    get: fn(String) -> Result(option.Option(BucketState), Nil),
    set: fn(String, BucketState, Int) -> Result(Nil, Nil),
    lock: fn(String) -> Result(Nil, Nil),
    unlock: fn(String) -> Result(Nil, Nil),
  )
}

Constructors

Store(
  get: fn(String) -> Result(option.Option(BucketState), Nil),
  set: fn(String, BucketState, Int) -> Result(Nil, Nil),
  lock: fn(String) -> Result(Nil, Nil),
  unlock: fn(String) -> Result(Nil, Nil),
)

Values

from_pairs

</>

pub fn from_pairs(
  pairs: List(#(String, String)),
) -> Result(BucketState, Nil)

Parse a BucketState from a list of string key-value pairs.

This is the inverse of to_pairs. Returns Error(Nil) if any required field is missing or cannot be parsed.

hit

</>

pub fn hit(
  state: BucketState,
  now: Int,
) -> #(Result(Nil, Nil), BucketState)

Hit the bucket: refill, then try to consume one token.

Returns #(Ok(Nil), new_state) on success, #(Error(Nil), new_state) when rate-limited.

is_full

</>

pub fn is_full(state: BucketState, now: Int) -> Bool

Returns True if the bucket is full after refilling.

new

</>

pub fn new(
  max_token_count: Int,
  token_rate: Int,
) -> Result(BucketState, Nil)

Create a new bucket state.

Returns Error(Nil) if max_token_count or token_rate are not positive.

refill

</>

pub fn refill(state: BucketState, now: Int) -> BucketState

Refill the bucket based on elapsed time.

to_pairs

</>

pub fn to_pairs(state: BucketState) -> List(#(String, String))

Convert a BucketState to a list of string key-value pairs.

Useful for serializing bucket state into external stores (e.g. Redis HSET). Keys: "tc" (token count), "lu" (last update), "mt" (max tokens), "tr" (token rate).

Constructors

Arguments

Constructors