dalli-rate_limiter 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1a4f84f2172c086af81637b00a5f9d29d6d856a2
-  data.tar.gz: f49d4308f8d54d941c4deb47a6c48995ab8f9a86
+  metadata.gz: 192caf393892d4ebed3b31ea0a9723eb7c6b5f65
+  data.tar.gz: 7a968b2e507d1b264de374e05089a49a08a9bd46
 SHA512:
-  metadata.gz: 92c0c0915aaa215d4f7968113b95f09e710a9d5fbb1da2fc6c1466930ba3e0e8eba7ad2f3ec8eb6079597929eea22bb9c276d21270e6bcfc11fe246ef7191703
-  data.tar.gz: 2e12c617f7953b982f05d3e7072919234ca4c542268c66fbe54151931f725079263e22ac84fd28cab9ca6301a76e41581dd1a383551239fb85701d291b7f2657
+  metadata.gz: 74b36d9bf284fe2aa66cced426037111c568279acf1662348d52ed8d18061e408d362979fbddfd87311f4feb83b5edb44d67f62941abacc306368c9f34ea8d38
+  data.tar.gz: 8e3b10b300b5d022649a26b42d68e926f82e852e382b57c446138eb8e10cdc333b0d3eac8f8677542fb2a42562e2620ef5e61bcd651d087bc87aac8bc2d3b124

data/README.md

@@ -3,10 +3,10 @@
 **Dalli::RateLimiter** provides arbitrary [Memcached][6]-backed rate limiting
 for your Ruby applications. You may be using an application-level rate limiter
 such as [Rack::Ratelimit][1], [Rack::Throttle][2], or [Rack::Attack][3], or
-something higher up in your stack (like an Nginx zone or HAproxy stick-table).
+something higher up in your stack (like an NGINX zone or HAproxy stick-table).
 This is not intended to be a replacement for any of those functions. Your
 application may not even be a web service and yet you find yourself needing to
-throttle certain types of operations.
+limit (or throttle) certain types of operations.
 
 This library allows you to impose specific rate limits on specific functions at
 whatever granularity you desire. For example, you have a function in your Ruby
@@ -17,15 +17,14 @@ limit imposed by the provider for a certain endpoint. It wouldn't make sense to
 apply these limits at the application level—it would be much easier to
 tightly integrate a check within your business logic.
 
