simple_http_service 0.2.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b48b86c315bf9ac3de107f1cd64d90b8675388691f29a4a11e73e1c544d25085
-  data.tar.gz: 9ced494e26dc8db12a0067e035d8934c5950321eaa41639da6ae37b6f1baec05
+  metadata.gz: 2bca219ad4f3a280dfea6a35fa241481c04414f2e85f553756e7a8612c8f81da
+  data.tar.gz: 647ce34790aaea4de53b84f852415d274b26cb51bd093173b8d2b5612381bf92
 SHA512:
-  metadata.gz: 13a4f3559c1325a6e6c2a8b6ee81664a6a074ceed6de198473c138071982052800bcdf2ed7110bfaf4d58ccdc5a06541feeb4458bac94880a8285328349f580b
-  data.tar.gz: 4d915ad4546c9fcb7e9734c5820ccc4e9afb9322cbf1a50b89351e83eb7e968c8bef14308ed19f5dd9104904f6b2be8dce3bf712ab74303978643f194c03c44d
+  metadata.gz: 0c2dd8b1ea07c4a43612df855b64595447e219ffa950c3340c8fa271e4ac72323e7ccc507db62f6f4266924e2f8d194dff109075ebb6432dfbb2a02622266819
+  data.tar.gz: dfeea32e3a2db839a96165cd9b18da540d014d7a7115a3afb0ccc23f4272c87fdd0b901c71cae80c910a8b9bb49fbe94f3f569d1b19935c75b87701cf3dc7611

data/.gitignore

@@ -9,4 +9,12 @@
 # rspec failure tracking
 .rspec_status
 
-.idea
+.idea
+
+# CCE (code-context-engine)
+# CCE local cache (per-machine, not for version control)
+.cce/
+# Claude Code local settings written by cce init
+.claude/settings.local.json
+# .mcp.json contains absolute paths regenerated by `cce init`
+.mcp.json

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    simple_http_service (0.2.0)
+    simple_http_service (3.0.0)
       net-http (>= 0.4)
 
 GEM
@@ -32,7 +32,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 2.0)
-  rake (~> 13.0)
+  rake (>= 10.0)
   rspec (~> 3.13.0)
   rspec-core (~> 3.13.1)
   simple_http_service!

data/README.md

@@ -45,6 +45,10 @@ client = SimpleHttpService.new(
   max_retries: 3,
   additional_headers: {
     'X-Request-Id': '12345'
+  },
+  rate_limit: {
+    limit: 2,
+    interval: 60
   }
 )
 ```
@@ -65,6 +69,50 @@ puts response.body
 - `max_retries`: The number of times to retry the request in case of failure.
 - `request_body`: The body of the request (used for POST and PUT requests).
 - `additional_headers`: Additional headers to include in the request.
+- `rate_limit`: A hash enabling client side throttling. Omit it and no limiting is applied.
+  - `limit` (required to enable): Maximum number of requests allowed per window.
+  - `interval`: Length of the window in seconds (default is `60`).
+  - `wait`: When `true`, `call` sleeps until a slot frees up instead of raising (default is `false`).
+  - `key`: Bucket the window under a custom key (default is `scheme://host:port`).
+
+### Rate Limiting
+Rate limiting is opt in. Pass a `rate_limit` hash to cap how often the client fires requests:
+
+```ruby
+client = SimpleHttpService.new(
+  url: 'https://api.example.com/endpoint',
+  http_method: :get,
+  rate_limit: { limit: 2, interval: 60 }
+)
+
+2.times { client.call }
+client.call # raises SimpleHttpService::RateLimitExceeded
+```
+
+The window is a sliding one, shared across every client in the process that resolves to the same
+key, so two clients pointing at the same host draw from the same budget. Use `key` to share (or
+separate) buckets explicitly.
+
+To block instead of raising when the budget is used up:
+
+```ruby
+client = SimpleHttpService.new(
+  url: 'https://api.example.com/endpoint',
+  http_method: :get,
+  rate_limit: { limit: 2, interval: 60, wait: true }
+)
+```
+
+`SimpleHttpService::RateLimitExceeded` inherits from `SimpleHttpService::Error` and exposes
+`retry_after`, the number of seconds until the next slot opens:
+
+```ruby
+begin
+  client.call
+rescue SimpleHttpService::RateLimitExceeded => e
+  puts "Throttled, retry in #{e.retry_after.ceil}s"
+end
+```
 
 ### Example
 Here's a complete example of using `SimpleHttpService` to make a `GET` request:

data/lib/simple_http_service/client.rb

@@ -1,8 +1,10 @@
 require 'net/http'
+require 'simple_http_service/rate_limiter'
+
 module SimpleHttpService
   class Client
     attr_accessor :uri, :headers, :http_method, :open_timeout, :read_timeout, :write_timeout,
