fulfil_api 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5088d4a6e17bfc91b7dbdbd841db0d649bbc7fc16e295fb63a1cf8d4e80436a
-  data.tar.gz: 30f89d00763dde2c6d2b1573ded61440097b87904dae062c7f8ee147de9621e0
+  metadata.gz: c2dd30142d140730335b3f184bc28c0fd897af19246a8794ec5d416b1a335b2a
+  data.tar.gz: b81436ad499dfdd14ea84f5651d4670395907ad8090ab4e9eed432c6195da86c
 SHA512:
-  metadata.gz: 35aa477f5a29a3597d7567bcb8f6708fb89cb13d20c0f848cb06dd46f381bbff94dbddb36bf6fb95d9e544f01c7e94989f44ab872e1ed891f5ea254dfa358727
-  data.tar.gz: de45ced7efb091fc5cfcce224310afab14b233f97197887d94137f2c31007b43b363db424a1478108a8469e1813eeb980a71febe0d4c55f6b6e63d101a57c35b
+  metadata.gz: 6dee8c45eea430b8f6e7bfa82b03c3d737dd424cdda363c74680f4acedc9e896c28cfc3bc746e35d33035a863ffed9f995877b267a59e0afae0f2e67f7047d20
+  data.tar.gz: 5873899ac0f65bb6a9e1ecbd74aebd1f45806cee1faed5716c1649e158d83396de15139a93da9347b8b20ba080172c7e2cfa59aca36b6f89a89a4a57207e3167

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+- Re-enable Ruby's built-in retry for idempotent requests on the persistent connection, which the `net_http_persistent` adapter disables by forcing `max_retries` to `0`. This recovers stale keep-alive sockets transparently instead of surfacing them as read timeouts.
+- Add a `connection_options` configuration option to tune the persistent connection (`max_retries`, `idle_timeout`, `pool_size`).
+- `FulfilApi.with_config` now merges the temporary options over the active configuration instead of replacing it, so a block inherits credentials and other unspecified settings rather than resetting them to their defaults.
+
 ## [0.1.0] - 2024-08-10
 
 - Initial release

data/README.md

@@ -41,6 +41,8 @@ end
 
 #### Using a Dynamic Configuration
 
+`with_config` temporarily applies options **on top of the currently active configuration** (per thread) and reverts when the block returns. The options you pass are merged over the active config, so you only need to specify what changes — credentials and other settings are inherited rather than reset to their defaults.
+
 ```ruby
 FulfilApi.with_config(
   access_token: FulfilApi::AccessToken.new(ENV["FULFIL_API_KEY"]),
@@ -50,6 +52,17 @@ FulfilApi.with_config(
 end
 ```
 
+This makes it easy to use different settings in contexts with different constraints. For example, a web request bound by a 30s timeout can keep tight defaults globally, while a background job (which has more time) overrides just the timeouts and retries without re-passing credentials:
+
+```ruby
+FulfilApi.with_config(
+  request_options: { open_timeout: 5, read_timeout: 60, write_timeout: 30 },
+  connection_options: { max_retries: 3, idle_timeout: 10 }
+) do
+  # Long-running work against the Fulfil API
+end
+```
+
 #### Available Configuration Options
 
 The following configuration options are (currently) available throught both configuration methods:
@@ -60,7 +73,16 @@ The following configuration options are (currently) available throught both conf
 
 - `merchant_id` (`String`): The `merchant_id` is the subdomain that the Fulfil instance is hosted on. This configuration option is required to be able to query Fulfil's API endpoints.
 
