berater 0.5.0 → 0.7.1

data/spec/dsl_refinement_spec.rb

@@ -3,18 +3,6 @@ require 'berater/dsl'
 describe Berater do
   using Berater::DSL
 
-  it 'instatiates an Unlimiter' do
-    limiter = Berater.new(:key) { unlimited }
-    expect(limiter).to be_a Berater::Unlimiter
-    expect(limiter.key).to be :key
-  end
-
-  it 'instatiates an Inhibiter' do
-    limiter = Berater.new(:key) { inhibited }
-    expect(limiter).to be_a Berater::Inhibitor
-    expect(limiter.key).to be :key
-  end
-
   it 'instatiates a RateLimiter' do
     limiter = Berater.new(:key) { 1.per second }
     expect(limiter).to be_a Berater::RateLimiter

data/spec/dsl_spec.rb

@@ -13,13 +13,13 @@ describe Berater::DSL do
     end
 
     it 'parses' do
-      check([ 1, :second ]) { 1.per second }
-      check([ 3, :minute ]) { 3.per minute }
-      check([ 5, :hour ]) { 5.every hour }
+      check([ 1, interval: :second ]) { 1.per second }
+      check([ 3, interval: :minute ]) { 3.per minute }
+      check([ 5, interval: :hour ]) { 5.every hour }
     end
 
     it 'cleans up afterward' do
-      check([ 1, :second ]) { 1.per second }
+      check([ 1, interval: :second ]) { 1.per second }
 
       expect(Integer).not_to respond_to(:per)
       expect(Integer).not_to respond_to(:every)
@@ -29,7 +29,7 @@ describe Berater::DSL do
       count = 1
       interval = :second
 
-      check([ count, interval ]) { count.per interval }
+      check([ count, interval: interval ]) { count.per interval }
     end
   end
 
@@ -57,16 +57,4 @@ describe Berater::DSL do
     end
   end
 
-  context 'unlimited mode' do
-    it 'has keywords' do
-      check(:unlimited) { unlimited }
-    end
-  end
-
-  context 'inhibited mode' do
-    it 'has keywords' do
-      check(:inhibited) { inhibited }
-    end
-  end
-
 end

data/spec/limiter_spec.rb

@@ -1,6 +1,6 @@
 describe Berater::Limiter do
   it 'can not be initialized' do
-    expect { described_class.new }.to raise_error(NotImplementedError)
+    expect { described_class.new }.to raise_error(NoMethodError)
   end
 
   describe 'abstract methods' do
@@ -8,11 +8,47 @@ describe Berater::Limiter do
 
     it do
       expect { limiter.limit }.to raise_error(NotImplementedError)
-      expect { limiter.overloaded? }.to raise_error(NotImplementedError)
+      expect { limiter.utilization }.to raise_error(NotImplementedError)
     end
   end
 
-  describe '==' do
+  describe '#limit' do
+    subject { Berater::Unlimiter.new }
+
+    context 'with a capacity parameter' do
+      it 'overrides the stored value' do
+        is_expected.to receive(:acquire_lock).with(3, anything)
+
+        subject.limit(capacity: 3)
+      end
+
+      it 'validates the type' do
+        expect {
+          subject.limit(capacity: 'abc')
+        }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'with a cost parameter' do
+      it 'overrides the stored value' do
+        is_expected.to receive(:acquire_lock).with(anything, 2)
+
+        subject.limit(cost: 2)
+      end
+
+      it 'validates' do
+        expect {
+          subject.limit(cost: 'abc')
+        }.to raise_error(ArgumentError)
+
+        expect {
+          subject.limit(cost: -1)
+        }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe '#==' do
     let(:limiter)  { Berater::RateLimiter.new(:key, 1, :second) }
 
     it 'equals itself' do

data/spec/matchers_spec.rb

@@ -1,130 +1,122 @@
-describe 'be_overloaded' do
+describe Berater::Matchers::Overloaded do
+
   context 'Berater::Unlimiter' do
