berater 0.4.0 → 0.7.0

data/spec/rate_limiter_spec.rb

@@ -1,12 +1,13 @@
 describe Berater::RateLimiter do
-  it_behaves_like 'a limiter', Berater.new(:key, :rate, 3, :second)
+  it_behaves_like 'a limiter', described_class.new(:key, 3, :second)
+  it_behaves_like 'a limiter', described_class.new(:key, 3.5, :second)
 
   describe '.new' do
     let(:limiter) { described_class.new(:key, 1, :second) }
 
     it 'initializes' do
       expect(limiter.key).to be :key
-      expect(limiter.count).to eq 1
+      expect(limiter.capacity).to eq 1
       expect(limiter.interval).to eq :second
     end
 
@@ -15,82 +16,48 @@ describe Berater::RateLimiter do
     end
   end
 
-  describe '#count' do
-    def expect_count(count)
-      limiter = described_class.new(:key, count, :second)
-      expect(limiter.count).to eq count
+  describe '#capacity' do
+    def expect_capacity(capacity)
+      limiter = described_class.new(:key, capacity, :second)
+      expect(limiter.capacity).to eq capacity
     end
 
-    it { expect_count(0) }
-    it { expect_count(1) }
-    it { expect_count(100) }
+    it { expect_capacity(0) }
+    it { expect_capacity(1) }
+    it { expect_capacity(1.5) }
+    it { expect_capacity(100) }
 
     context 'with erroneous values' do
-      def expect_bad_count(count)
+      def expect_bad_capacity(capacity)
         expect do
-          described_class.new(:key, count, :second)
+          described_class.new(:key, capacity, :second)
         end.to raise_error ArgumentError
       end
 
-      it { expect_bad_count(0.5) }
-      it { expect_bad_count(-1) }
-      it { expect_bad_count('1') }
-      it { expect_bad_count(:one) }
+      it { expect_bad_capacity(-1) }
+      it { expect_bad_capacity('1') }
+      it { expect_bad_capacity(:one) }
     end
   end
 
   describe '#interval' do
-    def expect_interval(interval, expected)
-      limiter = described_class.new(:key, 1, interval)
-      expect(limiter.interval).to eq expected
-    end
-
-    context 'with ints' do
-      it { expect_interval(0, 0) }
-      it { expect_interval(1, 1) }
-      it { expect_interval(33, 33) }
-    end
+    # see spec/utils_spec.rb for more
 
-    context 'with symbols' do
-      it { expect_interval(:sec, :second) }
-      it { expect_interval(:second, :second) }
-      it { expect_interval(:seconds, :second) }
+    subject { described_class.new(:key, 1, :second) }
 
-      it { expect_interval(:min, :minute) }
-      it { expect_interval(:minute, :minute) }
-      it { expect_interval(:minutes, :minute) }
-
-      it { expect_interval(:hour, :hour) }
-      it { expect_interval(:hours, :hour) }
+    it 'saves the interval in original and millisecond format' do
+      expect(subject.interval).to be :second
+      expect(subject.instance_variable_get(:@interval_msec)).to be 10**3
     end
 
-    context 'with strings' do
-      it { expect_interval('sec', :second) }
-      it { expect_interval('minute', :minute) }
-      it { expect_interval('hours', :hour) }
-    end
-
-    context 'with erroneous values' do
-      def expect_bad_interval(interval)
-        expect do
-          described_class.new(:key, 1, interval)
-        end.to raise_error(ArgumentError)
-      end
+    it 'must be > 0' do
+      expect {
+        described_class.new(:key, 1, 0)
+      }.to raise_error(ArgumentError)
 
-      it { expect_bad_interval(-1) }
-      it { expect_bad_interval(:secondz) }
-      it { expect_bad_interval('huor') }
-    end
-
-    context 'interprets values' do
-      def expect_sec(interval, expected)
-        limiter = described_class.new(:key, 1, interval)
-        expect(limiter.instance_variable_get(:@interval_sec)).to eq expected
-      end
-
-      it { expect_sec(:second, 1) }
-      it { expect_sec(:minute, 60) }
-      it { expect_sec(:hour, 3600) }
+      expect {
+        described_class.new(:key, 1, -1)
+      }.to raise_error(ArgumentError)
     end
   end
 
@@ -109,53 +76,183 @@ describe Berater::RateLimiter do
     it 'limits excessive calls' do
       3.times { limiter.limit }
 
-      expect(limiter).to be_overrated
+      expect(limiter).to be_overloaded
     end
 
-    it 'limit resets over time' do
+    it 'resets limit over time' do
       3.times { limiter.limit }
-      expect(limiter).to be_overrated
+      expect(limiter).to be_overloaded
 