-**Dalli::RateLimiter** leverages the excellent [Dalli][4] and
-[ConnectionPool][5] gems for fast and efficient Memcached access and
-thread-safe connection pooling. It uses an allowance counter and floating
-timestamp to implement a sliding window for each unique key, enforcing a limit
-of _m_ requests over a period of _n_ seconds. If you're familiar with
-[Sidekiq][10] (which is another excellent piece of software, written by the same
-person who wrote Dalli and ConnectionPool), it is similar to the Window style
-of the Sidekiq::Limiter class, although the invocation syntax differs slightly
-(see [Block Form](#block-form) below for an example of the differences).
+**Dalli::RateLimiter** leverages the excellent [Dalli][4] gem for fast and
+efficient (and thread-safe) Memcached access. It uses an allowance counter and
+floating timestamp to implement a sliding window for each unique key, enforcing
+a limit of _m_ requests over a period of _n_ seconds. If you're familiar with
+[Sidekiq][10] (which is another excellent piece of software, written by the
+same person who wrote Dalli), it is similar to the Window style of the
+Sidekiq::Limiter class, although the invocation syntax differs slightly (see
+[Block Form](#block-form) below for an example of the differences).
 
 It supports arbitrary unit quantities of consumption for partial operations or
 for operations that logically count as more than one request (i.e. batched
@@ -40,7 +39,7 @@ performed with floating-point precision.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'dalli-rate_limiter', '~> 0.2.0'
+gem 'dalli-rate_limiter', '~> 0.3.0'
 ```
 
 And then execute:
@@ -63,16 +62,23 @@ def do_foo
 
   # Do foo...
 end
+
+def do_bar
+  lim = Dalli::RateLimiter.new
+
+  lim.without_exceeding do
+    # Do bar...
+  end
+end
 ```
 
-**Dalli::RateLimiter** will, by default, create a ConnectionPool with its
-default options, using a block that yields Dalli::Client instances with its
+**Dalli::RateLimiter** will, by default, use a Dalli::Client instance with the
 default options. If `MEMCACHE_SERVERS` is set in your environment, or if your
 Memcached instance is running on localhost, port 11211, this is the quickest
 way to get started. Alternatively, you can pass in your own single-threaded
 Dalli::Client instance—or your own multi-threaded ConnectionPool instance
-(wrapping Dalli::Client)—as the first argument to customize the
-connection settings. Pass in `nil` to force the default behavior.
+(see [Compatibility](#compatibility) below)—as the first argument to
+customize the connection settings. Pass in `nil` to force the default behavior.
 
 The library itself defaults to five (5) requests per eight (8) seconds, but
 these can easily be changed with the `:max_requests` and `:period` options.
@@ -80,19 +86,19 @@ Locking can be fine-tuned by setting the `:lock_timeout` option. A
 `:key_prefix` option can be specified as well; note that this will be used in
 combination with any `:namespace` option defined in the Dalli::Client.
 
-The **Dalli::RateLimiter** instance itself is not stateful, so it can be
-instantiated as needed (e.g. in a function definition) or in a more global
-scope (e.g. in a Rails initializer). It does not mutate any of its own
-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 **Dalli::RateLimiter** instance itself is not stateful (in that it doesn't
+track the state of the things being limited, only the parameters of the limit
+itself), so it can be instantiated as needed (e.g. in a function definition) or
+in a more global scope (e.g. in a Rails initializer). It does not mutate any of
+its own attributes or allow its attributes to be mutated so it should be safe
+to share between threads.
 
 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
+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).
@@ -114,45 +120,69 @@ the lock.
 ## Advanced Usage
 
 ```ruby
+require "connection_pool"
+
 dalli = ConnectionPool.new(:size => 5, :timeout => 3) {
-  Dalli::Client.new(nil, :namespace => "myapp")
+  Dalli::Client.new nil, :namespace => "myapp"
 }
 
-lim1 = Dalli::RateLimiter.new dalli,
-  :key_prefix => "username-throttle", :max_requests => 2, :period => 3_600
+USERNAME_LIMIT = Dalli::RateLimiter.new dalli,
+  :key_prefix => "username-limit", :max_requests => 2, :period => 3_600
 
-lim2 = Dalli::RateLimiter.new dalli,
-  :key_prefix => "widgets-throttle", :max_requests => 10, :period => 60
+WIDGETS_LIMIT = Dalli::RateLimiter.new dalli,
+  :key_prefix => "widgets-limit", :max_requests => 10, :period => 60
 
 def change_username(user_id, new_username)
-  if lim1.exceeded? user_id
+  if USERNAME_LIMIT.exceeded?(user_id) # user-specific limit on changing usernames
     halt 422, "Sorry! Only two username changes allowed per hour."
   end
 
   # Change username...
 rescue Dalli::RateLimiter::LockError
-  # Unable to acquire a lock...
+  # Unable to acquire a lock before lock timeout...
 end
 
-def add_widgets(foo_id, some_widgets)
-  if some_widgets.length > lim2.max_requests
+def add_widgets(some_widgets)
+  if some_widgets.length > WIDGETS_LIMIT.max_requests
     halt 400, "Too many widgets!"
   end
 
-  if time = lim2.exceeded?(foo_id, some_widgets.length)
+  if time = WIDGETS_LIMIT.exceeded?(nil, some_widgets.length) # global limit on adding widgets
     halt 422, "Sorry! Unable to process request. " \
       "Please wait at least #{time} seconds before trying again."
   end
 
   # Add widgets...
 rescue Dalli::RateLimiter::LockError
-  # Unable to acquire a lock...
+  # Unable to acquire a lock before lock timeout...
 end
 ```
 
 ## Block Form
 
-Rewriting the Sidekiq::Limiter.window [example][9] from its documentation:
+This alternative syntax will sleep (as necessary) until the request can be
+processed without exceeding the limit. An optional wait timout can be specified
+to prevent the method from sleeping forever. Rewriting the `add_widgets` method
+from above:
+
+```ruby
+def add_widgets(some_widgets)
+  if some_widgets.length > WIDGETS_LIMIT.max_requests
+    halt 400, "Too many widgets!"
+  end
+
+  WIDGETS_LIMIT.without_exceeding(nil, some_widgets.length, :wait_timeout => 30) do
+    # Add widgets...
+  end
+rescue Dalli::RateLimiter::LimitError
+  halt 422, "Sorry! Request timed out. Please try again later."
+rescue Dalli::RateLimiter::LockError
+  # Unable to acquire a lock before lock timeout...
+end
+```
+
+This feature was originally requested for parity with Sidekiq::Limiter, so
+here's an example adapted from Sidekiq::Limiter.window's [documentation][9]:
 
 ```ruby
 def perform(user_id)
@@ -165,7 +195,7 @@ def perform(user_id)
 rescue Dalli::RateLimiter::LimitError
   # Unable to execute block before wait timeout...
 rescue Dalli::RateLimiter::LockError
-  # Unable to acquire a lock...
+  # Unable to acquire a lock before lock timeout...
 end
 ```
 
@@ -175,8 +205,8 @@ end results. Or, likewise, you could set `:key_prefix` to `"stripe:#{user_id}"`
 and pass in `nil` as the first argument to `#without_exceeding`. Sometimes it
 makes sense to share an instance between method calls, or indeed between
 different methods, and sometimes it doesn't. Please note that if `:key_prefix`
-and the first argument to `#exceeded?` or `#without_exceeding` are both `nil`,
-Dalli::Client will abort with an ArgumentError ("key cannot be blank").
+and the first argument to `#without_exceeding` (or `#exceeded?`) are both
+`nil`, Dalli::Client will abort with an ArgumentError ("key cannot be blank").
 
 ## Compatibility
 
@@ -184,7 +214,13 @@ Dalli::Client will abort with an ArgumentError ("key cannot be blank").
 tested with frozen string literals under Ruby 2.3.0. It has also been tested
 under Rubinius 2.15 and 3.14, and JRuby 1.7 (in 1.9.3 execution mode) and 9K.
 
-You might consider installing the [kgio][7] gem to [give Dalli a 10-20%
+If you are sharing a **Dalli::RateLimiter** instance between multiple threads
+and performance is a concern, you might consider adding the
+[connection_pool][5] gem to your project and passing in a ConnectionPool
+instance (wrapping Dalli::Client) as the first argument to the constructor.
+Make sure your pool has enough slots (`:size`) for these operations; I aim for
+one slot per thread plus one or two for overhead in my applications. You might
+also consider adding the [kgio][7] gem to your project to [give Dalli a 10-20%
 performance boost][8].
 
 ## Caveats
@@ -193,23 +229,27 @@ A rate-limiting system is only as good as its backing store, and it should be
 noted that a Memcached ring can lose members or indeed its entire working set
 (in the event of a flush operation) at the drop of a hat. Mission-critical use
 cases, where repeated operations absolutely, positively have to be restricted,
-should probably seek solutions elsewhere.
-
-The limiting algorithm, which was overhauled for the 0.2.0 release to greatly
-reduce the number of round-trips to Memcached, seems to work well but it is
-far from battle-tested. Simple benchmarking against a local Memcached instance
-shows zero lock timeouts with the default settings and 100 threads hitting the
-same limit concurrently. (Testing performed on a 2012 MacBook Pro with an Intel
-i7-3615QM processor and 16 GB RAM; benchmarking scripts available in the `bin`
-subdirectory of this repository.)
+should probably seek solutions elsewhere. If you have already have Redis in
+your stack, you might consider a Redis-based rate limiter (such as
+Sidekiq::Limiter). Redis has better mechanisms for locking and updating keys,
+it doesn't lose its working set on restart, and polling can be reduced or
+eliminated through use of its built-in Lua scripting.
+
+The limiting algorithm—which was overhauled for the 0.2.0 release to
+greatly reduce the number of round-trips to Memcached—seems to work well,
+but it is far from battle-tested. Simple benchmarking against a local Memcached
+instance shows zero lock timeouts with the default settings and 200 threads
+banging away at the same limit concurrently for an extended period of time.
+(Testing performed on a 2012 MacBook Pro with an Intel i7-3615QM processor and
+16 GB RAM; benchmarking scripts available in the `bin` subdirectory of this
+repository.) I do plan on performing additional testing with a few more client
+cores against a production (or production-like) Memcached ring at some point in
+the near future and will update these results at that time.
 
 As noted above, this is not a replacement for an application-level rate limit,
 and if your application faces the web, you should probably definitely have
 something else in your stack to handle e.g. a casual DoS.
 
-Make sure your ConnectionPool has enough slots for these operations. I aim for
-one slot per thread plus one or two for overhead in my applications.
-
 ## Documentation
 
 This README is fairly comprehensive, but additional information about the

data/dalli-rate_limiter.gemspec

@@ -22,7 +22,6 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 1.9.3'
 
   spec.add_runtime_dependency "dalli", "~> 2.7.5"
-  spec.add_runtime_dependency "connection_pool", "~> 2.2.0"
 
   spec.add_development_dependency "bundler", "~> 1.11.0"
   spec.add_development_dependency "rake", "~> 10.5.0"

data/lib/dalli/rate_limiter.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "dalli"
-require "connection_pool"
-
 require "dalli/rate_limiter/version"
 
 module Dalli
@@ -42,7 +40,7 @@ module Dalli
     # @option options [Integer, Float] :lock_timeout (30) maximum number of
     #    seconds to wait for the lock to become available
     def initialize(dalli = nil, options = {})
-      @pool = dalli || ConnectionPool.new { Dalli::Client.new }
+      @pool = dalli || Dalli::Client.new
 
       options = normalize_options options
 
@@ -72,11 +70,12 @@ module Dalli
     #
     # @raise [LockError] if a lock cannot be obtained before `@lock_timeout`
     def exceeded?(unique_key = nil, to_consume = 1)
+      to_consume = to_consume.to_f
+
       return false if to_consume <= 0
       return -1 if to_consume > max_requests
 
       key = [@key_prefix, unique_key].compact.join(":")
-      to_consume = to_consume.to_f
 
       try = 1
       total_time = 0
@@ -138,12 +137,12 @@ module Dalli
 
     private
 
-    def compute(previous, to_consume)
+    def compute(previous_value, to_consume)
       current_timestamp = Time.now.to_f
 
-      previous ||= {}
-      previous_allowance = previous[:allowance] || @max_requests
-      previous_timestamp = previous[:timestamp] || current_timestamp
+      previous_value ||= {}
+      previous_allowance = previous_value[:allowance] || @max_requests
+      previous_timestamp = previous_value[:timestamp] || current_timestamp
 
       allowance_delta = (current_timestamp - previous_timestamp) * @max_requests / @period
       projected_allowance = previous_allowance + allowance_delta
@@ -153,16 +152,16 @@ module Dalli
       end
 
       if to_consume > projected_allowance
-        # Determine how long the caller must wait (in seconds) before retrying the request.
+        # Determine how long the caller must wait (in seconds) before retrying.
         wait = (to_consume - projected_allowance) * @period / @max_requests
       else
-        current = {
+        value = {
           :allowance => previous_allowance + allowance_delta - to_consume,
           :timestamp => current_timestamp
         }
       end
 
-      [wait || 0, current || previous]
+      [wait || 0, value || previous_value]
     end
 
     def normalize_options(options)

data/lib/dalli/rate_limiter/version.rb

@@ -1,5 +1,5 @@
 module Dalli
   class RateLimiter
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dalli-rate_limiter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Mike Pastore
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-08 00:00:00.000000000 Z
+date: 2016-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dalli
@@ -24,20 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.7.5
-- !ruby/object:Gem::Dependency
-  name: connection_pool
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.2.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.2.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement