Smockron!

Distributed Rate Limiting via Nginx Plugin or Node Middleware

(Shut people down when they've made too many HTTP requests)

Fail-safe

In the case of server or network outages, Smockron makes sure your application stays accessible. Distributed design doesn't add a single point of failure.

Lightweight

Smockron uses minimal resources, and causes virtually no slowdown for users who aren't being throttled.

Flexible

Smockron works no matter what language your application is written in, or what technology you use for load-balancing.

Getting the code

Install from NPM:

$ npm install smockron

Or check it out from GitHub:

$ git clone https://github.com/arodland/smockron
$ git submodule update --init
$ npm install

Master

The master aggregates request counts and notifies app servers when thresholds are met.

Configure rate limiting criteria and thresholds:

$ vi config/default.yaml

Start up the master:

$ smockron_master
# or: node bin/master.js

Express middleware

App middleware sends events to the master and listens for throttle notifiactions. Use either this middleware, or the Nginx module below.

Configure your application:

var Smockron = require('smockron');
var gk = new Smockron.Gatekeeper({
  server: "smockron.example.com",
  domain: "myapp",
  identifierCB: Smockron.Gatekeeper.REMOTE_ADDR
});
app.use(gk.middleware());

Or run the example app:

$ node bin/gatekeeper_test.js

Nginx module

If you'd rather limit at the nginx level, use the nginx module instead of the Node middleware. The nginx module sends events to the master and listens for throttle notifiactions.

Download and unpack nginx:

$ cd smockron/gatekeeper/nginx-module
$ ./configure-nginx /path/to/nginx
$ ./build-nginx /path/to/nginx

Add configuration in nginx.conf:

$ smockron on;
$ smockron_master tcp://smockron.example.com:10004;
$ smockron_domain myapp;

Run the example config:

$ ./run-nginx /path/to/nginx

About Smockron

How does it work?

Application servers use ZeroMQ to send information about incoming requests to a Smockron master server. When the master detects that a client is accessing a resource too frequently, it sends a message to servers with that resource instructing them to deny that client for a period of time.

For more information about the design of Smockron, see the Smockron design documentation.

What do I need?

The Smockron master is written in Node and uses Redis as a data store. The Smockron gatekeeper exists in two versions: as a Node Express middleware, and as an Nginx plugin.

Is it ready to use?

Smockron is beta software under active development. It's not ready for production use quite yet. All of the components have a basic set of features and are reasonably stable, and you're encouraged to try it out and share your experiences.