TokenBucket → Configuration

Configuration

Pass an options table to TokenBucket.new to control capacity and refill behaviour. The same options apply whether you are configuring the App's built-in bucket, a Port's bucket, or a standalone instance.

Construction signature

TokenBucket.new(options: \{max: number?, refillRate: number?, refillInterval: number?, start: number?, cost: number?}) → TokenBucket

Options

OptionDefaultDescription
max60Maximum tokens per player. Acts as the burst ceiling — a player can never hold more than this many tokens.
refillRate20Number of tokens added to each player's bucket on each refill tick.
refillInterval1How often (in seconds) the refill fires. Together with refillRate this determines the sustained request rate: refillRate / refillInterval tokens per second.
startmaxHow many tokens a player starts with when they first appear. Defaults to a full bucket.
cost1Tokens deducted per Consume call. Increase this for expensive actions.

How the math works

The token bucket algorithm (RFC 2697 single-rate) separates burst capacity from sustained rate. max controls how many requests a player can fire in rapid succession. refillRate / refillInterval controls how quickly they recover.

Example: 30 requests per second

-- Burst of 60, recovers 30 tokens/s (30 per 1s tick)
local TokenBucket = RoExpress("TokenBucket")
local bucket = TokenBucket.new({
    max            = 60,
    refillRate     = 30,
    refillInterval = 1,
})

Example: 5 requests per second

-- Strict economy port: burst of 10, recovers 5 tokens/s
app:Listen("economy", function(port)
    port:Post("trade", handler)
end, {
    max            = 10,
    refillRate     = 5,
    refillInterval = 1,
    cost           = 1,
})

See also

← TokenBucket  ·  Consume & Check | deduct tokens per request  ·  Grant & Reset | add tokens back  ·  Port | per-port rate limiting settings