client-api-builder 0.7.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aac435317feb174db101e201b00464222bfc2df0f10601ac88e7897c3694be27
-  data.tar.gz: '08ad14efc0bff6c1f6e7fd4864e26c6f41853d72808fdc84b0e4781a0cfd229f'
+  metadata.gz: b12b7717adcfba57478c6ac76da774640924fa40dd67b9e570db305989de711b
+  data.tar.gz: 56ca42f80c9d6b0ae90cdfc131978421ef8cf7f1f80b9e0e96148fb0e23e95eb
 SHA512:
-  metadata.gz: e28726cc8c9670553371ba62a3c2ea4d30a4edb5db413936b91810ab1b592b2b84e6dd0fd3bcac8ad47fa2fb2c1b5d57a6c0443cace95210b9cf203a5e783d43
-  data.tar.gz: ed7628816de37ff4e8f4a27f67520f277abac439cb6183eca0c98ce5a072a1bd8c0413a3db5bda145d75208b4272c598b89514ad80f6692a6cb300c255330b64
+  metadata.gz: 1a4f218c711148e498517406e1893aac38cbba09a64062086b0986b4c187b87220ebce08dcba04d33472282f0998c8c299ac66fa89bd4021dfef6a2bda82b1d2
+  data.tar.gz: 8ba48b3d89d982669e7f7e3a9e2bc5951c96c9c2530b48cd95befd3fff22aed089be12cd04919ccfe43b43801139c65bdbb21364059cde7d55af888e18009d1b

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.9.0](https://github.com/dougyouch/client-api-builder/compare/v0.8.0...v0.9.0) (2026-10-04)
+
+
+### Features
+
+* add connection pools and exponential retry backoff ([e076162](https://github.com/dougyouch/client-api-builder/commit/e076162539aa9e92c1ec9bbdb5033de4cc163a14))
+* **connection-pools:** add opt-in persistent connection pools ([d172764](https://github.com/dougyouch/client-api-builder/commit/d17276410b007d15d577693677bd17f0a4be0a27))
+* **connection-pools:** add opt-in persistent connection pools ([df6fe98](https://github.com/dougyouch/client-api-builder/commit/df6fe9807ae9b0afb6b8f239ced15b6d5f984eea))
+* **connection-pools:** let sections configure their own connection pools ([b0e17e3](https://github.com/dougyouch/client-api-builder/commit/b0e17e34efaeaa731f854e2e58348c5ae87c7cfa))
+* **router:** add exponential backoff and jitter to retries ([59daf51](https://github.com/dougyouch/client-api-builder/commit/59daf51757f0b26d19064493cc499fc2cbef8954))
+
+## [0.8.0](https://github.com/dougyouch/client-api-builder/compare/v0.7.2...v0.8.0) (2026-10-03)
+
+
+### Features
+
+* **section:** let sections inherit root client headers, query params and connection options ([8849d98](https://github.com/dougyouch/client-api-builder/commit/8849d9875c86633639bf33c5e9b1eb486f67e921))
+
 ## [0.7.2](https://github.com/dougyouch/client-api-builder/compare/v0.7.1...v0.7.2) (2026-10-03)
 
 

data/README.md

@@ -15,6 +15,7 @@ A Ruby gem for building robust, secure API clients through declarative configura
 - **Flexible Request Building** - Support for JSON, query params, and custom body builders
 - **Nested Routing** - Organize complex APIs with hierarchical route structures
 - **Retry Logic** - Configurable automatic retries for transient network failures
+- **Connection Pooling** - Opt-in persistent connections shared across threads, with no extra gems
 - **Streaming Support** - Handle large payloads efficiently with streaming to files or IO
 - **ActiveSupport Integration** - Optional logging and instrumentation
 - **Comprehensive Error Handling** - Detailed error information for debugging
@@ -125,6 +126,9 @@ client.get_user(
   connection_options: { read_timeout: 5 },
   retries: 3,                           # attempts for this call
   sleep: 0.5,                           # seconds between attempts
+  backoff: 2,                           # multiply the sleep by this after each retry
+  max_sleep: 5,                         # cap on the sleep between attempts
+  jitter: true,                         # randomly shorten each sleep (true, false or 0..1)
   return: :body                         # :body or :response instead of parsed JSON
 )
 ```
@@ -296,9 +300,9 @@ class MyApiClient
     "Bearer #{auth_token}"
   end
 
-  section :users do
+  # Use the root client's headers (Authorization) beneath the section's own
+  section :users, inherit: :headers do
     base_url 'https://api.example.com/v2'  # Override base URL
-    header 'Authorization', :authorization
 
     route :list, '/users'
     route :get, '/users/:id'
@@ -306,7 +310,7 @@ class MyApiClient
   end
 
   section :posts do
-    header 'Authorization', :authorization
+    header 'Authorization', :authorization  # or declare what it needs itself
 
     route :list, '/posts'
     route :get, '/posts/:id'
@@ -322,7 +326,17 @@ user = client.users.get(id: 123)
 posts = client.posts.list
 ```
 
-A section is its own router class. It uses the parent's `base_url` unless it sets one, but headers, query params, connection options, retries and builders are not inherited, so declare the ones it needs inside the section. Symbol and block values given to `header` and `query_param`, `{name}` path values, and response blocks are evaluated on the root client, so they can use its methods and state.
+A section is its own router class. It uses the parent's `base_url` unless it sets one, but by default nothing else is inherited: declare the headers, query params and connection options it needs inside the section, or opt into the root client's with `inherit:`:
+
+```ruby
+section :users, inherit: %i[headers query_params connection_options] do
+  # or, inside the block: inherit_from_root :headers
+end
+```
+
+Inherited settings are the root client's class-level ones, read on every request (so ones declared after the section, or in a subclass of the client, apply too). The section's own settings override them, and per-request options override both; a per-request `nil` header still drops an inherited one. Retries and body/query builders are always the section's own. Any other options passed to `section` are available to it as `nested_router_options`.
+
+Symbol and block values given to `header` and `query_param`, `{name}` path values, and response blocks are evaluated on the root client, so they can use its methods and state.
 
 ### Connection Options
 
@@ -345,6 +359,46 @@ end
 
 Any `Net::HTTP.start` option can be set this way. Your options are applied over the secure HTTPS defaults, so setting `verify_mode` yourself replaces `VERIFY_PEER`.
 
+### Persistent Connections
+
+By default each request opens and closes its own connection. Include `ClientApiBuilder::ConnectionPools` (after `Router`) to keep connections open and reuse them:
+
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+  include ClientApiBuilder::ConnectionPools
+
+  base_url 'https://api.example.com'
+
+  # Optional; these are the defaults
+  connection_pool max_connections: 5,  # connections per host
+                  ttl: 30,             # seconds before a connection is closed and replaced
+                  checkout_timeout: 5, # seconds to wait for a free connection
+                  idle_timeout: 2      # seconds idle before Net::HTTP reconnects (keep_alive_timeout)
+end
+```
+
+The pools live on the class, like ActiveRecord's, so every instance shares them: keep one client instance per thread and the threads share the connections. A connection is checked out for one request (or one streamed response) and returned straight after, so `max_connections` can be lower than your thread count. There is one pool per scheme, host, port and connection options.
+
+- Sockets the server has closed, or that sat idle past `idle_timeout`, are reopened automatically.
+- A connection whose request raised is closed rather than reused.
+- When no connection frees up within `checkout_timeout`, the request raises `ClientApiBuilder::ConnectionPools::TimeoutError`.
+- Sections use their root client's pools, getting a separate pool for any other host in their `base_url`. Subclasses share their parent's pools unless they call `connection_pool` themselves.
+- A section can call `connection_pool` in its block to get its own pools and settings. This works whether or not the root client includes `ConnectionPools`:
+
+  ```ruby
+  section :uploads do
+    base_url 'https://uploads.example.com'
+    connection_pool max_connections: 2, ttl: 10
+  end
+  ```
+
+  Sections nested inside it still fall back to the root client, as they do for `base_url`.
+- After a fork (Puma, Sidekiq, Resque), the child process opens its own connections.
+- `MyApiClient.close_connections` closes idle connections now and in-use ones when they're returned, including the pools of sections that have their own.
+
+Pooling uses only `Net::HTTP` from the standard library.
+
 ### Retry Configuration
 
 Configure automatic retries for transient failures:
@@ -360,7 +414,28 @@ class MyApiClient
 end
 ```
 
-The first argument is the total number of attempts, not extra retries. The default is 1, so requests are not retried unless you configure it. `retries:` and `sleep:` can also be passed per request.
+The first argument is the total number of attempts, not extra retries. The default is 1, so requests are not retried unless you configure it.
+
+For exponential backoff, use `configure_exponential_retries`:
+
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+
+  # Up to 5 attempts, sleeping 0.1s, 0.2s, 0.4s, 0.8s between them (never more than 10s)
+  configure_exponential_retries attempts: 5, initial: 0.1, max: 10
+end
+```
+
+`initial` defaults to 0.1, `max` to 10 and the `multiplier` to 2. It is shorthand for `configure_retries 5, 0.1, backoff: 2, max_sleep: 10`: the sleep before retry n is `sleep * backoff**(n - 1)`, capped at `max_sleep`. `configure_retries` defaults to `backoff: 1` (a fixed sleep) and no cap.
+
+Add `jitter:` so many clients that fail together don't all retry at the same moment. `jitter: true` sleeps a random time between 0 and the computed sleep; a number between 0 and 1 shortens it by up to that fraction (`jitter: 0.5` sleeps between 50% and 100% of it):
+
+```ruby
+configure_exponential_retries attempts: 5, initial: 0.1, max: 10, jitter: true
+```
+
+`retries:`, `sleep:`, `backoff:`, `max_sleep:` and `jitter:` can also be passed per request.
 
 Only these network errors are retried by default:
 - `Net::OpenTimeout`, `Net::ReadTimeout`
@@ -608,7 +683,7 @@ Only safe file modes are allowed for streaming to files: `w`, `wb`, `a`, `ab`, `
 
 ## Thread Safety
 
-Client instances are **not thread-safe**. Create a separate client instance per thread:
+Client instances are **not thread-safe**. Create a separate client instance per thread. To share connections between those instances, see [Persistent Connections](#persistent-connections).
 
 ```ruby
 # Correct: Create a new client for each thread
@@ -641,9 +716,13 @@ end
 | `query_builder(builder)` | Configure query string serialization |
 | `query_param(name, value = nil, &block)` | Add a query parameter to all requests (value, method name symbol, or block) |
 | `connection_option(name, value)` | Set Net::HTTP connection options |
-| `configure_retries(max_attempts, sleep = 0.05)` | Configure retry behavior |
+| `configure_retries(max_attempts, sleep = 0.05, backoff: 1, max_sleep: nil, jitter: false)` | Configure retry behavior |
+| `configure_exponential_retries(attempts:, initial: 0.1, max: 10, multiplier: 2, jitter: false)` | Configure retries with exponential backoff |
+| `connection_pool(**settings)` | Configure persistent connection pools (requires `include ClientApiBuilder::ConnectionPools`) |
+| `close_connections` | Close the class's pooled connections and its sections' (with `ConnectionPools`) |
+| `section_routers` | Section router classes by name |
 | `route(name, path, options)` | Define an API endpoint |
-| `section(name, options, &block)` | Define nested routes |
+| `section(name, options, &block)` | Define nested routes; `inherit:` opts into the root client's `:headers`, `:query_params` and/or `:connection_options` |
 | `namespace(path, &block)` | Add path prefix to routes in block |
 
 ### Instance Methods
@@ -664,12 +743,13 @@ Define these in your client to change default behavior:
 | Method | Default |
 |--------|---------|
 | `retry_request?(exception, options)` | `true` for the network errors listed under Retry Configuration |
+| `with_http_connection(uri, connection_options, &block)` | Yields a started `Net::HTTP`: a new connection per request, or a pooled one with `ConnectionPools` |
 | `escape_path(value)` | Percent-encodes path values (`ERB::Util.url_encode`) |
 | `parse_response(response, options)` | Parses the body as JSON, `nil` when empty |
 | `handle_response(response, options, &block)` | Applies `return:`, parsing and the response block |
 | `expected_response_code!(response, codes, options)` | Raises `UnexpectedResponse` for unexpected codes |
 | `get_retry_request_max_retries(options)` | `retries:` option, then `configure_retries`, then 1 |
-| `get_retry_request_sleep_time(exception, options)` | `sleep:` option, then `configure_retries`, then 0.05 |
+| `get_retry_request_sleep_time(exception, options)` | `sleep:` option, then `configure_retries`, then 0.05; multiplied by `backoff**(attempt - 1)`, capped at `max_sleep`, then shortened by `jitter` |
 
 ## Requirements
 

data/lib/client-api-builder.rb

@@ -20,6 +20,7 @@ module ClientApiBuilder
 
   autoload :ActiveSupportNotifications, 'client_api_builder/active_support_notifications'
   autoload :ActiveSupportLogSubscriber, 'client_api_builder/active_support_log_subscriber'
+  autoload :ConnectionPools, 'client_api_builder/connection_pools'
   autoload :NestedRouter, 'client_api_builder/nested_router'
   autoload :QueryParams, 'client_api_builder/query_params'
   autoload :RouteValueValidator, 'client_api_builder/route_value_validator'

data/lib/client_api_builder/connection_pools/connection.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module ClientApiBuilder
+  module ConnectionPools
+    # A started Net::HTTP session and when it was opened and last used. Times come from the
+    # pool's monotonic clock. Net::HTTP reopens the socket itself if the server closed it or it
+    # sat idle past keep_alive_timeout.
+    class Connection
+      attr_reader :http, :opened_at, :last_used_at
+
+      def self.open(host, port, connection_options, now)
+        new(Net::HTTP.start(host, port, connection_options), now)
+      end
+
+      def initialize(http, now)
+        @http = http
+        @opened_at = now
+        @last_used_at = now
+      end
+
+      def used(now)
+        @last_used_at = now
+      end
+
+      def expired?(ttl, now)
+        now - opened_at >= ttl
+      end
+
+      def close
+        http.finish if http.started?
+      end
+    end
+  end
+end

data/lib/client_api_builder/connection_pools/pool.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module ConnectionPools
+    # Thread-safe pool of connections to one host, sharing one set of connection options.
+    # Connections are opened on demand up to max_connections and reused most recently used
+    # first. One that outlives the ttl is closed when it's next checked out or returned, and
+    # one whose request raised is closed rather than reused.
+    class Pool
+      MONOTONIC_CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+      attr_reader :host, :port, :settings
+
+      def initialize(host:, port:, connection_options:, settings:, clock: MONOTONIC_CLOCK)
+        @host = host
+        @port = port
+        @connection_options = connection_options
+        @settings = settings
+        @clock = clock
+        @mutex = Mutex.new
+        @available = ConditionVariable.new
+        @idle = []
+        @size = 0
+        @closed_at = nil
+      end
+
+      # Yields a connection's Net::HTTP session and returns the block's result
+      def with_connection
+        connection = checkout
+        returned = false
+        begin
+          result = yield connection.http
+          checkin(connection)
+          returned = true
+          result
+        ensure
+          discard(connection) unless returned
+        end
+      end
+
+      # Closes idle connections now; connections in use are closed when they're returned
+      def close
+        idle = @mutex.synchronize do
+          @closed_at = now
+          @size -= @idle.size
+          @available.broadcast
+          @idle.slice!(0..)
+        end
+        idle.each(&:close)
+      end
+
+      # Open connections, idle or in use
+      def size
+        @mutex.synchronize { @size }
+      end
+
+      def idle_size
+        @mutex.synchronize { @idle.size }
+      end
+
+      private
+
+      def now
+        @clock.call
+      end
+
+      def checkout
+        reuse_or_reserve(now + settings.checkout_timeout) || open_connection
+      end
+
+      # Returns an idle connection, or nil once a slot is reserved for a new one.
+      # Expired idle connections are closed after the lock is released.
+      def reuse_or_reserve(deadline)
+        expired = []
+        @mutex.synchronize do
+          loop do
+            connection = take_idle(expired)
+            return connection if connection
+            return nil if reserve_slot?
+
+            wait_for_connection(deadline)
+          end
+        end
+      ensure
+        expired.each(&:close)
+      end
+
+      def take_idle(expired)
+        while (connection = @idle.pop)
+          return connection unless retire?(connection)
+
+          @size -= 1
+          expired << connection
+        end
+      end
+
+      def reserve_slot?
+        return false if @size >= settings.max_connections
+
+        @size += 1
+        true
+      end
+
+      def wait_for_connection(deadline)
+        remaining = deadline - now
+        unless remaining.positive?
+          raise TimeoutError, "no connection to #{host}:#{port} became available within " \
+                              "#{settings.checkout_timeout}s (max_connections: #{settings.max_connections})"
+        end
+
+        @available.wait(@mutex, remaining)
+      end
+
+      def open_connection
+        connection = nil
+        connection = Connection.open(host, port, @connection_options, now)
+      ensure
+        release_slot unless connection
+      end
+
+      def checkin(connection)
+        connection.used(now)
+        retired = @mutex.synchronize do
+          retire = retire?(connection)
+          retire ? @size -= 1 : @idle.push(connection)
+          @available.signal
+          retire
+        end
+        connection.close if retired
+      end
+
+      def discard(connection)
+        release_slot
+        connection.close
+      end
+
+      def release_slot
+        @mutex.synchronize do
+          @size -= 1
+          @available.signal
+        end
+      end
+
+      def retire?(connection)
+        connection.expired?(settings.ttl, now) || closed_since_opened?(connection)
+      end
+
+      def closed_since_opened?(connection)
+        !@closed_at.nil? && connection.opened_at <= @closed_at
+      end
+    end
+  end
+end

data/lib/client_api_builder/connection_pools/pool_set.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module ConnectionPools
+    # A client class's pools: one per scheme, host, port and connection options, created on
+    # first use. After a fork the child starts with no pools; the parent's connections are
+    # dropped without being closed, since closing a shared TLS socket would disturb the parent.
+    class PoolSet
+      attr_reader :settings
+
+      def initialize(settings)
+        @settings = settings
+        reset
+      end
+
+      def with_connection(uri, connection_options, &)
+        pool_for(uri, connection_options).with_connection(&)
+      end
+
+      def pool_for(uri, connection_options)
+        reset if forked?
+        key = [uri.scheme, uri.hostname, uri.port, connection_options.dup.freeze].freeze
+        @mutex.synchronize { @pools[key] ||= build_pool(uri, connection_options) }
+      end
+
+      def pools
+        @mutex.synchronize { @pools.values }
+      end
+
+      def close
+        pools.each(&:close)
+      end
+
+      private
+
+      def reset
+        @pid = Process.pid
+        @mutex = Mutex.new
+        @pools = {}
+      end
+
+      def forked?
+        @pid != Process.pid
+      end
+
+      def build_pool(uri, connection_options)
+        Pool.new(host: uri.hostname, port: uri.port, settings: settings,
+                 connection_options: { keep_alive_timeout: settings.idle_timeout }.merge(connection_options))
+      end
+    end
+  end
+end

data/lib/client_api_builder/connection_pools/settings.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module ConnectionPools
+    # max_connections:  connections per host, in use or idle
+    # ttl:              seconds a connection may live before it's closed and replaced
+    # checkout_timeout: seconds a thread waits for a free connection before TimeoutError
+    # idle_timeout:     seconds a connection may sit unused before Net::HTTP reconnects it
+    #                   (Net::HTTP's keep_alive_timeout; a connection option overrides it)
+    Settings = Data.define(:max_connections, :ttl, :checkout_timeout, :idle_timeout) do
+      def initialize(max_connections: 5, ttl: 30, checkout_timeout: 5, idle_timeout: 2)
+        validate_max_connections!(max_connections)
+        { ttl: ttl, checkout_timeout: checkout_timeout, idle_timeout: idle_timeout }.each do |name, value|
+          validate_seconds!(name, value)
+        end
+        super
+      end
+
+      private
+
+      def validate_max_connections!(value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "max_connections must be a positive Integer, got #{value.inspect}"
+      end
+
+      def validate_seconds!(name, value)
+        return if value.is_a?(Numeric) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive number of seconds, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/client_api_builder/connection_pools.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Purpose: opt-in persistent HTTP connections shared by every instance of a client class.
+# Include after ClientApiBuilder::Router:
+#
+#   class MyClient
+#     include ClientApiBuilder::Router
+#     include ClientApiBuilder::ConnectionPools
+#
+#     connection_pool max_connections: 10, ttl: 60
+#   end
+#
+# Each thread uses its own client instance; the instances check connections out of the
+# class's pools (one pool per host and connection options) for the length of one request.
+module ClientApiBuilder
+  module ConnectionPools
+    autoload :Connection, 'client_api_builder/connection_pools/connection'
+    autoload :Pool, 'client_api_builder/connection_pools/pool'
+    autoload :PoolSet, 'client_api_builder/connection_pools/pool_set'
+    autoload :Settings, 'client_api_builder/connection_pools/settings'
+
+    # Raised when no connection frees up within checkout_timeout
+    class TimeoutError < ::ClientApiBuilder::Error; end
+
+    def self.included(base)
+      unless base.include?(::ClientApiBuilder::Router)
+        raise ArgumentError, 'include ClientApiBuilder::Router before ClientApiBuilder::ConnectionPools'
+      end
+
+      base.extend ClassMethods
+      base.connection_pool
+    end
+
+    module ClassMethods
+      # Configures this class's pools, replacing any it already had. Subclasses share their
+      # parent's pools unless they call connection_pool themselves.
+      def connection_pool(**settings)
+        redefine_class_method(:connection_pools, PoolSet.new(Settings.new(**settings)))
+      end
+
+      # Closes idle connections now and in-use ones when they are returned, including the
+      # pools of sections that have their own
+      def close_connections
+        connection_pools.close
+        section_routers.each_value(&:close_connections)
+      end
+    end
+
+    def with_http_connection(uri, connection_options, &)
+      self.class.connection_pools.with_connection(uri, connection_options, &)
+    end
+  end
+end

data/lib/client_api_builder/nested_router.rb

@@ -8,6 +8,9 @@ module ClientApiBuilder
   class NestedRouter
     include ::ClientApiBuilder::Router
 
+    # Root client settings a section can opt into with inherit: or inherit_from_root
+    INHERITABLE_SETTINGS = %i[headers query_params connection_options].freeze
+
     attr_reader :root_router,
                 :nested_router_options
 
@@ -20,6 +23,54 @@ module ClientApiBuilder
       "\#{escape_path(root_router.#{var})}"
     end
 
+    # The root client settings this section uses beneath its own; none by default
+    def self.inherited_root_settings
+      [].freeze
+    end
+
+    # Opts this section into the root client's class-level headers, query params and/or
+    # connection options. They are read per request and the section's own values take precedence.
+    def self.inherit_from_root(*settings)
+      settings = normalize_inherited_settings(settings)
+      redefine_class_method(:inherited_root_settings, (inherited_root_settings | settings).freeze)
+    end
+
+    def self.normalize_inherited_settings(settings)
+      settings = settings.flatten.map(&:to_sym)
+      unknown = settings - INHERITABLE_SETTINGS
+      return settings if unknown.empty?
+
+      raise ArgumentError, "Unknown inherit setting(s): #{unknown.map(&:inspect).join(', ')}. " \
+                           "Allowed: #{INHERITABLE_SETTINGS.map(&:inspect).join(', ')}"
+    end
+
+    # Gives this section its own connection pools (see ConnectionPools.connection_pool).
+    # Including ConnectionPools puts its connection_pool ahead of this one, so the call
+    # below configures the pools rather than recursing.
+    def self.connection_pool(**settings)
+      include ::ClientApiBuilder::ConnectionPools
+
+      connection_pool(**settings)
+    end
+
+    # Closes the pools of any nested sections that have their own; a section with its own
+    # pools uses ConnectionPools.close_connections, which closes those as well
+    def self.close_connections
+      section_routers.each_value(&:close_connections)
+    end
+
+    def configured_headers
+      inherits_from_root?(:headers) ? root_router.configured_headers.merge(super) : super
+    end
+
+    def configured_query_params
+      inherits_from_root?(:query_params) ? root_router.configured_query_params.merge(super) : super
+    end
+
+    def configured_connection_options
+      inherits_from_root?(:connection_options) ? root_router.configured_connection_options.merge(super) : super
+    end
+
     def base_url
       self.class.base_url || root_router.base_url
     end
@@ -27,5 +78,16 @@ module ClientApiBuilder
     def handle_response(response, options, &)
       root_router.handle_response(response, options, &)
     end
+
+    # Uses the root client's connections unless this section calls connection_pool
+    def with_http_connection(uri, connection_options, &)
+      root_router.with_http_connection(uri, connection_options, &)
+    end
+
+    private
+
+    def inherits_from_root?(setting)
+      self.class.inherited_root_settings.include?(setting)
+    end
   end
 end

data/lib/client_api_builder/net_http_request.rb

@@ -43,13 +43,19 @@ module ClientApiBuilder
         ssl_options = uri.scheme == 'https' ? DEFAULT_SECURE_OPTIONS.merge(use_ssl: true) : {}
         merged_options = ssl_options.merge(connection_options)
 
-        Net::HTTP.start(uri.hostname, uri.port, merged_options) do |http|
+        with_http_connection(uri, merged_options) do |http|
           http.request(request) do |response|
             yield response if block_given?
           end
         end
       end
 
+      # Yields a started Net::HTTP session for one request. By default each request opens
+      # and closes its own connection; ConnectionPools overrides this to reuse pooled ones.
+      def with_http_connection(uri, connection_options, &)
+        Net::HTTP.start(uri.hostname, uri.port, connection_options, &)
+      end
+
       # validate_response, when given, is called with the response before its body is streamed
       # and raises to reject it. A rejected body is read into response.body instead of being
       # streamed, so the error can still show it.

data/lib/client_api_builder/router.rb

@@ -60,7 +60,10 @@ module ClientApiBuilder
           query_params: {},
           response_procs: {},
           max_retries: 1,
-          sleep: 0.05
+          sleep: 0.05,
+          backoff: 1,
+          max_sleep: nil,
+          jitter: false
         }.freeze
       end
 
@@ -127,14 +130,27 @@ module ClientApiBuilder
         add_value_to_class_method(:default_options, connection_options: connection_options)
       end
 
-      def configure_retries(max_retries, sleep_time_between_retries_in_seconds = 0.05)
+      # max_retries is the total number of attempts. The sleep before retry n is
+      # sleep * backoff**(n - 1), capped at max_sleep when given. jitter randomly
+      # shortens each sleep: true by up to all of it, a number (0..1) by up to that fraction.
+      def configure_retries(max_retries, sleep_time_between_retries_in_seconds = 0.05,
+                            backoff: 1, max_sleep: nil, jitter: false)
         add_value_to_class_method(
           :default_options,
           max_retries: max_retries,
-          sleep: sleep_time_between_retries_in_seconds
+          sleep: sleep_time_between_retries_in_seconds,
+          backoff: backoff,
+          max_sleep: max_sleep,
+          jitter: jitter
         )
       end
 
+      # configure_retries with a sleep that starts at initial and doubles (by default)
+      # after each failed attempt, never exceeding max
+      def configure_exponential_retries(attempts:, initial: 0.1, max: 10, multiplier: 2, jitter: false)
+        configure_retries(attempts, initial, backoff: multiplier, max_sleep: max, jitter: jitter)
+      end
+
       # add a query param to all requests
       def query_param(name, value = nil, &block)
         query_params = deep_dup_hash(default_options[:query_params])
@@ -484,29 +500,41 @@ module ClientApiBuilder
     # Class-level headers may be method names or blocks; per-request headers are used as given.
     # Values are converted to strings, as Net::HTTP requires; nil values are left out of the request.
     def build_headers(options)
-      headers = self.class.default_headers.transform_values { |value| resolve_config_value(value) }
+      headers = configured_headers
       headers.merge!(options[:headers]) if options[:headers]
       headers.transform_values { |value| value&.to_s }
     end
 
+    # Class-level headers with symbols and blocks resolved; sections may add the root client's
+    def configured_headers
+      self.class.default_headers.transform_values { |value| resolve_config_value(value) }
+    end
+
     def build_connection_options(options)
-      if options[:connection_options]
-        self.class.default_connection_options.merge(options[:connection_options])
-      else
-        self.class.default_connection_options
-      end
+      connection_options = configured_connection_options
+      options[:connection_options] ? connection_options.merge(options[:connection_options]) : connection_options
+    end
+
+    # Class-level connection options; sections may add the root client's
+    def configured_connection_options
+      self.class.default_connection_options
     end
 
     # Class-level query params may be method names or blocks; values from route arguments
     # and per-request options are sent as given.
     def build_query(query, options)
-      query_params = self.class.default_query_params.transform_values { |value| resolve_config_value(value) }
+      query_params = configured_query_params
       query_params.merge!(query) if query
       query_params.merge!(options[:query]) if options[:query]
 
       query_params.empty? ? nil : self.class.build_query(self, query_params)
     end
 
+    # Class-level query params with symbols and blocks resolved; sections may add the root client's
+    def configured_query_params
+      self.class.default_query_params.transform_values { |value| resolve_config_value(value) }
+    end
+
     # Resolves a class-level header or query_param value: a Symbol calls that method and a
     # Proc is evaluated, both on the root router; anything else is used as is.
     def resolve_config_value(value)
@@ -623,7 +651,20 @@ module ClientApiBuilder
     end
 
     def get_retry_request_sleep_time(_exception, options)
-      options[:sleep] || self.class.default_options[:sleep] || 0.05
+      sleep_time = options[:sleep] || self.class.default_options[:sleep] || 0.05
+      backoff = options[:backoff] || self.class.default_options[:backoff] || 1
+      sleep_time *= backoff**(@request_attempts - 1)
+      max_sleep = options[:max_sleep] || self.class.default_options[:max_sleep]
+      sleep_time = [sleep_time, max_sleep].min if max_sleep
+      apply_retry_jitter(sleep_time, options.fetch(:jitter) { self.class.default_options[:jitter] })
+    end
+
+    # shortens sleep_time by a random amount: up to all of it for true, up to that fraction for a number
+    def apply_retry_jitter(sleep_time, jitter)
+      return sleep_time unless jitter
+
+      jitter = 1 if jitter == true
+      sleep_time * (1 - (jitter * rand))
     end
 
     def get_retry_request_max_retries(options)

data/lib/client_api_builder/section.rb

@@ -10,21 +10,33 @@ module ClientApiBuilder
     module ClassMethods
       SECTION_NAME = /\A[a-z_][a-z0-9_]*\z/i
 
+      # Section router classes by name, including inherited sections
+      def section_routers
+        {}.freeze
+      end
+
       # Defines <name>_router (the section's NestedRouter class) and <name> (its router for a
       # client instance) with closures, so anonymous client classes and any option values work.
-      def section(name, nested_router_options = {}, &)
+      # inherit: opts the section into root client settings (see NestedRouter.inherit_from_root);
+      # the remaining options are passed to the section as nested_router_options.
+      def section(name, nested_router_options = {}, &block)
         raise ArgumentError, "Invalid section name: #{name.inspect}" unless name.to_s.match?(SECTION_NAME)
 
+        nested_router_options = nested_router_options.dup
+        inherit = ::ClientApiBuilder::NestedRouter.normalize_inherited_settings(Array(nested_router_options.delete(:inherit)))
+
         kls = InheritanceHelper::ClassBuilder::Utils.create_class(
           self,
           name,
           ::ClientApiBuilder::NestedRouter,
           nil,
-          'NestedRouter',
-          &
+          'NestedRouter'
         )
+        kls.inherit_from_root(inherit)
+        kls.class_eval(&block) if block
 
         define_singleton_method(:"#{name}_router") { kls }
+        add_value_to_class_method(:section_routers, name.to_sym => kls)
         define_section_accessor(name, nested_router_options)
       end
 

data/lib/client_api_builder/version.rb

@@ -2,5 +2,5 @@
 
 module ClientApiBuilder
   # Gem version, bumped by release-please
-  VERSION = '0.7.2'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: client-api-builder
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Doug Youch
@@ -40,6 +40,11 @@ files:
 - lib/client-api-builder.rb
 - lib/client_api_builder/active_support_log_subscriber.rb
 - lib/client_api_builder/active_support_notifications.rb
+- lib/client_api_builder/connection_pools.rb
+- lib/client_api_builder/connection_pools/connection.rb
+- lib/client_api_builder/connection_pools/pool.rb
+- lib/client_api_builder/connection_pools/pool_set.rb
+- lib/client_api_builder/connection_pools/settings.rb
 - lib/client_api_builder/nested_router.rb
 - lib/client_api_builder/net_http_request.rb
 - lib/client_api_builder/query_params.rb