Rate Limiter

exception q2_sdk.core.rate_limiter.RateLimitException

class q2_sdk.core.rate_limiter.RateLimit(tokens, last_refilled)

Represent a single rate limit

serialize()

Used to return a json representation of the self Ratelimit. Datetime format is ISO 8601 format.

Return type:

str

Returns:

JSON representation of the RateLimit

static deserialize(json_str)

Takes a JSON string and parses it into a RateLimit

Parameters:

json_str (str) – The JSON string containing RateLimit information

Returns:

A RateLimit object

class q2_sdk.core.rate_limiter.RateLimiter(logger, max_tokens, refill_period, refill_amount, request, whitelist_networks=None, blacklist_networks=None, whitelist_regex=None, blacklist_regex=None, name='generic', segment_by_ip=True, is_proxied=True)

Each user gets a maximum number of tokens representing allowed requests. These tokens deplete by one each request, refilling at a rate of refill_amount / refill_period (in seconds).

For instance:

Max_tokens: 10 refill_period: 5 refill_amount: 2

A user can use the extension to which this rate limiter is bound until her token count reaches 0. She hits the extension 10 times in the first second and is now denied access. 5 seconds later, she is granted 2 more tokens. Every 5 seconds 2 more tokens are added to the count, a maximum of 10 again.

The state is saved in Memcached under the two key-value pairs ratelimit_count_ and ratelimit_update_

Parameters:

• max_tokens (int) – Total number of attempts allowed before denial

• refill_period (int) – In seconds

• refill_amount (int) – Number to add each refill period

• request (HTTPServerRequest) – User Request to reference IP and other info

• whitelist_networks (Optional[List[IPv4Network]]) – List of IPv4Networks that will be automatically allowed. i.e. IPv4Network(‘13.249.59.85/32’)

• blacklist_networks (Optional[List[IPv4Network]]) – List of IPv4Networks that will be automatically denied. i.e. IPv4Network(‘13.249.59.85/32’)

• whitelist_regex – (Deprecated) IP addresses that match this pattern will be automatically allowed

• blacklist_regex – (Deprecated) IP addresses that match this pattern will be automatically denied

• name – Will be appended to the cache key for uniqueness

• segment_by_ip – If True, each IP address gets its own rate limiting bucket

• is_proxied – If True, The ip address is pulled from the header x-forwarded-for value over the remote_ip value

property ratelimit_key: str

Returns the proper key depending on if the segment_by_ip flag is set true

Returns:

The key to select the ratelimit count

is_allowed()

Checks if the request is allowed to proceed. This function reads the cached memcached data and updates it to the current value. Based on the object values and the amount of time that has passed, this will return a true or false result.

Returns:

True if the request is able to proceed, False otherwise

q2_sdk.core.rate_limiter.rate_limit(max_tokens=1000, refill_period=60, refill_amount=18, whitelist_networks=None, blacklist_networks=None)

Decorator for the ProxyRateLimiter Class. Optional arguments to customize the rate limit.

The caching naming convention uses the __name__ methodology similar to Python’s default logging convention. For .. rubric:: Example

@rate_limit(max_tokens=1000) submit():

This wraps the submit() function inside the extension.py file will result in a cache located at approximately

[PROJECTNAME].extension.submit_[IP ADDRESS]

Parameters:

• max_tokens – The maximum number of tokens that will be accumulated

• refill_period – The number of seconds between when the refill amount is added to the token count

• refill_amount – The number of Tokens that are added every refill period

• whitelist_networks – List of IPv4Networks that will be automatically allowed. i.e. IPv4Network(‘13.249.59.85/32’)

• blacklist_networks – List of IPv4Networks that will be automatically block. i.e., IPv4Network(‘13.249.59.85/32’)

Returns:

function wrapper