-    let(:limiter) { Berater.new(:key, :unlimited) }
+    let(:limiter) { Berater::Unlimiter.new }
 
     it { expect(limiter).not_to be_overloaded }
-    it { expect(limiter).not_to be_inhibited }
-    it { expect(limiter).not_to be_overrated }
-    it { expect(limiter).not_to be_incapacitated }
-
     it { expect { limiter }.not_to be_overloaded }
-    it { expect { limiter }.not_to be_inhibited }
-    it { expect { limiter }.not_to be_overrated }
-    it { expect { limiter }.not_to be_incapacitated }
-
     it { expect { limiter.limit }.not_to be_overloaded }
-    it { expect { limiter.limit }.not_to be_inhibited }
-    it { expect { limiter.limit }.not_to be_overrated }
-    it { expect { limiter.limit }.not_to be_incapacitated }
-
-    it 'catches false positives' do
-      expect {
-        expect { limiter }.to be_overloaded
-      }.to fail
-    end
   end
 
   context 'Berater::Inhibitor' do
-    let(:limiter) { Berater.new(:key, :inhibited) }
+    let(:limiter) { Berater::Inhibitor.new }
 
     it { expect(limiter).to be_overloaded }
-    it { expect(limiter).to be_inhibited }
-
     it { expect { limiter }.to be_overloaded }
-    it { expect { limiter }.to be_inhibited }
-
     it { expect { limiter.limit }.to be_overloaded }
-    it { expect { limiter.limit }.to be_inhibited }
-
-    it 'catches false negatives' do
-      expect {
-        expect { limiter }.not_to be_overloaded
-      }.to fail
-    end
   end
 
   context 'Berater::RateLimiter' do
-    let(:limiter) { Berater.new(:key, 1, :second) }
+    let(:limiter) { Berater::RateLimiter.new(:key, 1, :second) }
 
     it { expect(limiter).not_to be_overloaded }
-    it { expect(limiter).not_to be_inhibited }
-    it { expect(limiter).not_to be_overrated }
-    it { expect(limiter).not_to be_incapacitated }
-
     it { expect { limiter }.not_to be_overloaded }
-    it { expect { limiter }.not_to be_inhibited }
-    it { expect { limiter }.not_to be_overrated }
-    it { expect { limiter }.not_to be_incapacitated }
-
     it { expect { limiter.limit }.not_to be_overloaded }
-    it { expect { limiter.limit }.not_to be_inhibited }
-    it { expect { limiter.limit }.not_to be_overrated }
-    it { expect { limiter.limit }.not_to be_incapacitated }
 
     context 'once limit is used up' do
       before { limiter.limit }
 
-      it 'should be_overrated' do
-        expect(limiter).to be_overrated
+      it 'should be_overloaded' do
+        expect(limiter).to be_overloaded
       end
 
-      it 'should be_overrated' do
-        expect { limiter }.to be_overrated
+      it 'should be_overloaded' do
+        expect { limiter }.to be_overloaded
       end
 
-      it 'should be_overrated' do
-        expect { limiter.limit }.to be_overrated
+      it 'should be_overloaded' do
+        expect { limiter.limit }.to be_overloaded
       end
     end
   end
 
   context 'Berater::ConcurrencyLimiter' do
-    let(:limiter) { Berater.new(:key, 1) }
+    let(:limiter) { Berater::ConcurrencyLimiter.new(:key, 1) }
 
     it { expect(limiter).not_to be_overloaded }
-    it { expect(limiter).not_to be_inhibited }
-    it { expect(limiter).not_to be_overrated }
-    it { expect(limiter).not_to be_incapacitated }
-
     it { expect { limiter }.not_to be_overloaded }
-    it { expect { limiter }.not_to be_inhibited }
-    it { expect { limiter }.not_to be_overrated }
-    it { expect { limiter }.not_to be_incapacitated }
-
     it { expect { limiter.limit }.not_to be_overloaded }
-    it { expect { limiter.limit }.not_to be_inhibited }
-    it { expect { limiter.limit }.not_to be_overrated }
-    it { expect { limiter.limit }.not_to be_incapacitated }
 
     context 'when lock is released' do
