simple_http_service 0.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a75ddb35b5f12bc409dfba441396f9341ee708894097afe93f1477095cf27cf
-  data.tar.gz: 4feb1170c683ff594d20f27c8b970e9a17b70ecb4dc088ce4b5cb84dd72cbd46
+  metadata.gz: 2bca219ad4f3a280dfea6a35fa241481c04414f2e85f553756e7a8612c8f81da
+  data.tar.gz: 647ce34790aaea4de53b84f852415d274b26cb51bd093173b8d2b5612381bf92
 SHA512:
-  metadata.gz: a80bacdcbaba0b520408918a547eb112c47cba2875a7bf4f64753d9f12287c3cb9bdb31de1890be53cc4d189c9db297dfcbdde93a929d7f6f1bf9f37ba184819
-  data.tar.gz: b8b1c7527e13face8f5f45e60ae16957585c5c3e87525618467d0c6912705b48b0406c42d2b4095a69a23d938e37682ce7fed5c446cc199c9336f97ee674a21d
+  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,38 +1,38 @@
 PATH
   remote: .
   specs:
-    simple_http_service (0.1.7)
-      net-http (~> 0.4.1)
+    simple_http_service (3.0.0)
+      net-http (>= 0.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.5.1)
-    net-http (0.4.1)
-      uri
-    rake (10.5.0)
-    rspec (3.13.0)
+    diff-lcs (1.6.2)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    rake (13.4.2)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.2)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.1)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.1)
-    uri (0.12.1)
-    yard (0.9.37)
+    rspec-support (3.13.7)
+    uri (1.1.1)
+    yard (0.9.44)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 2.5.10)
-  rake (~> 10.0)
+  bundler (~> 2.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.0"
+  VERSION = "3.0.0"
 end

data/simple_http_service.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'SimpleHttpService is a simple Ruby library to make HTTP requests with customizable options for headers, timeouts, and retries. It provides a convenient way to create and send HTTP requests using a clean and simple interface.'
   spec.homepage      = "https://github.com/gklsan/simple_http_service"
   spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.5"
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
@@ -38,8 +39,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "net-http", "~> 0.4.1"
-  spec.add_development_dependency "bundler", "~> 2.5.10"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_dependency "net-http", ">= 0.4"
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", ">= 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
 end

metadata

@@ -1,54 +1,54 @@
 --- !ruby/object:Gem::Specification
 name: simple_http_service
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Gokul (gklsan)
 bindir: exe
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.1
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.1
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.10
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.10
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
@@ -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
@@ -123,14 +124,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 4.0.11
 specification_version: 4
 summary: SimpleHttpService is a simple Ruby library to make HTTP requests with customizable
   options for headers, timeouts, and retries. It provides a convenient way to create