Module eternity::multi_bucket

A multi-bucket type uses groups of buckets. Each group represents a category, e.g. a command name or HTTP endpoint, which then contains buckets. The buckets represent individual identities, such as the command user’s ID or the endpoint parameters.

Group and Bucket Keys

The group key accesses a bucket group and the bucket key accesses the actual bucket instance containing the rate limit data within a group.

Limit Behaviour

Buckets are locked when accessed. Once a rate limit occurs, other attempts on locking the bucket will await until the bucket is free again.

Generics

When defining your multi-bucket type, the first generic you set is the group key. It decides the category of dispatch, e.g. a specific bot command.
The second generic you specify picks a rate limit measuering instance. Therefore, if you want a global rate limit, you simply use None as bucket key but when you want it to be limited per user, you provide the user ID.
Last but not least, when the cache-feature is enabled, you can pass the optional third generic to decide what type of value you want to cache.

Usage

The recommended way of adding buckets to a multi-bucket is by calling build_group on them. This returns a convenient builder API.

The other option is to implement the ToBucket-trait and call insert_group for each group. This can be useful if you want to dynamically add new groups and adjust the bucket values based on its key’s properties. E.g. if the key has a field named property and it has a special value, the bucket could have a different rate limit process.

You may also construct the bucket manually and insert it via insert_bucket. However build_group will do this for you already.

Structs

CachedLimitedEnums	Disclaimer:
CachedLimitedEnumsModifier	This builder takes ownership of CachedLimitedEnums and allows to add a new bucket while providing a builder API to the user. The taken CachedLimitedEnums will be given back once build is called.
LimitedRequests	This limiter can use a group key for each bucket group and a bucket key to get the bucket instance.
LimitedRequestsModifier	This builder takes ownership of LimitedRequests and allows to add a new bucket while providing a builder API to the user. The taken LimitedRequests will be given back once build is called.

Traits

ToBucket

Creates a bucket using the key.