dalli-rate_limiter 0.1.0

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rbenv-vars
+.ruby-version
+.rubocop-http*yml

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,36 @@
+inherit_from:
+  - http://relaxed.ruby.style/rubocop.yml
+
+AllCops:
+  Exclude:
+    - "**/spec_helper.rb"
+    - "**/*_spec.rb"
+    - "lib/dalli-rate_limiter.rb"
+
+# It's more consistent to use the old style everywhere. If anything, I want to
+# disable the new style!
+Style/HashSyntax:
+  Enabled: false
+
+# I find it clearer to continue multiline operations with leading periods.
+# English reads left-to-right; we don't look at the ends of lines to see if
+# they continue on the next.
+Style/MultilineOperationIndentation:
+  Enabled: false
+
+# I'm not entirely opposed to this but it's going to add a ton of lines to the
+# code base...
+Style/AlignParameters:
+  Enabled: false
+
+# What, and indent this entire file another stop? No way!
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Umm, no, commented code should have no leading space.
+Style/LeadingCommentSpace:
+  Enabled: false
+
+# WHY IS THIS FEATURE DISCOURAGED IF I WANTED TO WRITE JAVA I WOULD WRITE JAVA
+Style/UnlessElse:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+services:
+  - memcached
+rvm:
+  - 1.9
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Mike Pastore
+
+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.

data/README.md

