client-api-builder 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e2d55d531b568e6f1cb0bb718ee236ca44eac7951c133ca6f2d294460968a80
-  data.tar.gz: d617dc3983f1cde402095e2be735c804f9a657969007a1f601779fe90f01c110
+  metadata.gz: b12b7717adcfba57478c6ac76da774640924fa40dd67b9e570db305989de711b
+  data.tar.gz: 56ca42f80c9d6b0ae90cdfc131978421ef8cf7f1f80b9e0e96148fb0e23e95eb
 SHA512:
-  metadata.gz: 288273782ec2072f360e56b3653a80510684fd05772560db6544b438cc558c56a58d8de179cf87636a80dc396789aed431c63aee4681e90ad9bbc11325b294ba
-  data.tar.gz: 5a8622d04ae326e393c1b104a79ff8ed30f1f22420b6b3a7f4b1f30aa39b4e29e7929b625d8ff665276dd6ad45e2ee96e327afceb082b9a6c1d7eb227dde2229
+  metadata.gz: 1a4f218c711148e498517406e1893aac38cbba09a64062086b0986b4c187b87220ebce08dcba04d33472282f0998c8c299ac66fa89bd4021dfef6a2bda82b1d2
+  data.tar.gz: 8ba48b3d89d982669e7f7e3a9e2bc5951c96c9c2530b48cd95befd3fff22aed089be12cd04919ccfe43b43801139c65bdbb21364059cde7d55af888e18009d1b

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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)
 
 

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
 )
 ```
@@ -355,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:
@@ -370,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`
@@ -618,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
@@ -651,7 +716,11 @@ 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; `inherit:` opts into the root client's `:headers`, `:query_params` and/or `:connection_options` |
 | `namespace(path, &block)` | Add path prefix to routes in block |
@@ -674,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

@@ -44,6 +44,21 @@ module ClientApiBuilder
                            "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
@@ -64,6 +79,11 @@ module ClientApiBuilder
       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)

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])
@@ -635,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,6 +10,11 @@ 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.
       # inherit: opts the section into root client settings (see NestedRouter.inherit_from_root);
@@ -31,6 +36,7 @@ module ClientApiBuilder
         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.8.0'
+  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.8.0
+  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