tiny_rl 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31e146834dcf046d74daa459ecf49be6a1a3f640443c807a8177fda51f8d5b8e
-  data.tar.gz: 1874d4946e1b4733e32b0e56e0d5ba54e69f5ec4e4613cc3bb3ffb268a6a591d
+  metadata.gz: 2ff77bc53d01edfc80ddab66a55e6cca3333bb943199b8e707796fb950423bed
+  data.tar.gz: 0cee04760a9250243b7bcb715d437d958fa8d9ff0deb8d5df169d5972c05c695
 SHA512:
-  metadata.gz: 101faf881ca40f0c18163e9c9be50750393258eb1b5f77d5ab125d597a752b61aa828492073f14c66dc07d1a51c91f1877aecefec779ae72b503b5aad5b23f15
-  data.tar.gz: 90839e1152797de61e32bbe97d356bee46d3bc0a2c947ee1c8ea459a91128d8efc642d5b54d3cb29e3441185087c7ed1223da71875d388ccb68f11c9de396a43
+  metadata.gz: 37640f7aeaa30e0f65f082a50501d6a6b6f1f538f2c20424e18d5c6eeeb4ebab33a1414aaa743272dd4363c59b8ce3774c37f01e9cdd2adf9596719305fc84d2
+  data.tar.gz: f52bad20a8ec1c15438d8c66a649ab4d6b1faa522d4f3b853d4228e09206d36267f3cf1d88b91d8fdb353b5a513d5cc67c7a77aab0fc67fac2f2c9739e63a27f

data/lib/tiny_rl.rb

@@ -1,2 +1,115 @@
-require_relative 'tiny_rl/job'
-require_relative 'tiny_rl/exec'
+require 'time'
+
+# this class simply tracks a rate limit, the timestamps of things you want to
+# limit, and allows you the check both the used capacity and whether or not the
+# rate limit has been reached. there's some additional tracking of the total
+# number of jobs, dropped jobs, and errored jobs, just for some simple
+# accounting.
+#
+# Usage:
+#    > rl = TinyRl.new(5, TinyRl::MINUTE, :drop)
+#   => <a rate limiter that will drop method calls over a rate of 5 per minute>
+#    > 10.times{ rl.track }
+#    > rl.used_capacity
+#   => 5
+#    > rl.at_capacity?
+#   => true
+#
+# if you use the :error strategy, then an instance of
+# TinyRl::ExceededRateLimitError will be raised when you exceed the rate limit
+# when calling #track.
+#
+# if you'd like to check the capacity of the TinyRl before taking some action,
+# then check either TinyRl#at_capacity? or TinyRl#used_capacity as appropriate.
+class TinyRl
+  STRATEGIES = %i(drop error)
+
+  SECOND  = 1
+  MINUTE  = SECOND * 60
+  HOUR    = MINUTE * 60
+  DAY     = HOUR * 24
+  WEEK    = DAY * 7
+  MONTH   = DAY * 30
+  YEAR    = DAY * 365
+
+  # rate: number of requests per unit time
+  # per: unit of time (one of SECOND, MINUTE, etc.)
+  #   you can pass any integer in as the `per' parameter and it will be
+  #   interpreted as a number of seconds
+  # strategy: what to do when you're over the rate limit
+  #   drop: drop the request, never perform the method call
+  #   error: raise an exception when rate exceeded
+  def initialize(limit, per, strategy)
+    raise TinyRlInvalidStrategyError.new("Strategy `#{strategy.inspect}' is not one of the allowed strategies") unless STRATEGIES.include?(strategy)
+    @total_jobs = 0
+    @dropped_jobs = 0
+    @errored_jobs = 0
+    @limit = limit
+    @per = per
+    @strategy = strategy
+
+    @job_call_times = []
+  end
+
+  # this method will track the timestamp of something that you want to rate
+  # limit. this is generic so that you cand rate limit a bunch of things
+  # collectively with a single TinyRl instance.
+  #
+  # for strategy :drop
+  #   returns true if the job was run, false if it was dropped
+  # for strategy :error
+  #   returns true if the job was run, raises an exception otherwise
+  def track
+    @total_jobs += 1
+
+    if at_capacity?
+      case @strategy
+      when :drop
+        @dropped_jobs += 1
+      when :error
+        @errored_jobs += 1
+        raise TinyRlExceededRateLimitError.new("Rate limit of #{@limit} per #{@per} sec exceeded")
+      end
+      false
+    else
+      @job_call_times << Time.now
+      true
+    end
+  end
+
+  # returns true if the rate limit has currently been reached, false otherwise
+  def at_capacity?
+    _clear_old_jobs
+    @job_call_times.length == @limit
+  end
+
+  # useful for monitoring by consuming programs, and for issuing warnings when
+  # you're close, but not over, your limit
+  def used_capacity
+    _clear_old_jobs
+    @job_call_times.length
+  end
+
+  # removes old jobs before. used before checking capacity
+  def _clear_old_jobs
+    loop do
+      break if (@job_call_times.length == 0) || (@job_call_times.first >= (Time.now - @per))
+      @job_call_times.shift
+    end
+  end
+
+  # for debugging, really
+  def to_s
+    <<~TO_S
+             limit: #{@limit} per #{@per} seconds
+      at_capacity?: #{at_capacity?}
+     used_capacity: #{used_capacity}
+        total_jobs: #{@total_jobs}
+      dropped_jobs: #{@dropped_jobs}
+      errored_jobs: #{@errored_jobs}
+    TO_S
+  end
+end
+
+class TinyRlExceededRateLimitError < RuntimeError; end
+class TinyRlInvalidStrategyError < RuntimeError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tiny_rl
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jeff Lunt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-25 00:00:00.000000000 Z
+date: 2022-12-23 00:00:00.000000000 Z
 dependencies: []
 description: a tiny rate limiter with almost no features
 email: jefflunt@gmail.com