1. Home
2. Reference documentation
3. VCL Reference
4. Declarations

Penaltybox

A penaltybox stores keys for a specified period and provides functions to determine whether a given string is currently in the stored set.

Penalty boxes are a primitive that is used primarily in constructing rate limiting solutions.

They provide two operations: ratelimit.penaltybox_add and ratelimit.penaltybox_has. Calling the add function with a time to live (TTL) adds an entry to the penalty box. Calling the has function checks to see if the entry is already present in the set.

Each penaltybox can contain up to 200,000 entries per POP and, once that limit is reached, each new entry will evict the one with the smallest remaining TTL.

All the cache nodes within the POP communicate with each other, sharing information about the penalty box entries in order to converge on a single data set. Because of synchronization delays, the first time a penalty box is used on a given cache node it will appear to be empty, because it is not yet synchronized with the rest of the cache nodes in the POP. Once synchronization is complete, the penalty box will converge to the same data set across the POP.

Each penaltybox can contain up to 200,000 unique entries per POP and, once that limit is reached, each new entry will evict the one with the smallest remaining TTL. Each entry in a penalty box can be no longer than 256 bytes and will be silently truncated if it is longer. The effective minimum TTL of an entry is 2 minutes.

Penalty boxes do not have any properties and should be declared as an empty block:

penaltybox banned_users {
  # no properties
}