#ratelimit API reference

A rate limiter over a selectable key/value backend (kvstore.Store - memcache, redis, or the in-process kv). Each key (an IP, a user, an API token) is counted against a limit per time window; a check records a hit and returns a Result with the decision plus the metadata for a compliant 429 (remaining budget, reset time, and Retry-After). Two algorithms, both driven by the wall clock and window-aligned keys (so they work identically on every backend, needing only atomic increment): - fixed window - a counter per aligned window; simplest, but a burst can straddle a window boundary (up to 2x the limit across the seam). - sliding window - a weighted blend of the current and previous window counts, which smooths that boundary burst.

Import with import "ratelimit.j" as ratelimit;. See the ratelimit guide for prose and examples.

#Functions

#ratelimit.check(limiter as Limiter, key as string)

Record one hit against key and return the Result (decision + remaining + reset + retry-after). The counter is created and armed with the window TTL on the first hit, so it resets on its own - nothing to reap.

Parameters

• limiter {Limiter} - the configured limiter
• key {string} - the counter key (an IP, user, or API token)

Returns {Result} - the decision and rate-limit metadata

#ratelimit.fixedWindow(store as kvstore.Store, limit as int, window as int)

A fixed-window limiter: limit hits per aligned window seconds.

Parameters

• store {kvstore.Store} - the backend store
• limit {int} - the maximum hits per window
• window {int} - the window length in seconds

Returns {Limiter} - the configured limiter

#ratelimit.peek(limiter as Limiter, key as string)

Report the current state for key without recording a hit: allowed is whether the next hit would be within the limit, plus the same remaining / reset / retry-after metadata.

Parameters

• limiter {Limiter} - the configured limiter
• key {string} - the counter key

Returns {Result} - the current rate-limit state

#ratelimit.slidingWindow(store as kvstore.Store, limit as int, window as int)

A sliding-window limiter: like fixedWindow, but blends the current and previous window counts so a burst cannot straddle a window boundary.

Parameters

• store {kvstore.Store} - the backend store
• limit {int} - the maximum hits per window
• window {int} - the window length in seconds

Returns {Limiter} - the configured limiter

#Structs

#ratelimit.Limiter

A configured limiter: a backend store, a per-window limit, a window in seconds, and the algorithm. Value-semantic; build with fixedWindow / slidingWindow.

#ratelimit.Result

The outcome of a check / peek.