client-api-builder 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e2d55d531b568e6f1cb0bb718ee236ca44eac7951c133ca6f2d294460968a80
-  data.tar.gz: d617dc3983f1cde402095e2be735c804f9a657969007a1f601779fe90f01c110
+  metadata.gz: d24a1d62d5ce8f7ace55ad6e7505fddb3663c51d032df031f4e058bb632b6f5e
+  data.tar.gz: a40b56b3f7ff04ecbe3507ea7ef9a7e5bbd8bc0aeb34ef9a0255038b62574948
 SHA512:
-  metadata.gz: 288273782ec2072f360e56b3653a80510684fd05772560db6544b438cc558c56a58d8de179cf87636a80dc396789aed431c63aee4681e90ad9bbc11325b294ba
-  data.tar.gz: 5a8622d04ae326e393c1b104a79ff8ed30f1f22420b6b3a7f4b1f30aa39b4e29e7929b625d8ff665276dd6ad45e2ee96e327afceb082b9a6c1d7eb227dde2229
+  metadata.gz: '08cbffeca686d5299d7e294a25a750dc5ea7542ba017c3dbda817159b395bc51af51802f09326594b20968ac8f5628bf29d0e798bec84fddf4ff18c2e2613759'
+  data.tar.gz: 7a8476834697f1c8daf6498eeccd0a9fb256fd93b820e5fd407e586a49bdd3564459f005536b7eb0f29eba27c4925ffd8197289a77293df60310495f2c8c93a1

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.10.0](https://github.com/dougyouch/client-api-builder/compare/v0.9.0...v0.10.0) (2026-10-04)
+
+
+### Features
+
+* add opt-in HTTP/2 support ([48c6f6e](https://github.com/dougyouch/client-api-builder/commit/48c6f6e37b9c346d2e8b70db30a72661ea18358e))
+* **http2:** add opt-in HTTP/2 support ([10ee136](https://github.com/dougyouch/client-api-builder/commit/10ee13677d1914dd37dd5efb2afee9779e2fdbda))
+
+
+### Performance Improvements
+
+* **http2:** add HTTP/1.1 vs HTTP/2 benchmark script ([29b9add](https://github.com/dougyouch/client-api-builder/commit/29b9adde11ae6dcf55a5f2eedf0c1826774bb51a))
+
+## [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,8 @@ 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
+- **HTTP/2** - Opt-in HTTP/2 over TLS, multiplexing concurrent requests on one connection per host (with the `http-2` gem)
 - **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 +127,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 +360,85 @@ 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.
+
+### HTTP/2
+
+Include `ClientApiBuilder::HTTP2` (after `Router`, and after `ConnectionPools` if you use both) to send https requests over HTTP/2. It needs the [`http-2`](https://rubygems.org/gems/http-2) gem, which isn't installed with this one:
+
+```ruby
+# Gemfile
+gem 'http-2'
+```
+
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+  include ClientApiBuilder::ConnectionPools # optional: used for servers that only speak HTTP/1.1
+  include ClientApiBuilder::HTTP2
+
+  base_url 'https://api.example.com'
+end
+```
+
+Every instance of the class shares one connection per host (and connection options), and concurrent requests from different threads travel over it as separate streams. Responses are ordinary `Net::HTTPResponse` objects with `http_version` `'2.0'`, so `handle_response`, `UnexpectedResponse#response` and streaming routes work unchanged.
+
+- The protocol is negotiated during the TLS handshake (ALPN). When a server picks HTTP/1.1, that host is remembered and its requests go through `Net::HTTP`, or the connection pools if the class includes `ConnectionPools`. `http://` URLs always use HTTP/1.1.
+- The usual connection options apply: `open_timeout`, `read_timeout` (per response header and body chunk), and the SSL options (`verify_mode`, `ca_file`, `cert_store`, `cert`, `key`, ...). Proxies aren't supported.
+- When the server's limit on concurrent streams is reached, a request waits up to `read_timeout` for a stream to free up.
+- Gzip and deflate responses are inflated, as `Net::HTTP` does, unless you set `Accept-Encoding` yourself.
+- A stream the server refused, or never processed before closing the connection (GOAWAY), raises `ClientApiBuilder::HTTP2::StreamRefused`; a dropped connection raises `ClientApiBuilder::HTTP2::ConnectionLost`. Both are retried by `configure_retries`. A stream the server reset raises `ClientApiBuilder::HTTP2::StreamError`.
+- Response data is acknowledged to the server as it arrives, so a streaming consumer slower than the server buffers the difference in memory.
+- Sections use their root client's connections. After a fork, the child opens its own. `MyApiClient.close_connections` closes the HTTP/2 connections (and the pools).
+
+**When it's faster.** `script/benchmark_http2.rb` compares a new connection per request, `ConnectionPools` and HTTP/2 against a local TLS server. On one machine (Ruby 4.0.7, http-2 1.2.3):
+
+| Scenario (1000 requests) | New connection | Pooled | HTTP/2 |
+|---|---|---|---|
+| 1 thread, no server delay | 501 req/s | 4,824 req/s | 2,057 req/s |
+| 50 threads, 20ms delay, one pooled connection per thread | 628 req/s | 1,904 req/s | 1,765 req/s |
+| 50 threads, 20ms delay, default pool of 5 | 640 req/s | 208 req/s | 1,706 req/s |
+
+HTTP/2 avoids a TLS handshake per request, like the pools, and isn't limited by a connection count: many threads waiting on a slow API share one connection. Per request, it costs more client CPU than pooled HTTP/1.1 (the protocol layer is pure Ruby), which shows most with large bodies. If you can give the pools a connection per thread, they're usually as fast or faster.
+
 ### Retry Configuration
 
 Configure automatic retries for transient failures:
@@ -370,7 +454,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 +723,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 +756,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 +783,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

@@ -5,6 +5,10 @@ require_relative 'client_api_builder/version'
 module ClientApiBuilder
   class Error < StandardError; end
 
+  # Raised by a transport when a request failed in a way that is safe to send again, e.g. the
+  # server refused it before processing it. Router#retry_request? retries these.
+  class RetryableError < Error; end
+
   class UnexpectedResponse < Error
     attr_reader :response
 
@@ -20,6 +24,8 @@ 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 :HTTP2, 'client_api_builder/http2'
   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,57 @@
+# 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
+      # HTTP2 falls back to the pools through super, so it must come after them
+      if base.ancestors.any? { |mod| mod.name == 'ClientApiBuilder::HTTP2' }
+        raise ArgumentError, 'include ClientApiBuilder::ConnectionPools before ClientApiBuilder::HTTP2'
+      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