-      it 'should be_incapacitated' do
+      it 'should be_overloaded' do
         3.times do
-          expect(limiter).not_to be_incapacitated
+          expect(limiter).not_to be_overloaded
         end
       end
 
-      it 'should be_incapacitated' do
+      it 'should be_overloaded' do
         3.times do
-          expect { limiter }.not_to be_incapacitated
+          expect { limiter }.not_to be_overloaded
         end
       end
 
-      it 'should be_incapacitated' do
+      it 'should be_overloaded' do
         3.times do
-          expect { limiter.limit {} }.not_to be_incapacitated
+          expect { limiter.limit {} }.not_to be_overloaded
         end
       end
     end
 
     context 'when lock is *not* released' do
-      it 'should be_incapacitated' do
-        expect { limiter.limit }.not_to be_incapacitated
-        expect { limiter.limit }.to be_incapacitated
+      it 'should be_overloaded' do
+        expect { limiter.limit }.not_to be_overloaded
+        expect { limiter.limit }.to be_overloaded
       end
 
-      it 'should be_incapacitated' do
-        expect { 3.times { limiter.limit } }.to be_incapacitated
+      it 'should be_overloaded' do
+        expect { 3.times { limiter.limit } }.to be_overloaded
       end
     end
   end
+
+  context 'when matchers fail' do
+    let(:unlimiter) { Berater::Unlimiter.new }
+    let(:inhibitor) { Berater::Inhibitor.new }
+
+    it 'catches false negatives' do
+      expect {
+        expect(unlimiter).to be_overloaded
+      }.to fail_including('expected to be overloaded')
+
+      expect {
+        expect { unlimiter }.to be_overloaded
+      }.to fail_including('expected to be overloaded')
+
+      expect {
+        expect { unlimiter.limit }.to be_overloaded
+      }.to fail_including("expected #{Berater::Overloaded} to be raised")
+
+      expect {
+        expect { 123 }.to be_overloaded
+      }.to fail_including("expected #{Berater::Overloaded} to be raised")
+    end
+
+    it 'catches false positives' do
+      expect {
+        expect(inhibitor).not_to be_overloaded
+      }.to fail_including('expected not to be overloaded')
+
+      expect {
+        expect { inhibitor }.not_to be_overloaded
+      }.to fail_including('expected not to be overloaded')
+
+      expect {
+        expect { inhibitor.limit }.not_to be_overloaded
+      }.to fail_including("did not expect #{Berater::Overloaded} to be raised")
+
+      expect {
+        expect { raise Berater::Overloaded }.not_to be_overloaded
+      }.to fail_including("did not expect #{Berater::Overloaded} to be raised")
+    end
+  end
 end

data/spec/rate_limiter_spec.rb

@@ -1,5 +1,6 @@
 describe Berater::RateLimiter do
-  it_behaves_like 'a limiter', Berater.new(:key, 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) }
@@ -23,6 +24,7 @@ describe Berater::RateLimiter do
 
     it { expect_capacity(0) }
     it { expect_capacity(1) }
+    it { expect_capacity(1.5) }
     it { expect_capacity(100) }
 
     context 'with erroneous values' do
@@ -32,7 +34,6 @@ describe Berater::RateLimiter do
         end.to raise_error ArgumentError
       end
 
-      it { expect_bad_capacity(0.5) }
       it { expect_bad_capacity(-1) }
       it { expect_bad_capacity('1') }
       it { expect_bad_capacity(:one) }
@@ -44,9 +45,19 @@ describe Berater::RateLimiter do
 
     subject { described_class.new(:key, 1, :second) }
 
-    it 'saves the interval in original and microsecond format' do
+    it 'saves the interval in original and millisecond format' do
       expect(subject.interval).to be :second
-      expect(subject.instance_variable_get(:@interval_usec)).to be 10**6
+      expect(subject.instance_variable_get(:@interval_msec)).to be 10**3
+    end
+
+    it 'must be > 0' do
+      expect {
+        described_class.new(:key, 1, 0)
+      }.to raise_error(ArgumentError)
+
+      expect {
+        described_class.new(:key, 1, -1)
+      }.to raise_error(ArgumentError)
     end
   end
 
