prorate 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89ad7bfadc58561263e35de3de2a0eef9c4b5aca
-  data.tar.gz: 51591b0aabe76204c4a9029a095150faf434c84d
+  metadata.gz: dab868f09fd0b191abe56fdfdb156271331d397e
+  data.tar.gz: 0c9d8670999217b9b14f662a53b589f7c3b0b93d
 SHA512:
-  metadata.gz: 5393f7eb13d4bd9236f3809c90215ae1a9700dd20a17c195db4180a526502278055365fc8e5dfce4644bba737a808cd738e7e6d3120f07ff733d2a8d214a7749
-  data.tar.gz: 604f4fd70fd8d9506cdccff6e819d91d2e26eae94e70ba00f3cf212118ca5d2fb2eeab8052c0702bea4a76d423be93c860dded6de64cd140ad1ddacad9ea1e2e
+  metadata.gz: c7c9909a1ebf831a56b3216a3387598d1c72f20463962329a9d61ea993533f5298769af63f6e16d837a2b22f1f1d1008b7ae2b1413ac80ae58b264f08b72eeb5
+  data.tar.gz: b9c3b0b86240e6d8dd9b504a3c8bc2341bd230138e263edad0fc8e03db900cb9c1ca8e777f3ac22bea5e44f00750bad13568d47c315315d09608ab4bc597cc1c

data/.travis.yml

@@ -1,7 +1,10 @@
 rvm:
-- 2.2.5
-- 2.3.3
-- 2.4.1
+- 2.2
+- 2.3
+- 2.4
+- 2.5
+- 2.6
+- 2.7
 
 services:
 - redis

data/README.md

@@ -1,8 +1,10 @@
 # Prorate
 