-- `request_options` (`Hash`): The `request_options` are the configuration options for the HTTP client. See [https://lostisland.github.io/faraday/#/customization/request-options](https://lostisland.github.io/faraday/#/customization/request-options) in `faraday`.
+- `request_options` (`Hash`): The `request_options` are the per-request timeout options for the HTTP client. See [https://lostisland.github.io/faraday/#/customization/request-options](https://lostisland.github.io/faraday/#/customization/request-options) in `faraday`.
+
+> **NOTE:** With the persistent (keep-alive) adapter there is no single whole-request `timeout`; Faraday resolves `read_timeout`, `open_timeout`, and `write_timeout` independently. `read_timeout` is the value that governs a slow or stalled response.
+
+- `connection_options` (`Hash`): Tuning for the persistent (keep-alive) connection. Supported keys:
+  - `max_retries` (default `1`): Re-enables Ruby's built-in retry for **idempotent** requests (`GET`/`HEAD`/`PUT`/`DELETE`/`OPTIONS`). The `net_http_persistent` adapter disables this by forcing it to `0`, which makes a keep-alive socket the server has already dropped surface as a read timeout instead of being retried transparently on a fresh socket. `POST` is never auto-retried, so this is side-effect safe. Set to `0` to restore the adapter's default behaviour.
+  - `idle_timeout` (`Integer`, optional): Seconds a pooled socket may sit idle before it is recycled. Lower this towards your server's keep-alive window to shrink the stale-socket window for non-idempotent requests.
+  - `pool_size` (`Integer`, optional): Maximum number of concurrent connections kept in the pool.
+
+> **NOTE:** When retries are enabled, the worst-case time for a request is roughly `(max_retries + 1) × read_timeout`. On platforms with a hard request cap (e.g. Heroku's 30s router limit), keep `read_timeout` low enough that this product stays under the cap.
 
 ### Querying the Fulfil API
 

data/lib/fulfil_api/client.rb

@@ -109,7 +109,9 @@ module FulfilApi
     # @return [Faraday::Connection]
     def build_connection
       Faraday.new(url: api_endpoint, request: configuration.request_options) do |connection|
-        connection.adapter :net_http_persistent # TODO: Allow passing configuration options
+        connection.adapter(:net_http_persistent, **adapter_options) do |http|
+          configure_persistent_connection(http)
+        end
 
         # Configuration of the request middleware
         connection.request :json
@@ -120,9 +122,40 @@ module FulfilApi
       end
     end
 
+    # Initialization options for the persistent adapter. Only `pool_size` is
+    #   accepted here; `idle_timeout` and `max_retries` are applied to the live
+    #   Net::HTTP::Persistent instance in {#configure_persistent_connection}.
+    #
+    # @return [Hash]
+    def adapter_options
+      options = {}
+      options[:pool_size] = configuration.connection_options[:pool_size] if configuration.connection_options[:pool_size]
+      options
+    end
+
+    # Tunes the underlying Net::HTTP::Persistent connection.
+    #
+    # The `net_http_persistent` adapter forces `max_retries` to 0 on every
+    #   request, which disables Ruby's built-in retry for idempotent requests.
+    #   Restoring it lets a stale keep-alive socket — one the server has already
+    #   closed — be retried transparently on a fresh socket instead of surfacing
+    #   as a read timeout. The config block runs after the adapter zeroes the
+    #   value, so this takes effect.
+    #
+    # @param http [Net::HTTP::Persistent] The live persistent connection.
+    # @return [void]
+    def configure_persistent_connection(http)
+      if configuration.connection_options[:idle_timeout]
+        http.idle_timeout = configuration.connection_options[:idle_timeout]
+      end
+      return if configuration.connection_options[:max_retries].nil?
+
+      http.max_retries = configuration.connection_options[:max_retries]
+    end
+
     # @return [Array] The cache key identifying a unique connection.
     def connection_cache_key
-      [configuration.merchant_id, configuration.request_options]
+      [configuration.merchant_id, configuration.request_options, configuration.connection_options]
     end
 
     # @param relative_path [String] The relative path to the API endpoint.

data/lib/fulfil_api/configuration.rb

@@ -7,10 +7,23 @@ module FulfilApi
   #   to these settings.
   class Configuration
     attr_accessor :access_token, :api_version, :merchant_id, :request_options, :tpl
+    attr_reader :connection_options
 
     DEFAULT_API_VERSION = "v2"
     DEFAULT_REQUEST_OPTIONS = { open_timeout: 1, read_timeout: 5, write_timeout: 5, timeout: 5 }.freeze
 
+    # Tuning for the persistent (keep-alive) HTTP connection.
+    #
+    # `max_retries` re-enables Ruby's built-in retry for idempotent requests
+    #   (GET/HEAD/PUT/DELETE/OPTIONS). The `net_http_persistent` adapter forces
+    #   it to 0, which means a keep-alive socket the server has already dropped
+    #   surfaces as a read timeout instead of being transparently retried on a
+    #   fresh socket. POST is never auto-retried, so this is side-effect safe.
+    #
+    # `idle_timeout` and `pool_size` are passed through to the underlying
+    #   Net::HTTP::Persistent connection when set.
+    DEFAULT_CONNECTION_OPTIONS = { max_retries: 1 }.freeze
+
     # Initializes the configuration with optional settings.
     #
     # @param options [Hash, nil] An optional list of configuration options.
@@ -25,6 +38,16 @@ module FulfilApi
       set_default_options
     end
 
+    # Merges the provided connection options over the defaults so that, for
+    #   example, setting only `idle_timeout` still keeps the default
+    #   `max_retries`. Assigning `nil` resets to the defaults.
+    #
+    # @param options [Hash, nil] The connection options to apply.
+    # @return [void]
+    def connection_options=(options)
+      @connection_options = DEFAULT_CONNECTION_OPTIONS.merge(options || {})
+    end
+
     private
 
     # Sets the default options for the gem configuration.
@@ -36,6 +59,7 @@ module FulfilApi
     def set_default_options
       self.api_version = DEFAULT_API_VERSION if api_version.nil?
       self.request_options = DEFAULT_REQUEST_OPTIONS if request_options.nil?
+      self.connection_options = nil if connection_options.nil?
     end
   end
 
@@ -75,15 +99,23 @@ module FulfilApi
       end
   end
 
-  # Temporarily applies the provided configuration options within a block,
-  #   and then reverts to the original configuration after the block executes.
+  # Temporarily applies the provided configuration options on top of the
+  #   currently active configuration, and then reverts after the block executes.
+  #
+  # The temporary options are merged over a copy of the active configuration, so
+  #   a block only needs to specify what it overrides — credentials and other
+  #   settings (`access_token`, `merchant_id`, ...) are inherited rather than
+  #   reset to their defaults.
   #
   # @param temporary_options [Hash] A hash of temporary configuration options.
   # @yield Executes the block with the temporary configuration.
   # @return [void]
   def self.with_config(temporary_options)
-    original_configuration = configuration.dup
-    self.configuration = temporary_options
+    original_configuration = configuration
+
+    self.configuration = original_configuration.dup.tap do |config|
+      temporary_options.each { |key, value| config.public_send(:"#{key}=", value) }
+    end
 
     yield
   ensure

data/lib/fulfil_api/tpl_client.rb

@@ -123,11 +123,10 @@ module FulfilApi
     #
     # @return [Faraday::Connection]
     def build_connection
-      Faraday.new(
-        url: api_endpoint,
-        request: configuration.request_options
-      ) do |connection|
-        connection.adapter :net_http_persistent
+      Faraday.new(url: api_endpoint, request: configuration.request_options) do |connection|
+        connection.adapter(:net_http_persistent, **adapter_options) do |http|
+          configure_persistent_connection(http)
+        end
 
         # Configuration of the request middleware
         connection.request :json
@@ -138,9 +137,40 @@ module FulfilApi
       end
     end
 
+    # Initialization options for the persistent adapter. Only `pool_size` is
+    #   accepted here; `idle_timeout` and `max_retries` are applied to the live
+    #   Net::HTTP::Persistent instance in {#configure_persistent_connection}.
+    #
+    # @return [Hash]
+    def adapter_options
+      options = {}
+      options[:pool_size] = configuration.connection_options[:pool_size] if configuration.connection_options[:pool_size]
+      options
+    end
+
+    # Tunes the underlying Net::HTTP::Persistent connection.
+    #
+    # The `net_http_persistent` adapter forces `max_retries` to 0 on every
+    #   request, which disables Ruby's built-in retry for idempotent requests.
+    #   Restoring it lets a stale keep-alive socket — one the server has already
+    #   closed — be retried transparently on a fresh socket instead of surfacing
+    #   as a read timeout. The config block runs after the adapter zeroes the
+    #   value, so this takes effect.
+    #
+    # @param http [Net::HTTP::Persistent] The live persistent connection.
+    # @return [void]
+    def configure_persistent_connection(http)
+      if configuration.connection_options[:idle_timeout]
+        http.idle_timeout = configuration.connection_options[:idle_timeout]
+      end
+      return if configuration.connection_options[:max_retries].nil?
+
+      http.max_retries = configuration.connection_options[:max_retries]
+    end
+
     # @return [Array] The cache key identifying a unique connection.
     def connection_cache_key
-      [merchant_id, api_version, configuration.request_options]
+      [merchant_id, api_version, configuration.request_options, configuration.connection_options]
     end
 
     # @param relative_path [String] The relative path to the API endpoint.

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.6.3"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Stefan Vermaas
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -111,6 +112,7 @@ metadata:
   source_code_uri: https://www.github.com/codeturebv/fulfil_api
   changelog_uri: https://www.github.com/codeturebv/fulfil_api/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -125,7 +127,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.5.11
+signing_key:
 specification_version: 4
 summary: A HTTP client to interact the Fulfil.io API
 test_files: []