sinatra-rate-limiter 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8adddf799a15960cccfb10260b144cd2b44f648d
-  data.tar.gz: 39755bb89f40a13226ca738c64f12c4f9c6b5493
+  metadata.gz: 75be17ee12b4828c4e6640da0d910329df557225
+  data.tar.gz: fc79ea5b2aae041c72d8e1b4af609a19efa8ce09
 SHA512:
-  metadata.gz: fa29b11d746463878859cf05f2a4061a9ae09b9748a5b0cbf79e94fd60c285314a840c2bb680f2de5da1cae1180188ed863e48a5b42ac332bca7a0edb07dc33d
-  data.tar.gz: df6410fd0b9c87ac9ffff38ec7670f0db34e58d44b9501447384cc19e93f7b6dff9226c4da6659feb9ad939ef514d80936ac37407f96818e0a03071ba7eb1f30
+  metadata.gz: b80f42b1423bd489e32c6eb3d01667da5b436f2cf5d32865e7b7ff6eb637765134ab7a0f181135e9ab74eae142f4aa5baf2f326d6baf4ffb952ce649683ad9ab
+  data.tar.gz: a53669b2bea80a35db6cbd6b37d8383322f709e8b761a862a164bf06b47bde7ae3de256cb25ea7b2c9daeb5edee2d48b29097973b1f45510608cda975921c722

data/README.md

@@ -46,6 +46,8 @@ different requests using the same bucket.
 
 ## Usage
 
