APIs to manage rate-based thresholds
APIs to manage a rate-based threshold.
- The rate object
- rl.rateCreate()
The rate object provides the following APIs to decrease, reset, and modify the
token number.
All API specifications use the rate object that is assumed to be defined, for
example, by the following statements.
var rl = require('ratelimit');
var rate = rl.rateCreate('192.168.1.1', 10, 10, 'fixed');
rl.rateCreate()
Creates and initializes a rate object.
- Syntax
rl.rateCreate(key,tokens,interval[,intervalType])
- Parameters
-
- key
- The unique identifier that represents a defined threshold for the specific traffic type. The key can be any characters accessible in the GatewayScript file.
- tokens
- The maximum number of resources that can be requested during an interval, the rate-based threshold. This parameter also indicates the number of tokens that the bucket contains when the bucket is initialized. The bucket is initialized when this API is called. This parameter is an integer. The value is in the range 0 - (2**53 - 1).
- interval
- The frequency between enforcements. This parameter is an integer. The unit is second. The value is in the range 1 - 31536000.
- intervalType
- The type of interval. This parameter is a string. This parameter value is
fixed
orrolling
. The default value isfixed
.
- Guidelines
- The rl.rateCreate() API creates and initializes a rate
object that indicates the rate-based initial threshold for the specified key. When the
rate object of the specified key exists, no new rate object is
created and the rate object that was previously created by
rl.rateCreate() API is returned. But the value of tokens,
interval, and intervalType can be changed. The tokens of the
number tokens refill the bucket for each new interval. Calling the
rl.rateCreate() API multiple times does not impact the time when token refilling
occurs.When a request is received, whether the request can be accepted is based on the interval type. For example, call
rl.rateCreate('192.168.1.1', 10, 10)
to create a rate object. The bucket is initialized at 8:00:00. The interval is 10 seconds. A request is received at 8:00:18.- The fixed interval is a discrete block of time, such as from 8:00:00 to 8:00:10 and from 8:00:10
to 8:00:20. The request can be accepted when the threshold is not exceeded during the interval
8:00:10 to 8:00:20. When the interval type is
fixed
, you must check whether the threshold is exceeded from 8:00:10 to 8:00:18. If the threshold is exceeded, the request is rejected. - The rolling interval is a sliding time-window that is relative to the time when a request is
received. The request can be accepted when the threshold is not exceeded during the previous 10
seconds, from 8:00:08 to 8:00:18. When the interval type is
rolling
, you must check whether the threshold is exceeded from 8:00:08 to 8:00:18. If the threshold is exceeded, the request is rejected.
For rate object, in each interval, immutable 10 tokens are available to use.
- The fixed interval is a discrete block of time, such as from 8:00:00 to 8:00:10 and from 8:00:10
to 8:00:20. The request can be accepted when the threshold is not exceeded during the interval
8:00:10 to 8:00:20. When the interval type is
- Example
- Define a rate-based initial threshold of 10 tokens in 10 seconds. This threshold is associated
with key
192.168.1.1
.var rl = require('ratelimit'); var rate = rl.rateCreate('192.168.1.1', 10, 10, 'fixed');
rate.remaining()
Returns the number of remaining tokens.
- Syntax
rate.remaining(function(err,remaining,timetoReset))
- Parameters
-
- err
- The error information if any error occurs during the processing.
- remaining
- The number of remaining tokens in the bucket.
- timeToReset
- The number of remaining seconds in the current interval.
- Guidelines
- The rate.remaining() API obtains the number of remaining tokens for the current key.
rate.remove()
Removes a specific number of tokens from the bucket.
- Syntax
rate.remove(number,function(err,remaining,timeToReset))
- Parameters
-
- number
- The number of tokens for a request to use. This defined number of tokens are removed when the request is accepted. This parameter is an integer. The value is in the range 0 - (2**53 - 1).
- err
- The error information if any error occurs during the processing.
- remaining
- The number of remaining tokens in the bucket.
- timeToReset
- The number of remaining seconds in the current interval.
- Guidelines
- When the request is accepted, the remove() API removes the defined number of tokens for the current key. After the token removal, if the remaining value is less than the number value, the remaining tokens in the bucket are not enough for the next request. When the next request comes, the threshold is exceeded and the request is rejected. In this situation, no tokens are removed from the bucket and the number of remaining tokens does not change.
- Example
- The rate-based initial threshold is 10 tokens per 10 seconds. In the
first interval, when the first request comes at the third second, six tokens are removed and the
number of remaining tokens is 4. Because 4 is less than 6, the remaining tokens are not enough for
the next request. When the next request comes, the threshold is exceeded and the request is
rejected. The number of remaining tokens keeps the value of
4.
var rl = require('ratelimit'); var rate = rl.rateCreate('192.168.1.1', 10, 10); rate.remove(6, function(err, remaining, timeToReset){ if(err) { console.error('exceeded ratelimit'); session.reject('Ratelimit exceeded'); } else { console.info('ratelimit check ok, remaining token:' + remaining); } });
rate.reset()
Resets the number of tokens that can be requested to the initial threshold.
- Syntax
rate.reset(function(err,remaining,timeToReset))
- Parameters
-
- err
- The error information if any error occurs during the processing.
- remaining
- The number of remaining tokens in the bucket.
- timeToReset
- The number of remaining seconds in the current interval.
- Guidelines
- The rate.reset() API resets the number of tokens for the current key to the initial threshold that the rl.rateCreate() API defines. This API starts a new interval. The reset threshold takes effect in the new interval immediately after the rate.reset() API is called.
- Example
- Reset the number of tokens for key 192.168.1.1 to the initial
threshold.
var rl = require('ratelimit'); //Retrieve rate threshold associated with key '192.168.1.1' var rate = rl.rateCreate('192.168.1.1'); if(rate){ rate.reset(function(err, remaining, timeToReset) { if (err) { console.error('Error:' + err); // error handling actions } else { console.info('Reset ratelimit'); } }); }
rate.set()
Assigns a new value to the number of tokens that can be requested.
- Syntax
rate.set(number,function(err,remaining,timeToReset))
- Parameters
-
- number
- The new value to assign to the token number.
- err
- The error information if any error occurs during the processing.
- remaining
- The number of remaining tokens in the bucket.
- timeToReset
- The number of remaining seconds in the current interval.
- Guidelines
- The rate.set() API sets the new value to the number of tokens for the current key. This API starts a new interval. The new value must be less than or equal to the initial threshold that the rl.rateCreate() API defined. If the new value is greater than the initial threshold, the error occurs. The new value takes effect in the new interval immediately after the rate.set() API is called.
- Example
- Set the token number as 7.
var rl = require('ratelimit'); var rate = rl.rateCreate('192.168.1.1', 10, 10); var number = 7; rate.set(number, function(err, remaining, timeToReset){ if(err) { console.error('exceeded ratelimit'); session.reject('Ratelimit exceeded'); } else { console.info('Set ratelimit'); } });