Neurotic Pumpkin Murderer

    limitdb

    3.0.0 • Public • Published

    Build Status

    limitdb is a database for limits on top of leveldb.

    Currently limitdb uses the Token Bucket Algorithm.

    Installation

    npm i limitdb
    

    Configure

    Create an instance of Limitdb as follows:

    const Limitdb = require('limitdb');
    const limitdb = new Limitdb({
      path: '/tmp/limitdb',
      types: {
        ip: {
          size: 10,
          per_second: 5
        }
      }
    });

    Options available:

    • path (string): a path for the leveldb database.
    • inMemory (boolean): set this to true to run the entire database in memory.
    • types (object): setup your bucket types.

    The type defines the characteristics of a the bucket:

    • size is the maximun content of the bucket. This is the maximun burst you allow.
    • per_interval is the amount of tokens that the bucket receive on every interval.
    • interval defines the inverval in milliseconds.

    You can also define your rates using per_second, per_minute, per_hour, per_day. So per_second: 1 is equivalent to per_interval: 1, interval: 1000.

    If you omit size, limitdb assumes that size is the value of per_interval. So size: 10, per_second: 10 is the same than per_second: 10.

    If you don't specify a filling rate with per_interval or any other per_x, the bucket is fixed and you have to manually reset it using PUT.

    You can also define overrides inside your type definitions as follows:

    const Limitdb = require('limitdb');
    const limitdb = new Limitdb({
      path: '/tmp/limitdb',
      types: {
        ip: {
          size: 10,
          per_second: 5,
          overrides: {
            '127.0.0.1': {
              size: 100,
              per_second: 50
            }
          }
        }
      }
    });

    In this case the specific bucket for 127.0.0.1 of type ip will have a greater limit.

    It is also possible to define overrides by regex:

    overrides: {
      'local-ips': {
        match:      /192\.168\./
        size:       100,
        per_second: 50
      }
    }
    

    and also it is possible to configure expiration of overrides:

    overrides: {
      '54.32.12.31': {
        size:       100,
        per_second: 50,
        until:      new Date(2016, 4, 1)
      }
    }
    

    TAKE

    limitdb.take({ type: 'ip', key: '54.21.23.12' }, (err, result) => {
      console.dir(result);
    });

    limitdb.take takes as argument an object with:

    • type: the bucket type.
    • key: the identifier of the bucket.
    • count: the amount of tokens you need. This is optional and the default is 1.

    The result object has:

    • conformant (boolean): true if the requested amount is conformant to the limit.
    • remaining (int): the amount of remaining tokens in the bucket.
    • reset (int / unix timestamp): unix timestamp of the date when the bucket will be full again.
    • limit (int): the size of the bucket.

    PUT

    You can manually reset a fill a bucket using PUT:

    limitdb.put({ type: 'ip', key: '54.21.23.12' }, err => {});

    limitdb.put takes as argument an object with:

    • type: the bucket type.
    • key: the identifier of the bucket.
    • count: the amount of tokens you want to put in the bucket. This is optional and the default is the size of the bucket.

    STATUS

    limitdb.status({ type: 'ip', prefix: '54' }, (err, result) => {
      console.dir(result.items);
    });

    limitdb.status takes as argument an object with

    • type: the bucket type.
    • prefix: a prefix of buckets to search.

    The result object has:

    • items: an array of buckets with:
    • key: the key of the bucket.
    • size: the size of the bucket.
    • reset: the reset time.

    Author

    Auth0

    License

    This project is licensed under the MIT license. See the LICENSE file for more info.

    Keywords

    none

    Install

    npm i limitdb

    DownloadsWeekly Downloads

    33

    Version

    3.0.0

    License

    ISC

    Unpacked Size

    48.1 kB

    Total Files

    10

    Last publish

    Collaborators

    • elbuo8
    • jfromaniello