README
¶
Rate Limiter
Generic approach to tracking if an action goes over a certain treshold, measured in # / seconds. The library is generic, but the obvious example would be to limit the number of requests a user can make.
The library functions in two mode.
Embedded Mode
In this mode, the tracking code integrates with your existing code. This mode is ideal if you already maintain long-lived objects. For example, if you were building a TCP chat server, you'd use the embedded mode and associate a *Tracker with your existing *User.
// your code embeds a *ratelimit.Tracker
// create an instance via ratelimit.NewTracker()
type User struct {
tracker *ratelimit.Tracker
}
// whenever an action is taken that you want to limit:
if user.tracker.Track(5) < 0 {
// we've seen more than 5 requests per second
}
If you want to track different events independently, create multiple trackers. A tracker is composed of an int32 and an int64 and uses the sync/atomic package for concurrency control
Standalone Mode
In standalone mode, a rate limiter is backed by an LRU cache and tracks usage based on an arbitrary string key (such as an IP address).
Configure a new rate limiter instance:
limiter := ratelimit.New(ratelimit.Configure().
MaxAllowance(5).
MaxItems(5000)
and use it to track requests:
if limiter.Track("SOME_KEY") < 0 {
}
When configuring the limiter:
MaxAllowance(int)- maximum number of requests per second allowed (default: 5)MaxItems(int)- maximum number of values to track (default: 5000)
It takes roughly 1.2MB to track 10 000 items. The limiter is thread-safe.
Return Value
The return value is the number of allowed actions remaining. A value less than 0 means we're over the allocation. This can be used to take different actions based on how much over we are:
if allowed := tracker.Track(5); allowed < -5 {
//way over, disconnect!
} else if allowed < 0 {
//a little over, warn
}
Documentation
¶
Index ¶
Constants ¶
const ( BUCKETS = 16 BUCKET_MASK = BUCKETS - 1 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CachedTracker ¶
type CachedTracker struct {
// contains filtered or unexported fields
}
type Configuration ¶
type Configuration struct {
// contains filtered or unexported fields
}
func Configure ¶
func Configure() *Configuration
func (*Configuration) Allowance ¶
func (c *Configuration) Allowance(allowance int) *Configuration
The number of events allowed per second [5]
func (*Configuration) MaxItems ¶
func (c *Configuration) MaxItems(max int) *Configuration
The max number of items to track [5000]
type List ¶
type List struct {
// contains filtered or unexported fields
}
func (*List) PushToFront ¶
func (l *List) PushToFront(item *CachedTracker)
func (*List) Remove ¶
func (l *List) Remove(item *CachedTracker)
Source Files