limiter
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Overview¶
Package limiter provides a keyed token bucket rate limiter.
Index¶
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcQPSInterval¶
QPSInterval returns the interval between events corresponding tothe given queries/second rate.
This is a helper to be used when populating Limiter.RefillInterval.
Types¶
typeLimiter¶
type Limiter[Kcomparable] struct {// Size is the number of keys to track. Only the Size most// recently seen keys have their limits enforced precisely, older// keys are assumed to not be querying frequently enough to bother// tracking.Sizeint// Max is the number of tokens available for a key to consume// before time-based rate limiting kicks in. An unused limiter// regains available tokens over time, up to Max tokens. A newly// tracked key initially receives Max tokens.Maxint64// RefillInterval is the interval at which a key regains tokens for// use, up to Max tokens.RefillIntervaltime.Duration// Overdraft is the amount of additional tokens a key can be// charged for when it exceeds its rate limit. Each additional// request issued for the key charges one unit of overdraft, up to// this limit. Overdraft tokens are refilled at the normal rate,// and must be fully repaid before any tokens become available for// requests.//// A non-zero Overdraft results in "cooldown" behavior: with a// normal token bucket that bottoms out at zero tokens, an abusive// key can still consume one token every RefillInterval. With a// non-zero overdraft, a throttled key must stop requesting tokens// entirely for a cooldown period, otherwise they remain// perpetually in debt and cannot proceed at all.Overdraftint64// contains filtered or unexported fields}
Limiter is a keyed token bucket rate limiter.
Each key gets its own separate token bucket to pull from, enablingenforcement on things like "requests per IP address". To avoidunbounded memory growth, Limiter actually only tracks limitsprecisely for the N most recently seen keys, and assumes thatuntracked keys are well-behaved. This trades off absolute precisionfor bounded memory use, while still enforcing well for outlierkeys.
As such, Limiter should only be used in situations where "rough"enforcement of outliers only is sufficient, such as throttlingegregious outlier keys (e.g. something sending 100 queries persecond, where everyone else is sending at most 5).
Each key's token bucket behaves like a regular token bucket, withthe added feature that a bucket's token count can optionally gonegative. This implements a form of "cooldown" for keys that exceedthe rate limit: once a key starts getting denied, it must stoprequesting tokens long enough for the bucket to return to apositive balance. If the key keeps hammering the limiter in excessof the rate limit, the token count will remain negative, and thekey will not be allowed to proceed at all. This is in contrast tothe classic token bucket, where a key trying to use more than therate limit will get capped at the limit, but can still occasionallyconsume a token as one becomes available.
The zero value is a valid limiter that rejects all requests. Auseful limiter must specify a Size, Max and RefillInterval.
func (*Limiter[K])Allow¶
Allow charges the key one token (up to the overdraft limit), andreports whether the key can perform an action.
func (*Limiter[K])DumpHTML¶
DumpHTML writes the state of the limiter to the given writer,formatted as an HTML table. If onlyLimited is true, the output onlylists keys that are currently being limited.
DumpHTML blocks other callers of the limiter while it collects thestate for dumping. It should not be called on large limitersinvolved in hot codepaths.
Source Files