easyship 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c050cd7909443866f9f0365555f577024aa49ce0065be2a961018385409972d
-  data.tar.gz: a827b2cdaa8207b8723f5a7c2b65efba7c6b7f9e10cf16b46ea36f34aebae763
+  metadata.gz: 0e185adc98f576e3cf15ffc1ca38edf2dca8a0ffa580f68a731c900c3632392b
+  data.tar.gz: e15d52b3f530c58883fb8f50b086db537939ceed2fc1afff3579ea6aa82373c1
 SHA512:
-  metadata.gz: 959f2149e8e0d3f33ce0592de28df9718a0fb1c24cdb78909acffbdcecbeab71449b29a1000c03589d24616603214f0f9aa0dc05bad67e96ee413b2acad2a25c
-  data.tar.gz: 0ba62b8bf714db84417d4c2abb13e66738b0510dd0f57997c9403cdbfb81e2fa78029fb9b058d07a5ed943bb5eb8a9054be8929f6a7975b816fc59dda360b781
+  metadata.gz: 707860b193dbc25e916f8d0e5e68a2a3c8e34498e523871e243cf487f1e5c4c2469ed274099899b1b50c22598dc085906eca132f9e537515c43bf03428040c02
+  data.tar.gz: ec38670ff9d6626bc62485d8c836d00c1efb8e4a8218214c5c6b36b01570ad3b71906511c2459dc4a74b3a5ed91e3d3f91bd5f07586e75d481dc2ebf142a4d9a

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 ## [Unreleased]
 
-## [v.0.2.0](https://github.com/mmarusyk/easyship/tree/v0.2.0) - 2025-05-04
+## [v0.3.0](https://github.com/mmarusyk/easyship/tree/v0.3.0) - 2025-11-29
+
+### Added
+- Rate limiting for cursor by @mmarusyk in https://github.com/mmarusyk/easyship/pull/13
+
+
+## [v0.2.0](https://github.com/mmarusyk/easyship/tree/v0.2.0) - 2025-05-04
 
 ### Added
 - Add response_body and response_header to Easyship::Error

data/README.md

@@ -58,7 +58,7 @@ Easyship.configure do |config|
 end
 ```
 
-Configuration supports the next keys: `url`, `api_key`, `per_page`.
+Configuration supports the next keys: `url`, `api_key`, `per_page`, `requests_per_second`, `requests_per_minute`.
 
 ### Making Requests
 `Easyship::Client` supports the next methods: `get`, `post`, `put`, `delete`.
@@ -131,7 +131,48 @@ end
 shipments # Returns all shipments from all pages
 ```
 