-                  :max_retries, :request_body, :additional_headers
+                  :max_retries, :request_body, :additional_headers, :rate_limit
 
     def initialize(opts)
       raise 'URL must be present' unless opts[:url]
@@ -17,9 +19,11 @@ module SimpleHttpService
       @write_timeout = opts[:write_timeout]
       @max_retries = opts[:max_retries] || 1
       @additional_headers = opts[:additional_headers] || {}
+      @rate_limit = opts[:rate_limit] || {}
     end
 
     def call
+      throttle
       enable_ssl
       set_headers
       set_timeout
@@ -27,8 +31,23 @@ module SimpleHttpService
       http.request(request)
     end
 
+    # Limiter backing this client, or nil unless rate_limit[:limit] was passed in.
+    def rate_limiter
+      return unless rate_limit[:limit]
+
+      @rate_limiter ||= RateLimiter.for(
+        rate_limit[:key] || "#{uri.scheme}://#{uri.host}:#{uri.port}",
+        limit: rate_limit[:limit],
+        interval: rate_limit[:interval] || RateLimiter::DEFAULT_INTERVAL
+      )
+    end
+
     private
 
+    def throttle
+      rate_limiter&.acquire(wait: rate_limit[:wait] || false)
+    end
+
     def set_headers
       request["Accept"] = headers[:accept] if headers[:accept]
       request["Authorization"] = headers[:authorization] if headers[:authorization]

data/lib/simple_http_service/rate_limiter.rb

@@ -0,0 +1,107 @@
+module SimpleHttpService
+  class Error < StandardError; end
+
+  # Raised when a request would exceed the configured rate limit and
+  # the client is not configured to wait for a free slot.
+  class RateLimitExceeded < Error
+    attr_reader :retry_after
+
+    def initialize(msg, retry_after: nil)
+      @retry_after = retry_after
+      super(msg)
+    end
+  end
+
+  # Sliding-window rate limiter, shared per key across all Client instances
+  # in the process. Thread safe.
+  class RateLimiter
+    DEFAULT_INTERVAL = 60
+
+    attr_reader :limit, :interval
+
+    class << self
+      # Returns the limiter registered for +key+, creating it on first use.
+      def for(key, limit:, interval: DEFAULT_INTERVAL)
+        registry_mutex.synchronize do
+          registry[key] ||= new(limit: limit, interval: interval)
+        end
+      end
+
+      # Drops every registered limiter. Mainly useful in tests.
+      def reset!
+        registry_mutex.synchronize { registry.clear }
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+
+      def registry_mutex
+        @registry_mutex ||= Mutex.new
+      end
+    end
+
+    def initialize(limit:, interval: DEFAULT_INTERVAL)
+      raise 'rate limit must be a positive integer' unless limit.to_i.positive?
+      raise 'rate limit interval must be positive' unless interval.to_f.positive?
+
+      @limit = limit.to_i
+      @interval = interval.to_f
+      @timestamps = []
+      @mutex = Mutex.new
+    end
+
+    # Consumes one slot. Raises RateLimitExceeded when the window is full,
+    # unless +wait+ is true, in which case it sleeps until a slot frees up.
+    def acquire(wait: false)
+      loop do
+        retry_after = try_acquire
+        return true unless retry_after
+
+        unless wait
+          raise RateLimitExceeded.new(
+            "rate limit of #{limit} request(s) per #{interval.round} seconds exceeded, " \
+            "retry in #{retry_after.ceil} second(s)",
+            retry_after: retry_after
+          )
+        end
+
+        sleep(retry_after)
+      end
+    end
+
+    # Slots still available in the current window.
+    def remaining
+      @mutex.synchronize do
+        prune
+        limit - @timestamps.size
+      end
+    end
+
+    private
+
+    # Returns nil when a slot was taken, otherwise seconds until the next one.
+    def try_acquire
+      @mutex.synchronize do
+        prune
+        if @timestamps.size < limit
+          @timestamps << now
+          return nil
+        end
+
+        [@timestamps.first + interval - now, 0.001].max
+      end
+    end
+
+    def prune
+      cutoff = now - interval
+      @timestamps.shift while @timestamps.first && @timestamps.first <= cutoff
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/simple_http_service/version.rb

@@ -1,3 +1,3 @@
 module SimpleHttpService
-  VERSION = "0.2.1"
+  VERSION = "3.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_http_service
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Gokul (gklsan)
@@ -105,6 +105,7 @@ files:
 - doc/top-level-namespace.html
 - lib/simple_http_service.rb
 - lib/simple_http_service/client.rb
+- lib/simple_http_service/rate_limiter.rb
 - lib/simple_http_service/version.rb
 - simple_http_service.gemspec
 homepage: https://github.com/gklsan/simple_http_service