fulfil_api 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b08b66a980bb816b1424c5bdf4b6f07bdc652a0dc0838715b6176dd8dd3a52ac
-  data.tar.gz: e659a978bd939c89aafc27bab91d36c3af9daad8c2779f8e87ff7f9dc8203766
+  metadata.gz: c2dd30142d140730335b3f184bc28c0fd897af19246a8794ec5d416b1a335b2a
+  data.tar.gz: b81436ad499dfdd14ea84f5651d4670395907ad8090ab4e9eed432c6195da86c
 SHA512:
-  metadata.gz: 1da9f24a29088c2a177717731176b75ba29fcd9db6281ea7834ec2627e76b3b9029fb7f006ab428caba8035e68c39e221f77cf903145058820a2ebbb93e73552
-  data.tar.gz: de48831aca1ac5ebc8aed263e61ccd0bdb25728240504dbf43c6a91c298f253e8d566141a29c7cab7c67b2d8366704b0f1d4b40f436dd9ea005c582df5f4086e
+  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

@@ -5,6 +5,36 @@ require "faraday/net_http_persistent"
 
 module FulfilApi
   class Client
+    @connection_cache = {}
+    @connection_cache_mutex = Mutex.new
+
+    class << self
+      # Looks up a memoized {Faraday::Connection} for the given cache key, or
+      #   builds and stores one by yielding the block.
+      #
+      # The cache is process-wide, so the underlying `net_http_persistent` adapter
+      #   can actually reuse its TCP/TLS connection pool across requests. Without
+      #   this, each `FulfilApi.client` call would instantiate a fresh Faraday
+      #   connection, defeating the purpose of the persistent adapter.
+      #
+      # @param cache_key [Array] A key uniquely identifying the connection.
+      # @yieldreturn [Faraday::Connection] The newly built connection.
+      # @return [Faraday::Connection]
+      def connection_for(cache_key)
+        @connection_cache_mutex.synchronize do
+          @connection_cache[cache_key] ||= yield
+        end
+      end
+
+      # Clears the memoized connection cache. Intended for use in test suites
+      #   that need to isolate connection state between tests.
+      #
+      # @return [void]
+      def reset_connection_cache!
+        @connection_cache_mutex.synchronize { @connection_cache.clear }
+      end
+    end
+
     # @param configuration [FulfilApi::Configuration]
     def initialize(configuration)
       @configuration = configuration
@@ -56,14 +86,32 @@ module FulfilApi
       @api_endpoint ||= "https://#{configuration.merchant_id}.fulfil.io"
     end
 
+    # Returns a {Faraday::Connection} for the current configuration, reusing the
+    #   memoized connection from the class-level cache whenever possible.
+    #
     # @return [Faraday::Connection]
     def connection
-      @connection ||= Faraday.new(
-        headers: request_headers,
-        url: api_endpoint,
-        request: configuration.request_options
-      ) do |connection|
-        connection.adapter :net_http_persistent # TODO: Allow passing configuration options
+      self.class.connection_for(connection_cache_key) { build_connection }
+    end
+
+    # Builds a fresh {Faraday::Connection} for the current configuration.
+    #
+    # The connection carries no credentials — authentication headers are applied
+    #   per-request in {#request}. This keeps tokens out of any long-lived data
+    #   structure (cache keys, the connection's default headers) and lets a single
+    #   connection be shared across configurations that target the same merchant
+    #   with different access tokens.
+    #
+    # No `Content-Type` header is set on the connection. The `:json` request
+    #   middleware adds it on requests that actually have a body, so bodyless
+    #   verbs (GET, DELETE) are not sent with a misleading content type.
+    #
+    # @return [Faraday::Connection]
+    def build_connection
+      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
@@ -74,6 +122,42 @@ 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.connection_options]
+    end
+
     # @param relative_path [String] The relative path to the API endpoint.
     # @return [String] The absolute path for the request to the API endpoint.
     def expand_relative_path(relative_path)
@@ -98,17 +182,26 @@ module FulfilApi
     # @param relative_path [String] The relative path to the API endpoint.
     # @return [Array, Hash, String] The parsed response body.
     def request(method, relative_path, *args, **kwargs)
-      connection.send(method.to_sym, expand_relative_path(relative_path), *args, **kwargs).body
+      response = connection.send(method.to_sym, expand_relative_path(relative_path), *args, **kwargs) do |req|
+        apply_authentication(req)
+      end
+
+      response.body
     rescue Faraday::Error => e
       handle_request_error(e)
     end
 
-    # @return [Hash] The HTTP headers for any HTTP request to Fulfil.
-    def request_headers
-      default_headers = { "Content-Type" => "application/json" }
-      return default_headers if configuration.access_token.nil?
+    # Applies the configured access token to the request as an HTTP header.
+    #
+    # Authentication is set per-request rather than on the shared {#connection},
+    #   so the connection cache does not need to know about credentials.
+    #
+    # @param request [Faraday::Request] The request being prepared.
+    # @return [void]
+    def apply_authentication(request)
+      return if configuration.access_token.nil?
 