@@ -65,56 +76,129 @@ 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, with millisecond precision' do
+    it 'resets limit over time' do
       3.times { limiter.limit }
-      expect(limiter).to be_overrated
-
-      # travel forward to just before the count decrements
-      Timecop.freeze(0.333)
-      expect(limiter).to be_overrated
-
-      # traveling one more millisecond will decrement the count
-      Timecop.freeze(0.001)
-      limiter.limit
-      expect(limiter).to be_overrated
+      expect(limiter).to be_overloaded
 
-      # traveling 1 second will reset the count
       Timecop.freeze(1)
 
       3.times { limiter.limit }
-      expect(limiter).to be_overrated
+      expect(limiter).to be_overloaded
+    end
+
+    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
+
+        2.times { limiter.limit }
+      end
+    end
+
+    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_overrated
+      expect { limiter.limit(capacity: 0) }.to be_overloaded
       5.times { limiter.limit(capacity: 10) }
-      expect { limiter }.to be_overrated
+      expect { limiter }.to be_overloaded
     end
 
     context 'works with cost parameter' do
-      it { expect { limiter.limit(cost: 4) }.to be_overrated }
+      it { expect { limiter.limit(cost: 4) }.to be_overloaded }
 
       it 'works within limit' do
         limiter.limit(cost: 3)
-        expect { limiter.limit }.to be_overrated
+        expect { limiter.limit }.to be_overloaded
       end
 
       it 'resets over time' do
         limiter.limit(cost: 3)
-        expect(limiter).to be_overrated
+        expect(limiter).to be_overloaded
 
         Timecop.freeze(1)
-        expect(limiter).not_to be_overrated
+        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 'can be a Float' do
-        2.times { limiter.limit(cost: 1.5) }
-        expect(limiter).to be_overrated
+      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
 
@@ -123,10 +207,10 @@ describe Berater::RateLimiter do
       let(:limiter_two) { described_class.new(:key, 1, :second) }
 
       it 'works as expected' do
-        expect(limiter_one.limit).not_to be_overrated
+        expect(limiter_one.limit).not_to be_overloaded
 
-        expect(limiter_one).to be_overrated
-        expect(limiter_two).to be_overrated
+        expect(limiter_one).to be_overloaded
+        expect(limiter_two).to be_overloaded
       end
     end
 
@@ -135,27 +219,33 @@ describe Berater::RateLimiter do
       let(:limiter_two) { described_class.new(:two, 2, :second) }
 
       it 'works as expected' do
-        expect(limiter_one.limit).not_to be_overrated
-        expect(limiter_two.limit).not_to be_overrated
+        expect(limiter_one.limit).not_to be_overloaded
+        expect(limiter_two.limit).not_to be_overloaded
 
-        expect(limiter_one).to be_overrated
-        expect(limiter_two.limit).not_to be_overrated
+        expect(limiter_one).to be_overloaded
+        expect(limiter_two.limit).not_to be_overloaded
 
-        expect(limiter_one).to be_overrated
-        expect(limiter_two).to be_overrated
+        expect(limiter_one).to be_overloaded
+        expect(limiter_two).to be_overloaded
       end
     end
   end
 
-  describe '#overloaded?' do
-    let(:limiter) { described_class.new(:key, 1, :second) }
+  describe '#utilization' do
+    let(:limiter) { described_class.new(:key, 10, :minute) }
 
-    it 'works' do
-      expect(limiter.overloaded?).to be false
-      limiter.limit
-      expect(limiter.overloaded?).to be true
-      Timecop.freeze(1)
-      expect(limiter.overloaded?).to be false
+    it do
+      expect(limiter.utilization).to be 0.0
+
+      2.times { limiter.limit }
+      expect(limiter.utilization).to be 0.2
+
+      8.times { limiter.limit }
+      expect(limiter.utilization).to be 1.0
+
+      Timecop.freeze(30)
+
+      expect(limiter.utilization).to be 0.5
     end
   end