+### Defining rate limits
+
 Use `rate_limit` in the pipeline of any route (i.e. in the route itself, or
 in a `before` filter, or in a Padrino controller, etc. `rate_limit` takes
 zero to infinite parameters, with the syntax:
@@ -61,6 +63,30 @@ the globally defined default options can be provided.
 
 See the _Examples_ section below for usage examples.
 
+### Error handling
+
+When a rate limit is exceeded, the exception `Sinatra::RateLimiter::Exceeded`
+is thrown. By default, this sends an response code `429` with an informative
+plain text error message. You can use Sinatra's error handling to customise
+this. E.g.:
+
+  ```
+  error Sinatra::RateLimiter::Exceeded do
+    status 400
+    content_type :json
+
+    {error: { message: env['sinatra.error'].message } }.to_json
+  end
+  ```
+
+As well as the default error message being available in
+`env['sinatra.error'].message`, `the env['sinatra.error.rate_limiter']`
+object contains three values for the exceeded limit:
+
+ * `.requests` Integer of the number of requests allowed
+ * `.seconds` Integer of the number of seconds the request limit applies to
+ * `.try_again` Integer the number of seconds until the limit resets
+
 ## Configuration
 
 All configuration is optional. If no default limits are specified here,
@@ -76,8 +102,6 @@ you must specify limits with each call of `rate_limit`
    set :rate_limiter_redis_expires,    24*60*60
 
    set :rate_limiter_default_options, {
-     error_code:     429,
-     error_template: nil,
      send_headers:   true,
      header_prefix:  'Rate-Limit',
      identifier:     Proc.new{ |request| request.ip }
@@ -111,28 +135,10 @@ limiter's longest 'seconds' parameter.
 
 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 `Rate-Limit-*` 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.
+request.
 
 Three headers are sent per defined limit:
 
@@ -145,6 +151,9 @@ If a bucket name is defined, it will be included in the header in the format
 also be added to differentiate them, e.g `Rate-Limit-1-*`, `Rate-Limit-2-*`,
 `Rate-Limit-Bucketname-1-*`, etc.
 
+Additionally, a `Retry-After` header is sent containing the number of
+seconds remaining until the limit resets.
+
 ##### `header_prefix` (String)
 
 Prefix for HTTP headers sent to client. Default is `Rate-Limit` (per 

data/lib/sinatra/rate-limiter.rb

@@ -5,6 +5,9 @@ module Sinatra
 
   module RateLimiter
 
+    class Exceeded < StandardError
+    end
+
     module Helpers
 
       def rate_limit(*args)
@@ -18,25 +21,27 @@ module Sinatra
         limiter.options   = options
 
         if error_locals = limiter.limits_exceeded?
-          limiter.rate_limit_headers.each{|h,v| response.headers[h] = v} if limiter.options.send_headers
-
-          response.headers['Retry-After'] = error_locals[:try_again]
-          halt limiter.options.error_code, error_response(limiter, error_locals)
+          if limiter.options.send_headers
+            limiter.headers.each{|h,v| response.headers[h] = v}
+            response.headers['Retry-After'] = error_locals[:try_again]
+          end
+
+          request.env['sinatra.error.rate_limiter'] = Struct.new(*error_locals.keys).new(*error_locals.values)
+          raise Sinatra::RateLimiter::Exceeded, "Rate limit exceeded:" +
+            " #{error_locals[:requests]} requests in #{error_locals[:seconds]} seconds." +
+            " Try again in #{error_locals[:try_again]} seconds."
         end
 
-        redis.setex([namespace,limiter.user_identifier,bucket,Time.now.to_f.to_s].join('/'),
-                             settings.rate_limiter_redis_expires,
-                             request.env['REQUEST_URI'])
-
-        limiter.rate_limit_headers.each{|h,v| response.headers[h] = v} if limiter.options.send_headers
+        limiter.log_request
+        limiter.headers.each{|h,v| response.headers[h] = v} if limiter.options.send_headers
       end
 
       private
 
       def parse_args(args)
-        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
+        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 (limits.size < 1)
           raise ArgumentError, 'No explicit or default limits values provided.'
@@ -46,8 +51,19 @@ module Sinatra
           raise ArgumentError, 'Wrong number of Fixnum parameters supplied.'
         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
+
+        options.to_a.each do |option, value|
+          case option
+          when :send_headers
+            raise ArgumentError, 'send_headers must be true or false' if !(value == (true or false))
+          when :header_prefix
+            raise ArgumentError, 'header_prefix must be a String' if value.class != String
+          when :identifier
+            raise ArgumentError, 'identifier must be a Proc or nil' if (!value.nil? and value.class != Proc)
+          else
+            raise ArgumentError, "Invalid option #{option}"
+          end
         end
 
         return [bucket,
@@ -55,31 +71,6 @@ module Sinatra
                 limits.each_slice(2).map{|a| {requests: a[0], seconds: a[1]}}]
       end
 
-      def redis
-        settings.rate_limiter_redis_conn
-      end
-
-      def namespace
-        settings.rate_limiter_redis_namespace
-      end
-
-      def get_min_time_prefix(limits)
-        now    = Time.now.to_f
-        oldest = Time.now.to_f - limits.sort_by{|l| -l[:seconds]}.first[:seconds]
-
-        return now.to_s[0..((now/oldest).to_s.split(/^1\.|[1-9]+/)[1].length)].to_i.to_s
-      end
-
-      def error_response(limiter, locals)
-        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
-
-
     end
 
     def self.registered(app)
@@ -89,8 +80,6 @@ module Sinatra
       app.set :rate_limiter_environments,     [:production]
       app.set :rate_limiter_default_limits,   [10, 20]  # 10 requests per 20 seconds
       app.set :rate_limiter_default_options, {
-        error_code:     429,
-        error_template: nil,
         send_headers:   true,
         header_prefix:  'Rate-Limit',
         identifier:     Proc.new{ |request| request.ip }
@@ -99,45 +88,38 @@ module Sinatra
       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.error Sinatra::RateLimiter::Exceeded do
+        status 429
+        content_type 'text/plain'
+        env['sinatra.error'].message
+      end
     end
 
   end
 
   class RateLimit
+    attr_accessor :settings, :request, :options
+
     def initialize(bucket, limits)
       @bucket        = bucket
       @limits        = limits
       @time_prefix   = get_min_time_prefix(@limits)
     end
 
-    include Sinatra::RateLimiter::Helpers
+    def options=(options)
+      options = settings.rate_limiter_default_options.merge(options)
+      @options = Struct.new(*options.keys).new(*options.values)
+    end
 
     def history(seconds=0)
       redis_history.select{|t| seconds.eql?(0) ? true : t > (Time.now.to_f - seconds)}
     end
 
-    def redis_history
-      if @history
-        @history
-      else
-        @history = redis.
-          keys("#{[namespace,user_identifier,@bucket].join('/')}/#{@time_prefix}*").
-          map{|k| k.split('/')[3].to_f}
-      end
-    end
-
-    def user_identifier
-      if options.identifier.class == Proc
-        return options.identifier.call(request)
-      else
-        return request.ip
-      end
-    end
-
-    def rate_limit_headers
+    def headers
       headers = []
 
-      header_prefix = options.header_prefix + (@bucket.eql?('default') ? '' : '-' + @bucket)
+      header_prefix = @options.header_prefix + (@bucket.eql?('default') ? '' : '-' + @bucket)
       limit_no = 0 if @limits.length > 1
       @limits.each do |limit|
         limit_no = limit_no + 1 if limit_no
@@ -149,7 +131,7 @@ module Sinatra
       return headers
     end
 
-    def limit_remaining(limit)
+   def limit_remaining(limit)
       limit[:requests] - history(limit[:seconds]).length
     end
 
@@ -166,34 +148,46 @@ module Sinatra
       end
     end
 
-    def redis
-      settings.rate_limiter_redis_conn
+    def log_request
+      redis.setex(
+        [namespace, user_identifier, @bucket, Time.now.to_f.to_s].join('/'),
+        @settings.rate_limiter_redis_expires,
+        nil)
     end
 
-    def namespace
-      settings.rate_limiter_redis_namespace
-    end
+    private
 
-    def options=(options)
-      options = settings.rate_limiter_default_options.merge(options)
-      @options = Struct.new(*options.keys).new(*options.values)
-    end
-    def options
-      @options
+    def redis_history
+      if @history
+        @history
+      else
+        @history = redis.
+          keys("#{[namespace,user_identifier,@bucket].join('/')}/#{@time_prefix}*").
+        map{|k| k.split('/')[3].to_f}
+      end
     end
 
-    def settings=(settings)
-      @settings = settings
+    def user_identifier
+      if @options.identifier.class == Proc
+        return @options.identifier.call(request)
+      else
+        return request.ip
+      end
     end
-    def settings
-      @settings
+
+    def redis
+      @settings.rate_limiter_redis_conn
     end
 
-    def request=(request)
-      @request = request
+    def namespace
+      @settings.rate_limiter_redis_namespace
     end
-    def request
-      @request
+
+    def get_min_time_prefix(limits)
+      now    = Time.now.to_f
+      oldest = Time.now.to_f - limits.sort_by{|l| -l[:seconds]}.first[:seconds]
+
+      return now.to_s[0..((now/oldest).to_s.split(/^1\.|[1-9]+/)[1].length)].to_i.to_s
     end
   end
 

metadata

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