-      default_headers.merge(**configuration.access_token.to_http_header)
+      configuration.access_token.to_http_header.each { |name, value| request.headers[name] = value }
     end
   end
 

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/error.rb

@@ -15,7 +15,21 @@ module FulfilApi
 
     # @return [String]
     def message
+      body_message = parsed_body_message
+      return "[FulfilApi::Error] #{body_message}" if body_message
+
       "[FulfilApi::Error] #{super}"
     end
+
+    private
+
+    def parsed_body_message
+      body = details&.dig(:response_body)
+      return unless body
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
   end
 end

data/lib/fulfil_api/tpl_client.rb

@@ -16,6 +16,36 @@ module FulfilApi
 
     DEFAULT_API_VERSION = "v1"
 
+    @connection_cache = {}
+    @connection_cache_mutex = Mutex.new
+
+    class << self
+      # Looks up a memoized {Faraday::Connection} for the given cache key, or
+      #   builds and stores one by yielding the block.
+      #
+      # The cache is process-wide, so the underlying `net_http_persistent` adapter
+      #   can actually reuse its TCP/TLS connection pool across requests. Without
+      #   this, each `FulfilApi.tpl_client` call would instantiate a fresh Faraday
+      #   connection, defeating the purpose of the persistent adapter.
+      #
+      # @param cache_key [Array] A key uniquely identifying the connection.
+      # @yieldreturn [Faraday::Connection] The newly built connection.
+      # @return [Faraday::Connection]
+      def connection_for(cache_key)
+        @connection_cache_mutex.synchronize do
+          @connection_cache[cache_key] ||= yield
+        end
+      end
+
+      # Clears the memoized connection cache. Intended for use in test suites
+      #   that need to isolate connection state between tests.
+      #
+      # @return [void]
+      def reset_connection_cache!
+        @connection_cache_mutex.synchronize { @connection_cache.clear }
+      end
+    end
+
     # @param configuration [FulfilApi::Configuration]
     def initialize(configuration)
       @configuration = configuration
@@ -77,14 +107,26 @@ module FulfilApi
       @api_endpoint ||= "https://#{merchant_id}.fulfil.io"
     end
 
+    # Returns a {Faraday::Connection} for the current configuration, reusing the
+    #   memoized connection from the class-level cache whenever possible.
+    #
     # @return [Faraday::Connection]
     def connection
-      @connection ||= Faraday.new(
-        headers: request_headers,
-        url: api_endpoint,
-        request: configuration.request_options
-      ) do |connection|
-        connection.adapter :net_http_persistent
+      self.class.connection_for(connection_cache_key) { build_connection }
+    end
+
+    # Builds a fresh {Faraday::Connection} for the current configuration.
+    #
+    # The connection carries no credentials — the bearer token is applied
+    #   per-request in {#request}, keeping it out of long-lived data structures
+    #   such as cache keys or default connection headers.
+    #
+    # @return [Faraday::Connection]
+    def build_connection
+      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
@@ -95,6 +137,42 @@ 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, configuration.connection_options]
+    end
+
     # @param relative_path [String] The relative path to the API endpoint.
     # @return [String] The absolute path for the request to the API endpoint.
     def expand_relative_path(relative_path)
@@ -119,16 +197,24 @@ module FulfilApi
     # @param relative_path [String] The relative path to the API endpoint.
     # @return [Array, Hash, String] The parsed response body.
     def request(method, relative_path, *args, **kwargs)
-      connection.send(method.to_sym, expand_relative_path(relative_path), *args, **kwargs).body
+      response = connection.send(method.to_sym, expand_relative_path(relative_path), *args, **kwargs) do |req|
+        apply_authentication(req)
+      end
+
+      response.body
     rescue Faraday::Error => e
       handle_request_error(e)
     end
 
-    # @return [Hash] The HTTP headers for any HTTP request to the 3PL API.
-    def request_headers
-      {
-        "Authorization" => "Bearer #{auth_token}"
-      }
+    # Applies the configured bearer token to the request as an HTTP header.
+    #
+    # Authentication is set per-request rather than on the shared {#connection},
+    #   so the connection cache does not need to know about credentials.
+    #
+    # @param request [Faraday::Request] The request being prepared.
+    # @return [void]
+    def apply_authentication(request)
+      request.headers["Authorization"] = "Bearer #{auth_token}"
     end
   end
 

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.6.2"
+  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.2
+  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.3
+rubygems_version: 3.5.11
+signing_key:
 specification_version: 4
 summary: A HTTP client to interact the Fulfil.io API
 test_files: []