@@ -0,0 +1,193 @@
+# Dalli::RateLimiter [![Build Status](https://travis-ci.org/mwpastore/dalli-rate_limiter.svg?branch=master)](https://travis-ci.org/mwpastore/dalli-rate_limiter)
+
+**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).
+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.
+
+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
+web application that allows users to change their username, but you want to
+limit these requests to two per hour per user. Or your command-line Ruby
+application makes API calls over HTTP, but you must adhere to a strict rate
+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. It supports arbitrary unit
+quantities of consumption for operations that logically count as more than one
+request (i.e. batched requests). A simple mutex locking scheme (enabled by
+default) is used to mitigate race conditions and ensure that the limit is
+enforced under most cirumstances (see [Caveats](#caveats) below).  Math
+operations are performed with three decimal places of precision but the results
+are stored in Memcached as integers.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dalli-rate_limiter', '~> 0.1.0'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install dalli-rate_limiter
+
+## Basic Usage
+
+```ruby
+lim = Dalli::RateLimiter.new
+
+if lim.exceeded? "foo"
+  fail "Sorry, can't foo right now. Try again later!"
+else
+  # ..
+end
+```
+
+**Dalli::RateLimiter** will, by default, create a ConnectionPool with the
+default options, using a block that yields Dalli::Client instances 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.
+
+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.
+Locking can be disabled by setting the `:locking` option to `false` (see
+[Caveats](#caveats) below). 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 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 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, it will
+never not be limited. Consider a limit of 50 requests per minute: no amount of
+waiting would allow for a batch of 51 requests! To help check for this, a
+public getter method `#max_requests` is available.
+
+## Advanced Usage
+
+```ruby
+dalli = ConnectionPool.new(:size => 5, :timeout => 3) {
+  Dalli::Client.new(nil, :namespace => "myapp")
+}
+
+lim1 = Dalli::RateLimiter.new dalli,
+  :key_prefix => "username-throttle", :max_requests => 2, :period => 3_600
+
+lim2 = Dalli::RateLimiter.new dalli,
+  :key_prefix => "widgets-throttle", :max_requests => 10, :period => 60
+
+def change_username(user_id, new_username)
+  if lim1.exceeded? user_id
+    halt 422, "Sorry! Only two username changes allowed per hour."
+  end
+
+  # ..
+end
+
+def add_widgets(foo_id, some_widgets)
+  if some_widgets.length > lim2.max_requests
+    halt 400, "Too many widgets!"
+  end
+
+  if time = lim2.exceeded? foo_id, some_widgets.length
+    halt 422, "Sorry! Unable to process request. " \
+      "Please wait at least #{time} seconds before trying again."
+  end
+
+  # ..
+end
+```
+
+## Compatibility
+
+**Dalli::RateLimiter** is compatible with Ruby 1.9.3 and greater and has been
+tested with frozen string literals under Ruby 2.3.0.
+
+You might consider installing the [kgio][7] gem to [give Dalli a 10-20%
+performance boost][8].
+
+## Caveats
+
+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
+at the drop of a hat. Mission-critical use cases, where operations absolutely,
+positively have to be idempotent, should probably seek solutions elsewhere.
+
+The limiting algorithm seems to work well but it is far from battle-tested. I
+tried to use atomic operations where possible to mitigate race conditions, but
+still had to implement a locking scheme, which might slow down operations and
+lead to timeouts and exceptions if a lock can't be acquired for some reason.
+Locking can be disabled but this will increase the chances that a determined
+attacker figures out a way to defeat the limit.
+
+I will likely be revisiting the algorithm in the future, but at the moment it
+is in the unfortunate state of "good enough".
+
+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.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/mwpastore/dalli-rate_limiter.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).
+
+[1]: https://github.com/jeremy/rack-ratelimit "Rate::Ratelimit"
+[2]: https://github.com/bendiken/rack-throttle "Rack::Throttle"
+[3]: https://github.com/kickstarter/rack-attack "Rack::Attack"
+[4]: https://github.com/petergoldstein/dalli "Dalli"
+[5]: https://github.com/mperham/connection_pool "ConnectionPool"
+[6]: http://memcached.org "Memcached"
+[7]: http://bogomips.org/kgio "kgio"
+[8]: https://github.com/petergoldstein/dalli/blob/master/Performance.md "Dalli Performance"

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dalli/rate_limiter"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dalli-rate_limiter.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "dalli/rate_limiter/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "dalli-rate_limiter"
+  spec.version       = Dalli::RateLimiter::VERSION
+  spec.authors       = ["Mike Pastore"]
+  spec.email         = ["mike@oobak.org"]
+
+  spec.summary       = "Arbitrary Memcached-backed rate limiting for Ruby"
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/mwpastore/dalli-rate_limiter"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^#{spec.bindir}/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  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"
+  spec.add_development_dependency "rubocop", "~> 0.35.0"
+  spec.add_development_dependency "rspec", "~> 3.4.0"
+  spec.add_development_dependency "rspec-given", "~> 3.8.0"
+end

data/lib/dalli-rate_limiter.rb

@@ -0,0 +1 @@
+require "dalli/rate_limiter"

data/lib/dalli/rate_limiter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "dalli"
+require "connection_pool"
+
+require "dalli/rate_limiter/version"
+
+module Dalli
+  INVALID_KEY_CHARS = [
+    0x00, 0x20,
+    0x09, 0x0a,
+    0x0d
+  ].map(&:chr).join("").freeze
+
+  class RateLimiter
+    LOCK_TTL = 30
+    LOCK_MAX_TRIES = 6
+
+    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
+    end
+
+    def exceeded?(unique_key, to_consume = 1)
+      to_consume = to_ems(to_consume)
+
+      timestamp_key = format_key(unique_key, "timestamp")
+      allowance_key = format_key(unique_key, "allowance")
+
+      @dalli.with do |dc|
+        if to_consume <= @max_requests
+          if dc.add(allowance_key, @max_requests - to_consume, @period, :raw => true)
+            # 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
+          end
+        end
+
+        lock = acquire_lock(dc, unique_key) if @locking
+
+        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
+
+        allowance_delta = (1.0 * (current_timestamp - previous_timestamp) * @max_requests / @period).to_i
+        projected_allowance = previous_allowance + allowance_delta
+        if projected_allowance > @max_requests
+          projected_allowance = @max_requests
+          allowance_delta = @max_requests - previous_allowance
+        end
+
+        if to_consume > projected_allowance
+          release_lock(dc, unique_key) if lock
+
+          # Tell the caller how long (in seconds) to wait before retrying the request.
+          return to_fs((1.0 * (to_consume - projected_allowance) * @period / @max_requests).to_i)
+        end
+
+        allowance_delta -= to_consume
+
+        dc.set(timestamp_key, current_timestamp, @period, :raw => true)
+        dc.add(allowance_key, previous_allowance, 0, :raw => true) # ensure baseline exists
+        dc.send(allowance_delta < 0 ? :decr : :incr, allowance_key, allowance_delta.abs)
+        dc.touch(allowance_key, @period)
+
+        release_lock(dc, unique_key) if lock
+
+        return nil
+      end
+    end
+
+    def max_requests
+      to_fs(@max_requests)
+    end
+
+    private
+
+    def acquire_lock(dc, key)
+      lock_key = format_key(key, "mutex")
+
+      (1..LOCK_MAX_TRIES).each do |tries|
+        if lock = dc.add(lock_key, true, LOCK_TTL)
+          return lock
+        else
+          sleep rand(2**tries)
+        end
+      end
+
+      raise DalliError, "Unable to lock key for update"
+    end
+
+    def release_lock(dc, key)
+      lock_key = format_key(key, "mutex")
+
+      dc.delete(lock_key)
+    end
+
+    # Convert fractional units to encoded milliunits
+    def to_ems(fs)
+      (fs * 1_000).to_i
+    end
+
+    # Convert encoded milliunits to fractional units
+    def to_fs(ems)
+      1.0 * ems / 1_000
+    end
+
+    def format_key(key, attribute)
+      "#{@key_prefix}:#{key.to_s.delete INVALID_KEY_CHARS}:#{attribute}"
+    end
+  end
+end

data/lib/dalli/rate_limiter/version.rb

@@ -0,0 +1,5 @@
+module Dalli
+  class RateLimiter
+    VERSION = "0.1.0"
+  end
+end

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: dalli-rate_limiter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Mike Pastore
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dalli
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.7.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.7.5
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.11.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.5.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.35.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.35.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+- !ruby/object:Gem::Dependency
+  name: rspec-given
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+description: Arbitrary Memcached-backed rate limiting for Ruby
+email:
+- mike@oobak.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .rubocop.yml
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- dalli-rate_limiter.gemspec
+- lib/dalli-rate_limiter.rb
+- lib/dalli/rate_limiter.rb
+- lib/dalli/rate_limiter/version.rb
+homepage: https://github.com/mwpastore/dalli-rate_limiter
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 717744935584309687
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23.2
+signing_key: 
+specification_version: 3
+summary: Arbitrary Memcached-backed rate limiting for Ruby
+test_files: []