dalli-rate_limiter 0.1.1 → 0.1.2

data/.travis.yml

@@ -2,9 +2,13 @@ language: ruby
 services:
   - memcached
 rvm:
-  - 1.9
-  - 2.0
-  - 2.1
-  - 2.2
+  - 1.9.3
+  - 2.0.0
+  - 2.1.8
+  - 2.2.4
   - 2.3.0
+  - jruby-1.7.23
+  - jruby-9.0.5.0
+  - rbx-2.5.8
+  - rbx-3.14
 before_install: gem install bundler -v 1.11.2

data/README.md

@@ -82,22 +82,21 @@ attributes so it should be safe to share between threads; in this case, you
 will definitely want to use either the default ConnectionPool or your own (as
 opposed to a single-threaded Dalli::Client instance).
 
-The main instance method, `#exceeded?` will return a falsy value if the request
-is free to proceed. If the limit has been exceeded, it will return a positive
-floating point value that represents the fractional number of seconds that the
-caller should wait until retrying the request. Assuming no other requests were
-process during that time, the retried request will be free to proceed at that
-point.  When invoking this method, please be sure to pass in a key that is
-unique (in combination with the `:key_prefix` option described above) to the
-thing you are trying to limit. An optional second argument specifies the number
-of requests to "consume" from the allowance; this defaults to one (1).
+The main instance method, `#exceeded?` will return false if the request is free
+to proceed. If the limit has been exceeded, it will return a positive floating
+point value that represents the fractional number of seconds that the caller
+should wait until retrying the request. Assuming no other requests were process
+during that time, the retried request will be free to proceed at that point.
+When invoking this method, please be sure to pass in a key that is unique (in
+combination with the `:key_prefix` option described above) to the thing you are
+trying to limit. An optional second argument specifies the number of requests
+to "consume" from the allowance; this defaults to one (1).
 
 Please note that if the number of requests is greater than the maximum number
 of requests, the limit will never not be exceeded. Consider a limit of 50
 requests per minute: no amount of waiting would ever allow for a batch of 51
-requests! `#exceeded?` returns a negative integer in this event. To help detect
-this edge case proactively, a public getter method `#max_requests` is
-available.
+requests! `#exceeded?` returns `-1` in this event. To help detect this edge
+case proactively, a public getter method `#max_requests` is available.
 
 ## Advanced Usage
 

data/lib/dalli/rate_limiter.rb

@@ -12,20 +12,74 @@ module Dalli
     0x0d
   ].map(&:chr).join("").freeze
 
+  # Dalli::RateLimiter provides arbitrary Memcached-backed rate limiting for
+  # your Ruby applications.
+  #
+  # @see file:README.md
+  #
+  # @!attribute [r] max_requests
+  #   @return [Float] the maximum number of requests in a human-friendly format
   class RateLimiter
     LOCK_TTL = 30
     LOCK_MAX_TRIES = 6
 
+    DEFAULT_OPTIONS = {
+      :key_prefix => "dalli-rate_limiter",
+      :max_requests => 5_000,
+      :period => 8_000,
+      :locking => true
+    }.freeze
+
+    private_constant :DEFAULT_OPTIONS
+
+    # Create a new instance of Dalli::RateLimiter.
+    #
+    # @param dalli [nil, ConnectionPool, Dalli::Client] the Dalli::Client (or
+    #   ConnectionPool of Dalli::Client) to use as a backing store for this
+    #   rate limiter
+    # @param options [Hash{Symbol}] configuration options for this rate limiter
+    #
+    # @option options [String] :key_prefix ("dalli-rate_limiter") a unique
+    #   string describing this rate limiter
+    # @option options [Integer, Float] :max_requests (5) maximum number of
+    #   requests over the governed interval
+    # @option options [Integer, Float] :period (8) number of seconds over
+    #    which to enforce the maximum number of requests
+    # @option options [Boolean] :locking (true) enable or disable locking
     def initialize(dalli = nil, options = {})
       @dalli = dalli || ConnectionPool.new { Dalli::Client.new }
 
-      @key_prefix = options[:key_prefix] || "dalli-rate_limiter"
-      @max_requests = to_ems(options[:max_requests] || 5)
-      @period = to_ems(options[:period] || 8)
-      @locking = options.key?(:locking) ? !!options[:locking] : true
+      options = normalize_options options
+
+      @key_prefix = options[:key_prefix]
+      @max_requests = options[:max_requests]
+      @period = options[:period]
+      @locking = options[:locking]
     end
 
+    def max_requests
+      to_fs @max_requests
+    end
+
+    # Determine whether processing a given request would exceed the rate limit.
+    #
+    # @param unique_key [String] a key to use, in combination with the
+    #   `:key_prefix` and any `:namespace` defined in the Dalli::Client, to
+    #   distinguish the item being limited from similar items
+    # @param to_consume [Integer, Float] the number of requests to consume from
+    #   the allowance (used to represent a batch of requests)
+    #
+    # @return [false] if the request can be processed as given without
+    #   exceeding the limit (including the case where the number to consume is
+    #   zero)
+    # @return [Float] if processing the request as given would exceed
+    #   the limit and the caller should wait so many [fractional] seconds
+    #   before retrying
+    # @return [-1] if the number to consume exceeds the maximum,
+    #   and the request as given would never not exceed the limit
     def exceeded?(unique_key, to_consume = 1)
+      return false if to_consume == 0
+
       to_consume = to_ems(to_consume)
 
       return -1 if to_consume > @max_requests
@@ -38,7 +92,7 @@ module Dalli
           # Short-circuit the simple case of seeing the key for the first time.
           dc.set(timestamp_key, to_ems(Time.now.to_f), @period, :raw => true)
 
-          return nil
+          return false
         end
 
         lock = acquire_lock(dc, unique_key) if @locking
@@ -46,8 +100,8 @@ module Dalli
         current_timestamp = to_ems(Time.now.to_f) # obtain timestamp after locking
 
         previous = dc.get_multi allowance_key, timestamp_key
-        previous_allowance = previous[allowance_key].to_i || @max_requests
-        previous_timestamp = previous[timestamp_key].to_i || current_timestamp
+        previous_allowance = previous.key?(allowance_key) ? previous[allowance_key].to_i : @max_requests
+        previous_timestamp = previous.key?(timestamp_key) ? previous[timestamp_key].to_i : current_timestamp
 
         allowance_delta = (1.0 * (current_timestamp - previous_timestamp) * @max_requests / @period).to_i
         projected_allowance = previous_allowance + allowance_delta
@@ -72,16 +126,30 @@ module Dalli
 
         release_lock(dc, unique_key) if lock
 
-        return nil
+        return false
       end
     end
 
-    def max_requests
-      to_fs(@max_requests)
-    end
-
     private
 
+    def normalize_options(options)
+      normalized_options = {}
+
+      normalized_options[:key_prefix] = cleanse_key options[:key_prefix] \
+        if options[:key_prefix]
+
+      normalized_options[:max_requests] = to_ems options[:max_requests].to_f \
+        if options[:max_requests]
+
+      normalized_options[:period] = to_ems options[:period].to_f \
+        if options[:period]
+
+      normalized_options[:locking] = !!options[:locking] \
+        if options.key? :locking
+
+      DEFAULT_OPTIONS.dup.merge! normalized_options
+    end
+
     def acquire_lock(dc, key)
       lock_key = format_key(key, "mutex")
 
@@ -113,7 +181,11 @@ module Dalli
     end
 
     def format_key(key, attribute)
-      "#{@key_prefix}:#{key.to_s.delete INVALID_KEY_CHARS}:#{attribute}"
+      "#{@key_prefix}:#{cleanse_key key}:#{attribute}"
+    end
+
+    def cleanse_key(key)
+      key.to_s.delete INVALID_KEY_CHARS
     end
   end
 end

data/lib/dalli/rate_limiter/version.rb

@@ -1,5 +1,5 @@
 module Dalli
   class RateLimiter
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dalli-rate_limiter
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-31 00:00:00.000000000 Z
+date: 2016-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dalli
@@ -165,7 +165,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 132983352658914105
+      hash: 2846745512546726026
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23.2