APIs to manage rate-based thresholds

APIs to manage a rate-based threshold.

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])
rl.rateCreate({key:key,token:tokens,interval:interval[,intervalType: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 or rolling. The default value is fixed.
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.

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');
  }
});