-Provides a low-level time-based throttle. Is mainly meant for situations where using something like Rack::Attack is not very
-useful since you need access to more variables. Under the hood, this uses a Lua script that implements the
-[Leaky Bucket](https://en.wikipedia.org/wiki/Leaky_bucket) algorithm in a single threaded and race condition safe way.
+Provides a low-level time-based throttle. Is mainly meant for situations where
+using something like Rack::Attack is not very useful since you need access to
+more variables. Under the hood, this uses a Lua script that implements the
+[Leaky Bucket](https://en.wikipedia.org/wiki/Leaky_bucket) algorithm in a single
+threaded and race condition safe way.
 
 [![Build Status](https://travis-ci.org/WeTransfer/prorate.svg?branch=master)](https://travis-ci.org/WeTransfer/prorate)
 [![Gem Version](https://badge.fury.io/rb/prorate.svg)](https://badge.fury.io/rb/prorate)
@@ -17,29 +19,106 @@ gem 'prorate'
 
 And then execute:
 
-    $ bundle
+```shell
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install prorate
+```shell
+gem install prorate
+```
 
 ## Usage
 
+The simplest mode of operation is throttling an endpoint, using the throttler
+before the action happens.
+
 Within your Rails controller:
 
-    t = Prorate::Throttle.new(redis: Redis.new, logger: Rails.logger,
-        name: "throttle-login-email", limit: 20, period: 5.seconds)
-    # Add all the parameters that function as a discriminator
-    t << request.ip << params.require(:email)
-    # ...and call the throttle! method
-    t.throttle! # Will raise a Prorate::Throttled exception if the limit has been reached
+```ruby
+t = Prorate::Throttle.new(
+    redis: Redis.new,
+    logger: Rails.logger,
+    name: "throttle-login-email",
+    limit: 20,
+    period: 5.seconds
+)
+# Add all the parameters that function as a discriminator.
+t << request.ip << params.require(:email)
+# ...and call the throttle! method
+t.throttle! # Will raise a Prorate::Throttled exception if the limit has been reached
+#
+# Your regular action happens after this point
+```
+
+To capture that exception, in the controller
+
+```ruby
+rescue_from Prorate::Throttled do |e|
+  response.set_header('Retry-After', e.retry_in_seconds.to_s)
+  render nothing: true, status: 429
+end
+```
+
+### Throttling and checking of its status
+
+More exquisite control can be achieved by combining throttling (see previous
+step) and - in subsequent calls - checking the status of the throttle before
+invoking the throttle.
+
+Let's say you have an endpoint that not only needs throttling, but you want to
+ban [credential stuffers](https://en.wikipedia.org/wiki/Credential_stuffing)
+outright. This is a multi-step process:
+
+1. Respond with a 429 if the discriminators of the request would land in an
+  already blocking 'credential-stuffing'-throttle
+1. Run your regular throttling
+1. Perform your sign in action
+1. If the sign in was unsuccessful, add the discriminators to the
+  'credential-stuffing'-throttle
+
+In your controller that would look like this:
+
+```ruby
+t = Prorate::Throttle.new(
+    redis: Redis.new,
+    logger: Rails.logger,
+    name: "credential-stuffing",
+    limit: 20,
+    period: 20.minutes
+)
+# Add all the parameters that function as a discriminator.
+t << request.ip
+# And before anything else, check whether it is throttled
+if t.status.throttled?
+  response.set_header('Retry-After', t.status.remaining_throttle_seconds.to_s)
+  render(nothing: true, status: 429) and return
+end
+
+# run your regular throttles for the endpoint
+other_throttles.map(:throttle!)
+# Perform your sign in logic..
+
+user = YourSignInLogic.valid?(
+  email: params[:email],
+  password: params[:password]
+)
+
+# Add the request to the credential stuffing throttle if we didn't succeed
+t.throttle! unless user
+
+# the rest of your action
+```
 
 To capture that exception, in the controller
 
-    rescue_from Prorate::Throttled do |e|
-      response.set_header('Retry-After', e.retry_in_seconds.to_s)
-      render nothing: true, status: 429
-    end
+```ruby
+rescue_from Prorate::Throttled do |e|
+  response.set_header('Retry-After', e.retry_in_seconds.to_s)
+  render nothing: true, status: 429
+end
+```
 
 ## Development
 
@@ -51,8 +130,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/WeTransfer/prorate.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/lib/prorate/rate_limit.lua

@@ -1,5 +1,5 @@
 -- Single threaded Leaky Bucket implementation.
--- args: key_base, leak_rate, max_bucket_capacity, block_duration
+-- args: key_base, leak_rate, max_bucket_capacity, block_duration, n_tokens
 -- returns: an array of two integers, the first of which indicates the remaining block time.
 -- if the block time is nonzero, the second integer is always zero. If the block time is zero,
 -- the second integer indicates the level of the bucket

data/lib/prorate/throttle.rb

@@ -96,6 +96,19 @@ module Prorate
       end
     end
 
+    def status
+      discriminator = Digest::SHA1.hexdigest(Marshal.dump(@discriminators))
+      identifier = [name, discriminator].join(':')
+
+      redis.with do |r|
+        is_blocked = r.exists("#{identifier}.block")
+        return Status.new(is_throttled: false, remaining_throttle_seconds: 0) unless is_blocked
+
+        remaining_seconds = r.get("#{identifier}.block").to_i - Time.now.to_i
+        Status.new(is_throttled: true, remaining_throttle_seconds: remaining_seconds)
+      end
+    end
+
     private
 
     def run_lua_throttler(redis:, identifier:, bucket_capacity:, leak_rate:, block_for:, n_tokens:)
@@ -110,5 +123,11 @@ module Prorate
         raise e
       end
     end
+
+    class Status < Ks.strict(:is_throttled, :remaining_throttle_seconds)
+      def throttled?
+        is_throttled
+      end
+    end
   end
 end

data/lib/prorate/version.rb

@@ -1,3 +1,3 @@
 module Prorate
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/prorate.gemspec

@@ -30,9 +30,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency "ks"
   spec.add_dependency "redis", ">= 2"
   spec.add_development_dependency "connection_pool", "~> 2"
-  spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 12.3"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency 'wetransfer_style', '0.6.0'
+  spec.add_development_dependency 'wetransfer_style', '0.6.5'
   spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'pry', '~> 0.12.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prorate
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Julik Tarkhanov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-13 00:00:00.000000000 Z
+date: 2020-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ks
@@ -56,30 +56,30 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.6.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.6.5
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
 description: Can be used to implement all kinds of throttles
 email:
 - me@julik.nl