Struct DistributedTokenBucketSpec 

pub struct DistributedTokenBucketSpec { /* private fields */ }

Distributed token bucket implementation

Uses atomic operations in a distributed backend (e.g., Redis Lua scripts) to implement token bucket algorithm across multiple workers.

Redis Implementation

The token bucket is implemented using Redis with two keys:

• {key}:tokens - Current token count (float)
• {key}:refill - Last refill timestamp (integer, milliseconds since epoch)

A Lua script performs atomic token refill and acquisition:

1. Calculate elapsed time since last refill
2. Add tokens based on elapsed time and rate
3. Cap tokens at burst capacity
4. Attempt to consume 1 token
5. Update last refill timestamp

Example Lua Script

local tokens_key = KEYS[1]
local refill_key = KEYS[2]
local rate = tonumber(ARGV[1])
local burst = tonumber(ARGV[2])
local now = tonumber(ARGV[3])

local last_refill = redis.call('GET', refill_key)
local tokens = redis.call('GET', tokens_key)

if not tokens then
    tokens = burst
else
    tokens = tonumber(tokens)
end

if last_refill then
    local elapsed = (now - tonumber(last_refill)) / 1000.0
    tokens = math.min(tokens + elapsed * rate, burst)
end

if tokens >= 1.0 then
    tokens = tokens - 1.0
    redis.call('SET', tokens_key, tostring(tokens))
    redis.call('SET', refill_key, tostring(now))
    return 1
else
    redis.call('SET', tokens_key, tostring(tokens))
    redis.call('SET', refill_key, tostring(now))
    return 0
end

Implementations

impl DistributedTokenBucketSpec

pub fn new(key: String, config: RateLimitConfig) -> Self

Create a new distributed token bucket specification

This creates the specification for a distributed token bucket. Actual implementation requires a backend (e.g., Redis client).

pub fn lua_acquire_script() -> &'static str

Get the Lua script for atomic token acquisition

This script should be loaded into Redis using SCRIPT LOAD and executed with EVALSHA for better performance.

pub fn lua_available_script() -> &'static str

Get the Lua script for querying available permits

pub fn state(&self) -> &DistributedRateLimiterState

Get the state for implementing the distributed backend

pub fn try_acquire_fallback(&self) -> bool

Try to acquire using local fallback

Trait Implementations

impl Clone for DistributedTokenBucketSpec

fn clone(&self) -> DistributedTokenBucketSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DistributedTokenBucketSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.