Documentation
¶
Overview ¶
Package rateLimiting implements the leaky bucket algorithm: https://en.wikipedia.org/wiki/Leaky_bucket
Index ¶
- Constants
- type Bucket
- func CreateBucket(capacity, leaked uint32, leakDuration time.Duration, addToDb UpdateDB) *Bucket
- func CreateBucketFromDB(capacity, leaked uint32, leakDuration time.Duration, inBucket uint32, ...) *Bucket
- func CreateBucketFromLeakRatio(capacity uint32, leakRate float64, updateDB UpdateDB) *Bucket
- func CreateBucketFromParams(params *BucketParams, updateDB UpdateDB) *Bucket
- func (b *Bucket) Add(tokens uint32) (bool, bool)
- func (b *Bucket) AddWithExternalParams(tokens, capacity, leakedTokens uint32, duration time.Duration) (bool, bool)
- func (b *Bucket) AddWithoutOverflow(tokens uint32) (bool, bool)
- func (b *Bucket) Capacity() uint32
- func (b *Bucket) IsEmpty() bool
- func (b *Bucket) IsFull() bool
- func (b *Bucket) IsFullOrWhitelist() bool
- func (b *Bucket) IsLocked() bool
- func (b *Bucket) IsWhitelisted() bool
- func (b *Bucket) MarshalJSON() ([]byte, error)
- func (b *Bucket) Remaining() uint32
- func (b *Bucket) SetAddToDB(updateDB UpdateDB)
- func (b *Bucket) UnmarshalJSON(data []byte) error
- type BucketMap
- type BucketParams
- type MapParams
- type Storage
- type UpdateDB
Constants ¶
const ClientRateLimitErr = "Too many messages sent from ID %v with IP address " +
"%s in a specific time frame by a user"
ClientRateLimitErr is returned once a user has hit the rate limit.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bucket ¶
Bucket structure tracks the capacity and rate at which the remaining buckets decrease.
func CreateBucket ¶
CreateBucket generates a new empty bucket.
func CreateBucketFromDB ¶
func CreateBucketFromDB(capacity, leaked uint32, leakDuration time.Duration, inBucket uint32, timestamp int64, updateDB UpdateDB) *Bucket
CreateBucketFromDB creates a bucket from parameters of a stored Bucket.
func CreateBucketFromLeakRatio ¶
CreateBucketFromLeakRatio generates a new empty bucket.
func CreateBucketFromParams ¶
func CreateBucketFromParams(params *BucketParams, updateDB UpdateDB) *Bucket
CreateBucketFromParams generates a new empty bucket from custom parameters.
func (*Bucket) Add ¶
Add adds the specified number of tokens to the bucket. Returns true if the tokens were added; otherwise, returns false if there was insufficient capacity to do so.
func (*Bucket) AddWithExternalParams ¶
func (b *Bucket) AddWithExternalParams(tokens, capacity, leakedTokens uint32, duration time.Duration) (bool, bool)
AddWithExternalParams adds the specified number of tokens to the bucket given external bucket parameters rather than the params specified in the bucket. Returns true if the tokens were added; otherwise, returns false if there was insufficient capacity to do so.
func (*Bucket) IsFull ¶
IsFull returns true if the bucket is overflowing (i.e. no remaining capacity for additional tokens) .
func (*Bucket) IsFullOrWhitelist ¶
IsFullOrWhitelist returns true if the bucket is overflowing (i.e., no remaining capacity for additional tokens) or if the bucket is whitelisted.
func (*Bucket) IsWhitelisted ¶
IsWhitelisted returns true if the bucket is on the whitelist.
func (*Bucket) MarshalJSON ¶
MarshalJSON marshals the Bucket into valid JSON. This function adheres to the json.Marshaler interface. Note: it does not include the database function.
func (*Bucket) SetAddToDB ¶
SetAddToDB should be called after unmarshalling if you need a database function.
func (*Bucket) UnmarshalJSON ¶
UnmarshalJSON unmarshalls the JSON into the Bucket. This function adheres to the json.Unmarshaler interface. Note: it does not include the database function; call Bucket.SetAddToDB to add it.
type BucketMap ¶
BucketMap structure is a collection of buckets in a map, each with the same capacity and leak rate. The structure contains an optional database backend.
func CreateBucketMap ¶
func CreateBucketMap(capacity, leaked uint32, leakDuration, pollDuration, bucketMaxAge time.Duration, db Storage, quit chan struct{}) *BucketMap
CreateBucketMap creates a new BucketMap structure and starts the stale bucket removal thread. The leak rate is calculated by dividing leaked by leakDuration. If a database is being used, then all the stored buckets are reloaded from storage on creation of the map.
NOTE: If db is nil, then the database will not be used. If the quit channel is not provided, then the stale bucket removal service will not start.
func CreateBucketMapFromParams ¶
CreateBucketMapFromParams creates a new BucketMap from the buckets MapParams structure.
NOTE: If db is nil, then the database will not be used. If the quit channel is not provided, then the stale bucket removal service will not start.
func (*BucketMap) AddBucket ¶
func (bm *BucketMap) AddBucket(key string, capacity, leaked uint32, leakDuration time.Duration) *Bucket
AddBucket adds a new bucket to the map. The leak rate is calculated by dividing leaked by leakDuration.
func (*BucketMap) AddToWhitelist ¶
AddToWhitelist adds the list of entries to the bucket map and set them as whitelisted.
func (*BucketMap) DeleteBucket ¶
DeleteBucket removes the bucket with the specified key from the map. If the bucket does not exist, then an error is returned.
func (*BucketMap) LookupBucket ¶
LookupBucket returns the bucket in the map with the specified key. If no bucket exists, then a new one is added to the map and returned.
type BucketParams ¶
type BucketParams struct {
Key string // Unique bucket key
Capacity uint32 // Maximum number of tokens the bucket can hold
Remaining uint32 // Current number of tokens in the bucket
LeakRate float64 // Rate that the bucket leaks tokens at [tokens/ns]
LastUpdate int64 // Time that the bucket was most recently updated
Locked bool // Prevents auto deletion when stale
Whitelist bool // No limit for adding tokens to bucket
}
BucketParams structure holds all the values to save and restore a Bucket.
type MapParams ¶
type MapParams struct {
// Capacity for newly created buckets
Capacity uint32
// The leak rate is calculated by LeakedTokens / LeakDuration
LeakedTokens uint32
LeakDuration time.Duration
// How often to look for and discard stale buckets
PollDuration time.Duration
// Age of stale buckets when discarded
BucketMaxAge time.Duration
}
MapParams holds the values used for new BucketMaps.
type Storage ¶
type Storage interface {
// UpsertBucket inserts the BucketParams into Storage with the unique
// BucketParams key. If a bucket already exists with the same key, its
// values are updated.
UpsertBucket(bp *BucketParams)
// AddToBucket updates the remaining and lastUpdate of the bucket with the
// given key in Storage. If the bucket does not exist, an error is returned.
AddToBucket(key string, remaining uint32, lastUpdate int64) error
// RetrieveBucket returns a BucketParams for the bucket with the given key
// from Storage. If the bucket does not exist, an error is returned.
RetrieveBucket(key string) (*BucketParams, error)
// RetrieveAllBuckets returns an array of all the buckets found in Storage.
RetrieveAllBuckets() []*BucketParams
// DeleteBucket deletes the bucket with the given key from Storage. If no
// bucket is found, an error is returned.
DeleteBucket(key string) error
}
Storage is the generic interface used by the BucketMap for permanent storage.
Source Files