Next: , Previous: , Up: Library   [Contents][Index]

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 optional26, 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.


Footnotes

(26)

It is made optional in order to provide backward compatibility with the releases of mailfromd prior to 5.0.93.


Next: , Previous: , Up: Library   [Contents][Index]