-To setup items perpage, use the key `per_page` in your configuration.
+To setup items per page, use the key `per_page` in your configuration.
+
+For Example:
+
+```ruby
+# Global defaults
+Easyship.configure do |config|
+  config.per_page = 100
+end
+
+# Per-call overrides (any of these are supported)
+shipments = []
+Easyship::Client.instance.get('/2023-01/shipments', {
+  per_page: 50,
+}) do |page|
+  shipments.concat(page[:shipments])
+end
+```
+
+Rate limiting during pagination:
+- The cursor has no default rate limiting; it uses nil to indicate that rate limiting is disabled.
+  - Use [Rate limiting documentation](https://developers.easyship.com/reference/rate-limit) for more details which values to set.
+- You can override the limits per call, by passing `requests_per_second` and `requests_per_minute`.
+
+Examples:
+
+```ruby
+# Global defaults
+Easyship.configure do |config|
+  config.requests_per_second = 10
+  config.requests_per_minute = 60
+end
+
+# Per-call overrides (any of these are supported)
+shipments = []
+Easyship::Client.instance.get('/2023-01/shipments', {
+  requests_per_second: 5,
+  requests_per_minute: 40,
+}) do |page|
+  shipments.concat(page[:shipments])
+end
+```
 
 ## Development
 

data/lib/easyship/configuration.rb

@@ -3,12 +3,14 @@
 module Easyship
   # Represents the configuration settings for the Easyship client.
   class Configuration
-    attr_accessor :url, :api_key, :per_page
+    attr_accessor :url, :api_key, :per_page, :requests_per_second, :requests_per_minute
 
     def initialize
       @url = nil
       @api_key = nil
       @per_page = 100 # Maximum possible number of items per page
+      @requests_per_second = nil
+      @requests_per_minute = nil
     end
   end
 end

data/lib/easyship/pagination/cursor.rb

@@ -4,20 +4,26 @@ module Easyship
   module Pagination
     # Represents a pagination object
     class Cursor
-      attr_reader :client, :path, :params, :key, :per_page
+      CONFIGURATION_VARIABLES = %i[requests_per_second requests_per_minute].freeze
+
+      attr_reader :client, :path, :params, :key, :per_page, :requests_per_second, :requests_per_minute
 
       def initialize(client, path, params)
         @client = client
         @path = path
         @params = params
         @per_page = params[:per_page] || Easyship.configuration.per_page
+        @requests_per_second = params[:requests_per_second] || Easyship.configuration.requests_per_second
+        @requests_per_minute = params[:requests_per_minute] || Easyship.configuration.requests_per_minute
       end
 
       def all
         page = 1
 
         loop do
-          body = client.get(path, params.merge(page: page, per_page: per_page))
+          limiter.throttle!
+
+          body = client.get(path, build_request_params(page: page))
 
           break if body.nil? || body.empty?
 
@@ -28,6 +34,19 @@ module Easyship
           page += 1
         end
       end
+
+      private
+
+      def build_request_params(page:)
+        params.merge(page: page, per_page: per_page).except(*CONFIGURATION_VARIABLES)
+      end
+
+      def limiter
+        @limiter ||= Easyship::RateLimiting::WindowRateLimiter.new(
+          requests_per_second: requests_per_second,
+          requests_per_minute: requests_per_minute
+        )
+      end
     end
   end
 end

data/lib/easyship/rate_limiting/rate_limiter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Easyship
+  module RateLimiting
+    # Represents RateLimiter
+    class RateLimiter
+      def throttle!
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/easyship/rate_limiting/window_rate_limiter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Easyship
+  module RateLimiting
+    # Represents WindowRateLimiter
+    class WindowRateLimiter < RateLimiter
+      attr_reader :timestamps, :requests_per_second, :requests_per_minute
+
+      def initialize(requests_per_second:, requests_per_minute:)
+        super()
+        @requests_per_second = requests_per_second
+        @requests_per_minute = requests_per_minute
+        @timestamps = []
+      end
+
+      def throttle!
+        now = Time.now
+
+        timestamps << now
+
+        # Remove timestamps older than a minute
+        timestamps.reject! { |t| t < now - 60 }
+
+        check_second_window(now)
+        check_minute_window(now)
+      end
+
+      private
+
+      def check_second_window(now)
+        second_requests = timestamps.count { |t| t > now - 1 }
+
+        return if !requests_per_second || second_requests < requests_per_second
+
+        first_in_seconds = timestamps.find { |t| t > now - 1 }
+        sleep_time = (first_in_seconds + 1) - now
+
+        sleep(sleep_time) if sleep_time.positive?
+      end
+
+      def check_minute_window(now)
+        return if !requests_per_minute || timestamps.size < requests_per_minute
+
+        sleep_time = (timestamps.first + 60) - now
+
+        sleep(sleep_time) if sleep_time.positive?
+      end
+    end
+  end
+end

data/lib/easyship/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Easyship
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/easyship.rb

@@ -3,6 +3,8 @@
 require_relative 'easyship/version'
 require_relative 'easyship/configuration'
 require_relative 'easyship/client'
+require_relative 'easyship/rate_limiting/rate_limiter'
+require_relative 'easyship/rate_limiting/window_rate_limiter'
 
 # Provides configuration options for the Easyship gem.
 module Easyship

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easyship
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Marusyk
@@ -56,6 +56,8 @@ files:
 - lib/easyship/handlers/response_body_handler.rb
 - lib/easyship/middleware/error_handler_middleware.rb
 - lib/easyship/pagination/cursor.rb
+- lib/easyship/rate_limiting/rate_limiter.rb
+- lib/easyship/rate_limiting/window_rate_limiter.rb
 - lib/easyship/version.rb
 - sig/easyship.rbs
 homepage: https://rubygems.org/gems/easyship
@@ -81,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Ruby client for integrating with Easyship's API for shipping and logistics
   management.