-      # travel forward a second
       Timecop.freeze(1)
 
       3.times { limiter.limit }
-      expect(limiter).to be_overrated
+      expect(limiter).to be_overloaded
     end
-  end
 
-  context 'with same key, different limiters' do
-    let(:limiter_one) { described_class.new(:key, 1, :second) }
-    let(:limiter_two) { described_class.new(:key, 1, :second) }
+    context 'with millisecond precision' do
+      it 'resets limit over time' do
+        3.times { limiter.limit }
+        expect(limiter).to be_overloaded
+
+        # travel forward to just before the count decrements
+        Timecop.freeze(0.333)
+        expect(limiter).to be_overloaded
+
+        # traveling one more millisecond will decrement the count
+        Timecop.freeze(0.001)
+        limiter.limit
+        expect(limiter).to be_overloaded
+      end
+
+      it 'works when drip rate is < 1 per millisecond' do
+        limiter = described_class.new(:key, 2_000, :second)
+
+        limiter.capacity.times { limiter.limit }
+        expect(limiter).to be_overloaded
+
+        Timecop.freeze(0.001)
+        expect(limiter).not_to be_overloaded
 
-    it 'works as expected' do
-      expect(limiter_one.limit).not_to be_overrated
+        2.times { limiter.limit }
+      end
+    end
 
-      expect(limiter_one).to be_overrated
-      expect(limiter_two).to be_overrated
+    context 'when capacity is a Float' do
+      let(:limiter) { described_class.new(:key, 1.5, :second) }
+
+      it 'still works' do
+        limiter.limit
+        expect(limiter).not_to be_overloaded
+
+        expect { limiter.limit }.to be_overloaded
+
+        limiter.limit(cost: 0.5)
+      end
+    end
+
+    it 'accepts a dynamic capacity' do
+      limiter = described_class.new(:key, 1, :second)
+
+      expect { limiter.limit(capacity: 0) }.to be_overloaded
+      5.times { limiter.limit(capacity: 10) }
+      expect { limiter }.to be_overloaded
+    end
+
+    context 'works with cost parameter' do
+      it { expect { limiter.limit(cost: 4) }.to be_overloaded }
+
+      it 'works within limit' do
+        limiter.limit(cost: 3)
+        expect { limiter.limit }.to be_overloaded
+      end
+
+      it 'resets over time' do
+        limiter.limit(cost: 3)
+        expect(limiter).to be_overloaded
+
+        Timecop.freeze(1)
+        expect(limiter).not_to be_overloaded
+      end
+
+      context 'when cost is a Float' do
+        it 'still works' do
+          2.times { limiter.limit(cost: 1.5) }
+          expect(limiter).to be_overloaded
+        end
+
+        it 'calculates contention correctly' do
+          # note: Redis must return Floats as strings to maintain precision
+          lock = limiter.limit(cost: 1.5)
+          expect(lock.contention).to be 1.5
+        end
+      end
+    end
+
+    context 'with clock skew' do
+      let(:limiter) { described_class.new(:key, 10, :second) }
+
+      it 'works skewing backward' do
+        limiter.limit(cost: 9)
+
+        Timecop.freeze(-0.1) do
+          limiter.limit
+          expect(limiter).to be_overloaded
+        end
+
+        expect(limiter).to be_overloaded
+
+        Timecop.freeze(0.1)
+        limiter.limit
+        expect(limiter).to be_overloaded
+      end
+
+      it 'works skewing forward' do
+        limiter.limit
+
+        Timecop.freeze(0.1) do
+          # one drip later
+          limiter.limit(cost: 10)
+          expect(limiter).to be_overloaded
+        end
+
+        expect(limiter).to be_overloaded
+
+        Timecop.freeze(0.1)
+        expect(limiter).to be_overloaded
+      end
+    end
+
+    context 'with same key, different limiters' do
+      let(:limiter_one) { described_class.new(:key, 1, :second) }
+      let(:limiter_two) { described_class.new(:key, 1, :second) }
+
+      it 'works as expected' do
+        expect(limiter_one.limit).not_to be_overloaded
+
+        expect(limiter_one).to be_overloaded
+        expect(limiter_two).to be_overloaded
+      end
+    end
+
+    context 'with different keys, different limiters' do
+      let(:limiter_one) { described_class.new(:one, 1, :second) }
+      let(:limiter_two) { described_class.new(:two, 2, :second) }
+
+      it 'works as expected' do
+        expect(limiter_one.limit).not_to be_overloaded
+        expect(limiter_two.limit).not_to be_overloaded
+
+        expect(limiter_one).to be_overloaded
+        expect(limiter_two.limit).not_to be_overloaded
+
+        expect(limiter_one).to be_overloaded
+        expect(limiter_two).to be_overloaded
+      end
     end
   end
 
