taky-redis-throttle

install

using npm

npm i taky-redis-throttle --save

example

Throttle = require 'taky-redis-throttle'

# one instance accesses multiple throttling rules
t = new Throttle {
  prefix: 'throttle'
  cache: yes
  cache_time: '30 minutes'
}

# create a new rule using the key "login_attempts" and throttle it at 500 occurrences/min
# practically this would be something user-specific, ie: "login_attempts_67.129.43.39"
rule =
  key: 'login_attempts'
  time: 'minute'
  max: 500

t.create rule, (e,r) ->

  # increment the counter every 15ms
  every '15ms', ->
    t.incr 'login_attempts', 1, -> 1

  # dump stats every 3 seconds to console
  every '3 secs', ->
    t.stats 'login_attempts', (e,stats) ->
      console.log stats

###
{ counters: { minute: 166, hour: 166, day: 166, week: 166, month: 166 },
  is_maxed: false,
  percent: '33.20',
  _meta: 
   { elapsed: 5,
     rule: 
      { _id: '3twttjbc7q1',
        key: 'login_attempts',
        max: 500,
        time: 'minute',
        ctime: 1443154353 } } }
{ counters: { minute: 335, hour: 335, day: 335, week: 335, month: 335 },
  is_maxed: false,
  percent: '67.00',
  _meta: 
   { elapsed: 2,
     rule: 
      { _id: '3twttjbc7q1',
        key: 'login_attempts',
        max: 500,
        time: 'minute',
        ctime: 1443154353 } } }
{ counters: { minute: 505, hour: 505, day: 505, week: 505, month: 505 },
  is_maxed: true,
  percent: '100.00',
  _meta: 
   { elapsed: 2,
     rule: 
      { _id: '3twttjbc7q1',
        key: 'login_attempts',
        max: 500,
        time: 'minute',
        ctime: 1443154353 } } }
{ counters: { minute: 675, hour: 675, day: 675, week: 675, month: 675 },
  is_maxed: true,
  percent: '100.00',
  _meta: 
   { elapsed: 2,
     rule: 
      { _id: '3twttjbc7q1',
        key: 'login_attempts',
        max: 500,
        time: 'minute',
        ctime: 1443154353 } } }
###

constructor(options={})

create a new taky-redis-throttle instance

options =
  redis: my_redis # an instance of ioredis, default creates one on 0.0:6379
  prefix: 'limitations' # defaults to "throttle"
  cache: yes
  cache_time: '30 minutes'

.create(rule_opts={})

create a new throttling rule

rule_opts =
  key: 'login_attempts'
  time: 'minute' # ['minute','hour','day','week','month']
  max: 500

.incr(key,amount=1,cb)

increment the counter for a rule

.update(key,update_obj={},cb)

update the properties of an existing rule (change max amount or change time segment)

update_obj =
  time: 'minute' # ['minute','hour','day','week','month']
  max: 1000

.remove(key,cb)

remove a rule from redis

.stats(key,cb)

get throttle stats for a rule

{ counters: { minute: 675, hour: 675, day: 675, week: 675, month: 675 },
  is_maxed: false,
  percent: '6.75',
  _meta: 
   { elapsed: 1,
     rule: 
      { _id: '0twtfpc304z',
        key: 'login_attempts',
        max: 10000,
        time: 'hour',
        ctime: 1443153516,
        utime: '1443153521' } } }