5.32 Rate limiting functions

Built-in Function: number rate (string key, number sample-interval, [number min-samples, number threshold])

Returns the mail sending rate for key per sample-interval. Optional min-samples, if supplied, specifies the minimal number of mails needed to obtain the statistics. The default is 2. Optional threshold controls rate database updates. If the observed rate (per sample-interval seconds) is higher than the threshold, the hit counters for that key are not incremented and the database is not updated. Although the threshold argument is optional²⁶, its use is strongly encouraged. Normally, the value of threshold equals the value compared with the return from rate, as in:

  if rate("$f-$client_addr", rate_interval, 4, maxrate) > maxrate
    tempfail 450 4.7.0 "Mail sending rate exceeded.  Try again later"
  fi

This function is a low-level interface. Instead of using it directly, we advise to use the rateok function, described below.

Library Function: boolean rateok (string key, number sample-interval, number threshold,

[number min-samples])

To use this function, require the rateok module (see Modules), e.g.: require rateok.

The rateok function returns ‘True’ if the mail sending rate for key, computed for the interval of sample-interval seconds is less than the threshold. Optional min-samples parameter supplies the minimal number of mails needed to obtain the statistics. It defaults to 4.

See Sending Rate, for a detailed description of the rateok and its use. The interval function (see interval) is often used in the second argument to rateok or rate.

Built-in Function: boolean tbf_rate (string key, number cost, number sample-interval, number burst-size)

This function implements a classical token bucket filter algorithm. Tokens are added to the bucket identified by the key at constant rate of 1 token per sample-interval microseconds, to a maximum of burst-size tokens. If no bucket is found for the specified key, a new bucket is created and initialized to contain burst-size tokens. If the bucket contains cost or more tokens, cost tokens are removed from it and tbf_rate returns ‘True’. Otherwise, the function returns ‘False’.

For a detailed description of the Token Bucket Algorithm and its use to limit mail rates, see TBF.