-  context 'with different keys, different limiters' do
-    let(:limiter_one) { described_class.new(:one, 1, :second) }
-    let(:limiter_two) { described_class.new(:two, 2, :second) }
+  describe '#utilization' do
+    let(:limiter) { described_class.new(:key, 10, :minute) }
+
+    it do
+      expect(limiter.utilization).to be 0.0
+
+      2.times { limiter.limit }
+      expect(limiter.utilization).to be 0.2
 
-    it 'works as expected' do
-      expect(limiter_one.limit).not_to be_overrated
-      expect(limiter_two.limit).not_to be_overrated
+      8.times { limiter.limit }
+      expect(limiter.utilization).to be 1.0
 
-      expect(limiter_one).to be_overrated
-      expect(limiter_two.limit).not_to be_overrated
+      Timecop.freeze(30)
 
-      expect(limiter_one).to be_overrated
-      expect(limiter_two).to be_overrated
+      expect(limiter.utilization).to be 0.5
     end
   end
 
   describe '#to_s' do
-    def check(count, interval, expected)
+    def check(capacity, interval, expected)
       expect(
-        described_class.new(:key, count, interval).to_s
+        described_class.new(:key, capacity, interval).to_s
       ).to match(expected)
     end
 
@@ -171,16 +268,6 @@ describe Berater::RateLimiter do
       check(1, 'hour', /1 per hour/)
     end
 
-    it 'normalizes' do
-      check(1, :sec, /1 per second/)
-      check(1, :seconds, /1 per second/)
-
-      check(1, :min, /1 per minute/)
-      check(1, :minutes, /1 per minute/)
-
-      check(1, :hours, /1 per hour/)
-    end
-
     it 'works with integers' do
       check(1, 1, /1 every second/)
       check(1, 2, /1 every 2 seconds/)

data/spec/riddle_spec.rb

@@ -0,0 +1,106 @@
+# Can you build a rate limiter from a concurrency limiter?  Yes!
+
+class RateRiddler
+  def self.limit(capacity, interval)
+    lock = Berater::ConcurrencyLimiter.new(:key, capacity, timeout: interval).limit
+    yield if block_given?
+    # allow lock to time out rather than be released
+  end
+end
+
+
+describe 'a ConcurrencyLimiter-derived rate limiter' do
+  def limit(&block)
+    RateRiddler.limit(1, :second, &block)
+  end
+
+  it 'works' do
+    expect(limit { 123 }).to eq 123
+  end
+
+  it 'respects limits' do
+    limit
+    expect { limit }.to be_overloaded
+  end
+
+  it 'resets over time' do
+    limit
+    expect { limit }.to be_overloaded
+
+    Timecop.freeze(1)
+
+    limit
+    expect { limit }.to be_overloaded
+  end
+end
+
+
+# Can you build a concurrency limiter from a rate limiter?  Almost...
+
+class ConcurrenyRiddler
+  def self.limit(capacity, timeout: nil)
+    timeout ||= 1_000 # fake infinity
+
+    limiter = Berater::RateLimiter.new(:key, capacity, timeout)
+    lock = limiter.limit
+    yield if block_given?
+  ensure
+    # decrement counter
+    if lock
+      key = limiter.send(:cache_key, :key)
+      count, ts = limiter.redis.get(key).split ';'
+      limiter.redis.set(key, "#{count.to_f - 1};#{ts}")
+    end
+  end
+end
+
+
+describe 'a RateLimiter-derived concurrency limiter' do
+  def limit(capacity = 1, timeout: nil, &block)
+    ConcurrenyRiddler.limit(capacity, timeout: timeout, &block)
+  end
+
+  it 'works' do
+    expect(limit { 123 }).to eq 123
+  end
+
+  it 'respects limits' do
+    limit do
+      # a second, simultaneous request isn't allowed
+      expect { limit }.to be_overloaded
+    end
+
+    # but now it'll work
+    limit
+  end
+
+  it 'resets over time' do
+    limit(timeout: 1) do
+      expect { limit }.to be_overloaded
+
+      # ...wait for it
+      Timecop.freeze(10)
+
+      limit(timeout: 1)
+    end
+  end
+
+  it "has no memory of the order, so timeouts don't work quite right" do
+    limit(2, timeout: 1) do
+      Timecop.freeze(0.5)
+
+      limit(2, timeout: 1) do
+        # this is where the masquerading breaks.  the first lock is still
+        # being held and within it's timeout limit, however the RaterLimiter
+        # decremented the count internally since enough time has passed.
+        # This next call *should* fail, but doesn't.
+
+        expect {
+          expect { limit(2, timeout: 1) }.to be_overloaded
+        }.to fail
+
+        # ...close, but not quite!
+      end
+    end
+  end
+end