hook

Hook

Hook is a simple node package used for counting unique occurances (by key) in a window of time that performs and has a low memory footprint. It works with multiple instances of node if used in conjunction with redis.

This allows for throttling and statistics tracking over a period of time.

Use Cases

• tracking request count by url, ip, etc.. over a specific amount of time (minute, day, hour, etc...)
• throttling users based on the same principles.

Examples

middleware

Throttle by ip address

var hook    = require('hook');
var connect = require('connect');

var IP_LIMIT = 1000;
var IP_PER   = "day"; // hour or minute

var app = connect(
  hook.middleware.throttleIP(IP_LIMIT, IP_PER) 
); 

Count urls by day and generate a realtime report:

var app = express.createServer(
  hook.middleware.countURL("day")
);

app.get('/stats', function(req, res, next) { 
  req.writeHead(200, { "Content-type": "text/html" });
  req.end(hook.middleware.htmlTable();
});

More specific throttling

// throttle by url.  
// A url can only be visited 10 times in an hour
// hour on minute granularity
connect(
  hook.middleware.throttle({
    limit:  10,
    buckets: 60,
    seconds: 60,
    prefix:  "ip"
  }, function (req) { return req.url; })
);

RangeCounter API

Range counters are used for collecting data in a sliding window. They are not meant to be persistent. Instead, they are a snapshot of statistical data. They are a few concepts that need to be defined:

• buckets: this is the number of containers which the counters keep. They represent a period of time in which counts/keys fall into.
• time per bucket: this is the number of seconds each bucket should represent. For instance: 24 buckets at 3600 seconds each will keep track of data for a day in hourly increments.

Example

Say we want to limit the number of times a user can log in a 10 minute time period:

var redis = require('redis').createClient();

var buckets = 10;
var seconds = 60;
var prefix  = "login:users"; // for redis
var users   = new hook.RangeCounter(buckets, seconds, prefix);
var limit   = 100;

function userLoggedIn(username) {
  users.inc(username); 
}

function canUserLogin(username) {
  return users.getCount(username) < limit;
}

// sync counter data to redis (prefix key is "login:users");
// if you have multiple node instances running, they will sync up
// to each other every 5 seconds
setInterval(function () { hook.RangeCounter.sync(redis, users) }, 5000);

new hook.RangeCounter(buckets, seconds, prefix)

Instantiates a range counter. Inputs:

• buckets: the number of buckets to store counts (more for more granularity
• seconds: the number of seconds each bucket represents
• prefix: the prefix used for keys in redis

counter.inc(key)

Increments counter for a specific key (eg. ip address, url)

counter.getCount(key)

Returns integer for the count of a key

counter.getCounts()

Returns a hash where the keys are the keys and the counts are the values.