Skip to content
Browse files

Exported both RateLimiter and TokenBucket classes and wrote a README

  • Loading branch information...
1 parent f76fd4f commit 5ee53e644bf30b282eb527cd4d0a5d12f9986f79 @jhurliman committed
Showing with 97 additions and 1 deletion.
  1. +95 −0 README.md
  2. +2 −1 index.js
View
95 README.md
@@ -0,0 +1,95 @@
+
+# rate-limiter #
+
+Provides a generic rate limiter for node.js. Useful for API clients, web
+crawling, or other tasks that need to be throttled. Two classes are exposed,
+RateLimiter and TokenBucket. TokenBucket provides a lower level interface to
+rate limiting with a configurable burst rate and drip rate. RateLimiter sits
+on top of the token bucket and adds a restriction on the maximum number of
+tokens that can be removed each interval to comply with common API
+restrictions like "150 requests per hour maximum".
+
+## Installation ##
+
+Use NPM to install:
+
+ npm install rate-limiter
+
+## Usage ##
+
+A simple example allowing 150 requests per hour:
+
+ var RateLimiter = require('rate-limiter).RateLimiter;
+ // Allow 150 requests per hour (the Twitter search limit). Also understands
+ // 'second', 'minute', 'day', or a number of milliseconds
+ var limiter = new RateLimiter(150, 'hour');
+
+ // Throttle requests
+ limiter.removeTokens(1, function(err, remainingRequests) {
+ // err will only be set if we request more than the maximum number of
+ // requests we set in the constructor
+
+ // remainingRequests tells us how many additional requests could be sent
+ // right this moment
+
+ callMyRequestSendingFunction(...);
+ });
+
+Another example allowing one message to be sent every 250ms:
+
+ var RateLimiter = require('rate-limiter).RateLimiter;
+ var limiter = new RateLimiter(1, 250);
+
+ limiter.removeTokens(1, function() {
+ callMyMessageSendingFunction(...);
+ });
+
+Uses the token bucket directly to throttle at the byte level:
+
+ var BURST_RATE = 1024 * 1024 * 150; // 150KB/sec burst rate
+ var FILL_RATE = 1024 * 1024 * 50; // 50KB/sec sustained rate
+ var TokenBucket = require('rate-limiter').TokenBucket;
+ // We could also pass a parent token bucket in as the last parameter to
+ // create a hierarchical token bucket
+ var bucket = new TokenBucket(BURST_RATE, FILL_RATE, 'second', null);
+
+ bucket.removeTokens(myData.byteLength, function() {
+ sendMyData(myData);
+ });
+
+## Additional Notes ##
+
+Both the token bucket and rate limiter should be used with a message queue or
+some way of preventing multiple simultaneous calls to removeTokens().
+Otherwise, earlier messages may get held up for long periods of time if more
+recent messages are continually draining the token bucket. This can lead to
+out of order messages or the appearance of "lost" messages under heavy load.
+
+## Sponsors ##
+
+* [cull.tv](http://cull.tv/) - New music television
+
+## License ##
+
+(The MIT License)
+
+Copyright (c) 2011 Cull TV, Inc. <jhurliman@cull.tv>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
View
3 index.js
@@ -1,2 +1,3 @@
-module.exports = require('./lib/rateLimiter');
+exports.RateLimiter = require('./lib/rateLimiter');
+exports.TokenBucket = require('./lib/tokenBucket');

0 comments on commit 5ee53e6

Please sign in to comment.
Something went wrong with that request. Please try again.