sinatra-rate-limiter 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 284920f0a11fd397c41ae1bd5e31f6e1f45bb846
-  data.tar.gz: 58c8cc97bbab02f53ba781fbc4e1ef0ba0901eb5
+  metadata.gz: 006ef1d8689384395b156b7c636c4745287d07f0
+  data.tar.gz: 127f8f5d68dcd6898e8d21e6ac0fdfbaf16858b3
 SHA512:
-  metadata.gz: 589661c3cd2635d4fad8c7ad421ef3ca02cc22c6dff9e7bcbb6dc495820d99c2b1063a530057907499a2725404c198cbf394d38a34362fd9dcc1e4afbe670554
-  data.tar.gz: d279915ae972605f568070b3e0d63b2a35963b5a805dc82c3ed75fbe80436d5c9b5cc632fd2fffbb81f316962b94751411a40cf28efe7152af0a6d55c950ed82
+  metadata.gz: 4360d48ffd69e8274b6e2e504547ce58847fa98ba153aedaf7c9e959c4690ac87a01131b006aa023d9b5f0485c2e609cb200d4e6031b5ba7b52c208bef9907ab
+  data.tar.gz: 20133bd94e537603a00de43971cd840a46d3212d8a046b115a0177801df7ff28299391c126cebafb550849088996fb0ded7ad25af552535c2c758e0ceaae902b

data/README.md

@@ -7,9 +7,8 @@ request that the rate limiter sees logs a new item in the redis store. If
 more than the allowable number of requests have been made in the given time
 then no new item is logged and the request is aborted. The items stored in
 redis include a bucket name and timestamp in their key name. This allows
-multiple limit "buckets" to be used and for variable rate limits to be
-applied to different requests using the same bucket. See the _Usage_ section
-below for examples demonstrating this.
+multiple "buckets" to be used and for variable rate limits to be applied to
+different requests using the same bucket.
 
 ## Installing
 
@@ -23,8 +22,26 @@ below for examples demonstrating this.
  * Require and enable it in your app after including Sinatra
 
    ```ruby
+   require 'sinatra'
    require 'sinatra/rate-limiter'
+
    enable :rate_limiter
+
+   ...
+   ```
+
+ * Modular applications must explicitly register the extension, e.g.
+
+   ```ruby
+   require 'sinatra/base'
+   require 'sinatra/rate-limiter'
+
+   class ModularApp < Sinatra::Base
+     register Sinatra::RateLimiter
+     enable :rate_limiter
+
+     ...
+   end
    ```
 
 ## Usage
@@ -34,13 +51,97 @@ in a `before` filter, or in a Padrino controller, etc. `rate_limit` takes
 zero to infinite parameters, with the syntax:
 
   ```
-  rate_limit [String], [[<Fixnum>, <Fixnum>], [<Fixnum>, <Fixnum>], ...]
+  rate_limit [BucketName], [[<Requests>, <Seconds>], ...], [[<Key>: <Value>], ...]
   ```
 
-The `String` optionally defines a name for this rate limiter, allowing you
-to have multiple rate limits within your app. The following pairs of
+The `String` optionally defines a named bucket. The following pairs of
 `Fixnum`s define `[requests, seconds]`, allowing you to specify how many
-requests per seconds this rate limiter allows.
+requests per seconds are allowed for this route/path. Finally overrides for
+the globally defined default options can be provided.
+
+See the _Examples_ section below for usage examples.
+
+## Configuration
+
+All configuration is optional. If no default limits are specified here,
+you must specify limits with each call of `rate_limit`
+
+### Defaults
+
+   ```ruby
+   set :rate_limiter_environments,     [:production]
+   set :rate_limiter_default_limits,   [10, 20]
+   set :rate_limiter_redis_conn,       Redis.new
+   set :rate_limiter_redis_namespace,  'rate_limit'
+   set :rate_limiter_redis_expires,    24*60*60
+
+   set :rate_limiter_default_options, {
+     error_code:     429,
+     error_template: nil,
+     send_headers:   true,
+     identifier:     Proc.new{ |request| request.ip }
+   }
+   ```
+
+#### `rate_limiter_environments` (Array)
+
+An Array of Rack environments to enable the rate limiter for.
+
+#### `rate_limiter_default_limits` (Array)
+
+Default limit parameters.
+
+#### `rate_limiter_redis_conn` (Redis)
+
+Redis connection definition (e.g. global variable pointing at your already
+defined Redis connection, or a ConnectionPool, etc).
+
+#### `rate_limiter_redis_namespace` (String)
+
+The Redis namespace to use. All keys stored in the Redis store will be
+prefixed with this string plus a forward-slash (`/`).
+
+#### `rate_limiter_redis_expires` (Integer)
+
+How long keys live in the Redis store for. This must be longer than any
+limiter's longest 'seconds' parameter.
+
+#### `rate_limiter_default_options` (Hash)
+
+Default options provided to each call of `rate_limit`
+
+##### `error_code` (Integer)
+
+The HTTP error code to send to the client when a rate limit is reached.
+Defaults to `429` per [RFC 6585](http://tools.ietf.org/html/rfc6585) but
+you may have your own reasons for wanting to use a different code (like 400
+or 503).
+
+##### `error_template` (String)
+
+Defines a template to render when a rate limit is reached (e.g. a nice error
+page or a machine friendly JSON response). Three local variables are
+provided (all Integers):
+
+ * `requests`: The number of requests that triggered the rate limit.
+ * `seconds`: The rate limit period.
+ * `try_again`: In how many seconds the client should try again.
+
+##### `send_headers` (Boolean)
+
+Whether or not to send `X-RateLimit-` headers to the client with each
+request. A `Retry-After` header is currently always sent when a rate
+limit is reached regardless of this setting.
+
+##### `identifier` (Proc)
+
+A `Proc` taking exactly one parameter (`request`) which returns a String
+identifying the client for the purposes of rate limiting. Defaults to the
+clients IP address (from `request.ip`) but you could use the value of a 
+cookie, a session ID, username, or anything else accessible from Sinatra's
+`request` object.
+
+## Examples
 
 The following route will be limited to 10 requests per minute and 100
 requests per hour:
@@ -53,25 +154,30 @@ requests per hour:
   end
   ```
 
-The following will apply an unnamed limit of 1000 requests per hour to all
-routes and stricter individual rate limits to two particular routes:
+The following will apply a limit of 1000 requests per hour using the default
+bucket to all routes and stricter individual rate limits with additional
+buckets assigned to the remaining routes. It identifiers the client by the
+value of the cookie `userid` instead of by IP address.
 
   ```ruby
-  set :rate_limiter_default_limits, [1000, 60*60]
+  set :rate_limiter_default_limits,  [1000, 60*60]
+  set :rate_limiter_default_options, send_headers: true,
+                                     identifier: Proc.new{|request| request.cookies['userid']}
+
   before do
     rate_limit
   end
 
   get '/' do
-    "this route has the global limit applied"
+    "this route has only the global limit applied"
   end
 
   get '/rate-limit-1/example-1' do
     rate_limit 'ratelimit1', 2,  5,
-                             10, 60 
+                             10, 60
 
     "this route is rate limited to 2 requests per 5 seconds and 10 per 60
-     seconds"
+     seconds in addition to the global limit of 1000 per hour"
   end
 
   get '/rate-limit-1/example-2' do
@@ -81,34 +187,25 @@ routes and stricter individual rate limits to two particular routes:
      bucket as '/rate-limit-1'. "
 
   get '/rate-limit-2' do
-    rate_limit 'ratelimit2', 1, 10
+    rate_limit 'ratelimit2', 1, 10, send_headers: false
 
-    "this route is rate limited to 1 request per 10 seconds"
+    "this route is rate limited to 1 request per 10 seconds, and won't send
+     any headers"
   end
   ```
 
 N.B. in the last example, be aware that the more specific rate limits do not
 override any rate limit already defined during route processing, and the
-global rate limit will apply additionally. If you call `rate_limit` more
-than once with the same (or no) name, it will be double counted.
+first rate limit specified in `before` will apply additionally. If you call
+`rate_limit` more than once with the same (or no) bucket name, the request
+will be double counted in that bucket.
 
-## Configuration
+## License
 
-All configuration is optional. If no default limits are specified here,
-you must specify limits with each call of `rate_limit`
+MIT license. See [LICENSE](https://github.com/warrenguy/sinatra-rate-limiter/blob/master/LICENSE).
 
-### Defaults
+## Author
 
-   ```ruby
-   set :rate_limiter_default_limits,   []
-   set :rate_limiter_environments,     [:production]
-   set :rate_limiter_error_code,       429
-   set :rate_limiter_error_template,   nil
-   set :rate_limiter_send_headers,     true
-   set :rate_limiter_custom_user_id,   nil
-   set :rate_limiter_redis_conn,       Redis.new
-   set :rate_limiter_redis_namespace,  'rate_limit'
-   set :rate_limiter_redis_expires,    24*60*60
-   ```
+Warren Guy <warren@guy.net.au>
 
-TODO: document each setting here explicitly
+https://warrenguy.me

data/lib/sinatra/rate-limiter.rb

@@ -10,50 +10,55 @@ module Sinatra
       def rate_limit(*args)
         return unless settings.rate_limiter and settings.rate_limiter_environments.include?(settings.environment)
 
-        limit_name, limits = parse_args(args)
+        bucket, options, limits = parse_args(args)
 
-        limiter = RateLimit.new(limit_name, limits)
-        limiter.settings = settings
-        limiter.request  = request
+        limiter = RateLimit.new(bucket, limits)
+        limiter.settings  = settings
+        limiter.request   = request
+        limiter.options   = options
 
         if error_locals = limits_exceeded?(limits, limiter)
-          rate_limit_headers(limits, limit_name, limiter)
-          response.headers['Retry-After'] = error_locals[:try_again] if settings.rate_limiter_send_headers
-          halt settings.rate_limiter_error_code, error_response(error_locals)
+          rate_limit_headers(limits, bucket, limiter) if limiter.options.send_headers
+          response.headers['Retry-After'] = error_locals[:try_again]
+          halt limiter.options.error_code, error_response(error_locals, limiter)
         end
 
-        redis.setex([namespace,user_identifier,limit_name,Time.now.to_f.to_s].join('/'),
-                    settings.rate_limiter_redis_expires,
-                    request.env['REQUEST_URI'])
+        redis(limiter).setex([namespace(limiter),user_identifier(limiter),bucket,Time.now.to_f.to_s].join('/'),
+                             settings.rate_limiter_redis_expires,
+                             request.env['REQUEST_URI'])
 
-        rate_limit_headers(limits, limit_name, limiter) if settings.rate_limiter_send_headers
+        rate_limit_headers(limits, bucket, limiter) if limiter.options.send_headers
       end
 
       private
 
       def parse_args(args)
-        limit_name = args.map{|a| a.class}.first.eql?(String) ? args.shift : 'default'
-        args = settings.rate_limiter_default_limits if args.size < 1
+        bucket    = (args.first.class == String) ? args.shift : 'default'
+        options   = (args.last.class == Hash)    ? args.pop   : {}
+        limits    = (args.size < 1) ? settings.rate_limiter_default_limits : args
 
-        if (args.size < 1)
+        if (limits.size < 1)
           raise ArgumentError, 'No explicit or default limits values provided.'
-        elsif (args.map{|a| a.class}.select{|a| a != Fixnum}.count > 0)
+        elsif (limits.map{|a| a.class}.select{|a| a != Fixnum}.count > 0)
           raise ArgumentError, 'Non-Fixnum parameters supplied. All parameters must be Fixnum except the first which may be a String.'
-        elsif ((args.map{|a| a.class}.size % 2) != 0)
+        elsif ((limits.map{|a| a.class}.size % 2) != 0)
           raise ArgumentError, 'Wrong number of Fixnum parameters supplied.'
-        elsif !(limit_name =~ /^[a-zA-Z0-9\-]*$/)
+        elsif !(bucket =~ /^[a-zA-Z0-9\-]*$/)
           raise ArgumentError, 'Limit name must be a String containing only a-z, A-Z, 0-9, and -.'
+        elsif (omap = (options.keys.map{|o| settings.rate_limiter_default_options.keys.include?(o)})).include?(false)
+          raise ArgumentError, "Invalid option '#{options.keys[omap.index(false)]}'."
         end
 
-        return [limit_name,
-                args.each_slice(2).map{|a| {requests: a[0], seconds: a[1]}}]
+        return [bucket,
+                options,
+                limits.each_slice(2).map{|a| {requests: a[0], seconds: a[1]}}]
       end
 
-      def redis
+      def redis(limiter)
         settings.rate_limiter_redis_conn
       end
 
-      def namespace
+      def namespace(limiter)
         settings.rate_limiter_redis_namespace
       end
 
@@ -74,8 +79,8 @@ module Sinatra
         end
       end
 
-      def rate_limit_headers(limits, limit_name, limiter)
-        header_prefix = 'X-Rate-Limit' + (limit_name.eql?('default') ? '' : '-' + limit_name)
+      def rate_limit_headers(limits, bucket, limiter)
+        header_prefix = 'X-Rate-Limit' + (bucket.eql?('default') ? '' : '-' + bucket)
         limit_no = 0 if limits.length > 1
         limits.each do |limit|
           limit_no = limit_no + 1 if limit_no
@@ -85,18 +90,18 @@ module Sinatra
         end
       end
 
-      def error_response(locals)
-        if settings.rate_limiter_error_template
-          render settings.rate_limiter_error_template, locals: locals
+      def error_response(locals, limiter)
+        if limiter.options.error_template
+          render limiter.options.error_template, locals: locals
         else
           content_type 'text/plain'
           "Rate limit exceeded (#{locals[:requests]} requests in #{locals[:seconds]} seconds). Try again in #{locals[:try_again]} seconds."
         end
       end
 
-      def user_identifier
-        if settings.rate_limiter_custom_user_id.class == Proc
-          return settings.rate_limiter_custom_user_id.call(request)
+      def user_identifier(limiter)
+        if limiter.options.identifier.class == Proc
+          return limiter.options.identifier.call(request)
         else
           return request.ip
         end
@@ -115,26 +120,27 @@ module Sinatra
       app.helpers RateLimiter::Helpers
 
       app.set :rate_limiter,                  false
-      app.set :rate_limiter_default_limits,   []  # 10 requests per minute: [{requests: 10, seconds: 60}] 
       app.set :rate_limiter_environments,     [:production]
-      app.set :rate_limiter_error_code,       429 # http://tools.ietf.org/html/rfc6585
-      app.set :rate_limiter_error_template,   nil # locals: requests, seconds, try_again
-      app.set :rate_limiter_send_headers,     true
-      app.set :rate_limiter_custom_user_id,   nil # Proc.new { Proc.new{ |request| request.ip } }
-                                                  # must be wrapped with another Proc because Sinatra
-                                                  # evaluates Procs in settings when reading them.
+      app.set :rate_limiter_default_limits,   [10, 20]  # 10 requests per 20 seconds
       app.set :rate_limiter_redis_conn,       Redis.new
       app.set :rate_limiter_redis_namespace,  'rate_limit'
       app.set :rate_limiter_redis_expires,    24*60*60 # This must be larger than longest limit time period
+
+      app.set :rate_limiter_default_options, {
+        error_code:     429,
+        error_template: nil,
+        send_headers:   true,
+        identifier:     Proc.new{ |request| request.ip }
+      }
     end
 
   end
 
   class RateLimit
-    attr_reader :history
+    attr_reader :history, :options
 
-    def initialize(limit_name, limits)
-      @limit_name    = limit_name
+    def initialize(bucket, limits)
+      @bucket        = bucket
       @limits        = limits
       @time_prefix   = get_min_time_prefix(@limits)
     end
@@ -149,12 +155,19 @@ module Sinatra
       if @history
         @history
       else
-        @history = redis.
-          keys("#{[namespace,user_identifier,@limit_name].join('/')}/#{@time_prefix}*").
+        @history = redis(self).
+          keys("#{[namespace(self),user_identifier(self),@bucket].join('/')}/#{@time_prefix}*").
           map{|k| k.split('/')[3].to_f}
       end
     end
 
+    def options=(options)
+      @options = OpenStruct.new(settings.rate_limiter_default_options.merge(options))
+    end
+    def options
+      @options
+    end
+
     def settings=(settings)
       @settings = settings
     end
@@ -170,4 +183,5 @@ module Sinatra
     end
   end
 
+  register RateLimiter
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-rate-limiter
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Warren Guy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-28 00:00:00.000000000 Z
+date: 2015-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra