client-api-builder 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d24a1d62d5ce8f7ace55ad6e7505fddb3663c51d032df031f4e058bb632b6f5e
-  data.tar.gz: a40b56b3f7ff04ecbe3507ea7ef9a7e5bbd8bc0aeb34ef9a0255038b62574948
+  metadata.gz: c5a8b4e5fcad31bffb2d4234fb2d73205ae0e3aed33ba75ec32defa778ed456f
+  data.tar.gz: ff349350509add94a7108af7dddf9416b98265752735a510d46d35bc97897849
 SHA512:
-  metadata.gz: '08cbffeca686d5299d7e294a25a750dc5ea7542ba017c3dbda817159b395bc51af51802f09326594b20968ac8f5628bf29d0e798bec84fddf4ff18c2e2613759'
-  data.tar.gz: 7a8476834697f1c8daf6498eeccd0a9fb256fd93b820e5fd407e586a49bdd3564459f005536b7eb0f29eba27c4925ffd8197289a77293df60310495f2c8c93a1
+  metadata.gz: cea030b2bb67c167c3dc4f4a798cadd2e4a8c873fe71d19bed944b4263446f0befb3cbdbc6dccbd9741814aeedb52f0b0b7b2aff155f7800c221601d52383fbd
+  data.tar.gz: 62d3ccbfc3ad52500a29070c6bad1961ba06539e131fc53e5eb775616c8ca179d91c8bd4f0e3bfa150cb3c40a2f8897f3e8bb957d4ae867400c7ec6a872db42e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.11.0](https://github.com/dougyouch/client-api-builder/compare/v0.10.0...v0.11.0) (2026-10-04)
+
+
+### Features
+
+* **thread_connections:** add per-thread persistent connections ([3ad347d](https://github.com/dougyouch/client-api-builder/commit/3ad347d7a022b60dfb9e0d36de5260dd37f456be))
+* **thread_connections:** add per-thread persistent connections ([4f61cd9](https://github.com/dougyouch/client-api-builder/commit/4f61cd94731ac81c0993bfbee8acf6c9c4328ce2))
+
 ## [0.10.0](https://github.com/dougyouch/client-api-builder/compare/v0.9.0...v0.10.0) (2026-10-04)
 
 

data/README.md

@@ -16,6 +16,7 @@ A Ruby gem for building robust, secure API clients through declarative configura
 - **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
+- **Per-Thread Connections** - Opt-in persistent connections dedicated to each thread, with no pool to size
 - **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
@@ -400,9 +401,41 @@ The pools live on the class, like ActiveRecord's, so every instance shares them:
 
 Pooling uses only `Net::HTTP` from the standard library.
 
+### Per-Thread Connections
+
+When a program runs a fixed set of worker threads, each making its own requests, include `ClientApiBuilder::ThreadConnections` (after `Router`, instead of `ConnectionPools`) to give every thread its own persistent connections:
+
+```ruby
+class MyApiClient
+  include ClientApiBuilder::Router
+  include ClientApiBuilder::ThreadConnections
+
+  base_url 'https://api.example.com'
+
+  # Optional; these are the defaults
+  connection_per_thread ttl: 30,        # seconds before a connection is closed and replaced
+                        idle_timeout: 2 # seconds idle before Net::HTTP reconnects (keep_alive_timeout)
+end
+
+workers = Array.new(20) do
+  Thread.new do
+    client = MyApiClient.new
+    user_ids.each { |id| client.get_user(id: id) } # always over this thread's connection
+  end
+end
+```
+
+A thread opens a connection per host (scheme, port and connection options) on its first request and reuses it for every later one. There's no pool size to keep in step with the thread count, and no thread ever waits for another's connection.
+
+- 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.
+- A request made while the thread's connection is busy (from inside a streaming block, or from another fiber on the thread) opens a connection of its own; the thread keeps one of the two afterwards.
+- Connections of threads that have finished are closed when a thread makes its first request. With short-lived threads, prefer `ConnectionPools`.
+- Sections and subclasses share the class's connections the same way they share pools, and a section can call `connection_per_thread` in its block to get its own.
+- After a fork, the child process opens its own connections. `MyApiClient.close_connections` closes every thread's idle connections now and in-use ones when their request ends.
+
 ### 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:
+Include `ClientApiBuilder::HTTP2` (after `Router`, and after `ConnectionPools` or `ThreadConnections` if you use either) 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
@@ -421,13 +454,13 @@ 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 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 pooled or per-thread connections if the class includes `ConnectionPools` or `ThreadConnections`. `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).
+- 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 pooled or per-thread ones).
 
 **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):
 
@@ -437,7 +470,7 @@ Every instance of the class shares one connection per host (and connection optio
 | 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.
+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 each thread its own connection (a pool as large as the thread count, or `ThreadConnections`), HTTP/1.1 is usually as fast or faster.
 
 ### Retry Configuration
 
@@ -759,7 +792,8 @@ end
 | `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`) |
+| `connection_per_thread(**settings)` | Configure persistent per-thread connections (requires `include ClientApiBuilder::ThreadConnections`) |
+| `close_connections` | Close the class's pooled or per-thread connections and its sections' (with `ConnectionPools` or `ThreadConnections`) |
 | `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` |
@@ -783,7 +817,7 @@ 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` |
+| `with_http_connection(uri, connection_options, &block)` | Yields a started `Net::HTTP`: a new connection per request, a pooled one with `ConnectionPools`, or the thread's own with `ThreadConnections` |
 | `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 |

data/lib/client-api-builder.rb

@@ -31,6 +31,7 @@ module ClientApiBuilder
   autoload :RouteValueValidator, 'client_api_builder/route_value_validator'
   autoload :Router, 'client_api_builder/router'
   autoload :Section, 'client_api_builder/section'
+  autoload :ThreadConnections, 'client_api_builder/thread_connections'
 
   module NetHTTP
     autoload :Request, 'client_api_builder/net_http_request'

data/lib/client_api_builder/connection_pools.rb

@@ -26,6 +26,9 @@ module ClientApiBuilder
       unless base.include?(::ClientApiBuilder::Router)
         raise ArgumentError, 'include ClientApiBuilder::Router before ClientApiBuilder::ConnectionPools'
       end
+      if base.include?(::ClientApiBuilder::ThreadConnections)
+        raise ArgumentError, 'include either ClientApiBuilder::ConnectionPools or ClientApiBuilder::ThreadConnections'
+      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'

data/lib/client_api_builder/http2.rb

@@ -2,7 +2,7 @@
 
 # Purpose: opt-in HTTP/2 for https requests, using the http-2 gem (add gem 'http-2' to your
 # Gemfile; it isn't a runtime dependency). Include after ClientApiBuilder::Router, and after
-# ClientApiBuilder::ConnectionPools when using both:
+# ClientApiBuilder::ConnectionPools or ClientApiBuilder::ThreadConnections when using either:
 #
 #   class MyClient
 #     include ClientApiBuilder::Router
@@ -13,8 +13,9 @@
 #
 # Every instance of the class shares one connection per origin, carrying concurrent requests
 # as streams. TLS negotiates the protocol (ALPN): when the server picks HTTP/1.1, the origin is
-# remembered and its requests go through Net::HTTP (or the connection pools) instead. http
-# URLs always use HTTP/1.1. Responses are Net::HTTPResponse objects with http_version '2.0'.
+# remembered and its requests go through Net::HTTP (or the pooled or per-thread connections)
+# instead. http URLs always use HTTP/1.1. Responses are Net::HTTPResponse objects with
+# http_version '2.0'.
 module ClientApiBuilder
   module HTTP2
     autoload :Connection, 'client_api_builder/http2/connection'
@@ -54,7 +55,8 @@ module ClientApiBuilder
     end
 
     module ClassMethods
-      # Closes this class's HTTP/2 connections, and its connection pools when it has them
+      # Closes this class's HTTP/2 connections, and its pooled or per-thread connections when it
+      # has them
       def close_connections
         http2_connections.close
         super if defined?(super)

data/lib/client_api_builder/nested_router.rb

@@ -53,8 +53,16 @@ module ClientApiBuilder
       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
+    # Gives this section its own per-thread connections (see
+    # ThreadConnections.connection_per_thread), the same way connection_pool does
+    def self.connection_per_thread(**settings)
+      include ::ClientApiBuilder::ThreadConnections
+
+      connection_per_thread(**settings)
+    end
+
+    # Closes the connections of any nested sections that have their own; a section with its
+    # own uses ConnectionPools or ThreadConnections.close_connections, which close those as well
     def self.close_connections
       section_routers.each_value(&:close_connections)
     end
@@ -79,7 +87,8 @@ module ClientApiBuilder
       root_router.handle_response(response, options, &)
     end
 
-    # Uses the root client's connections unless this section calls connection_pool
+    # Uses the root client's connections unless this section calls connection_pool or
+    # connection_per_thread
     def with_http_connection(uri, connection_options, &)
       root_router.with_http_connection(uri, connection_options, &)
     end

data/lib/client_api_builder/thread_connections/connection_set.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module ThreadConnections
+    # A client class's connections, kept per thread: one per scheme, host, port and connection
+    # options, opened on the thread's first request and reused by its later ones.
+    #
+    # A connection is taken out of its thread's slot while a request uses it, so a request made
+    # before it's back (from a streaming block, or another fiber on the thread) opens one of its
+    # own; whichever finishes second is closed rather than kept. A connection that outlives the
+    # ttl, was opened before close, or whose request raised is closed instead of reused. The
+    # connections of threads that have died are closed when a thread makes its first request.
+    # After a fork the child starts with none; the parent's are dropped without being closed,
+    # since closing a shared TLS socket would disturb the parent.
+    class ConnectionSet
+      MONOTONIC_CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+      attr_reader :settings
+
+      def initialize(settings, clock: MONOTONIC_CLOCK)
+        @settings = settings
+        @clock = clock
+        reset
+      end
+
+      # Yields the current thread's Net::HTTP session and returns the block's result
+      def with_connection(uri, connection_options)
+        key = [uri.scheme, uri.hostname, uri.port, connection_options.dup.freeze].freeze
+        connection = checkout(key) || open_connection(uri, connection_options)
+        returned = false
+        begin
+          result = yield connection.http
+          checkin(key, connection)
+          returned = true
+          result
+        ensure
+          connection.close unless returned
+        end
+      end
+
+      # Closes idle connections now; connections in use are closed when their request ends
+      def close
+        idle = @mutex.synchronize do
+          @closed_at = now
+          remove_threads(@threads.keys)
+        end
+        idle.each(&:close)
+      end
+
+      # Idle connections, across all threads
+      def size
+        @mutex.synchronize { @threads.each_value.sum(&:size) }
+      end
+
+      private
+
+      def reset
+        @pid = Process.pid
+        @mutex = Mutex.new
+        @threads = {}
+        @closed_at = nil
+      end
+
+      def forked?
+        @pid != Process.pid
+      end
+
+      def now
+        @clock.call
+      end
+
+      # Returns the thread's connection for key, or nil when it has none to reuse. Retired
+      # connections are closed after the lock is released.
+      def checkout(key)
+        retired = []
+        reset if forked?
+        @mutex.synchronize do
+          retired.concat(remove_threads(dead_threads)) unless @threads.key?(Thread.current)
+          take(key, retired)
+        end
+      ensure
+        retired.each(&:close)
+      end
+
+      def take(key, retired)
+        connection = @threads[Thread.current]&.delete(key)
+        return connection unless connection && retire?(connection)
+
+        retired << connection
+        nil
+      end
+
+      def open_connection(uri, connection_options)
+        ConnectionPools::Connection.open(uri.hostname, uri.port,
+                                         { keep_alive_timeout: settings.idle_timeout }.merge(connection_options), now)
+      end
+
+      def checkin(key, connection)
+        connection.used(now)
+        kept = @mutex.synchronize { !retire?(connection) && keep?(key, connection) }
+        connection.close unless kept
+      end
+
+      # Keeps the connection for the thread's next request, unless a request that ran while
+      # this one did has already left one there
+      def keep?(key, connection)
+        connections = (@threads[Thread.current] ||= {})
+        return false if connections.key?(key)
+
+        connections[key] = connection
+        true
+      end
+
+      def dead_threads
+        @threads.keys.reject(&:alive?)
+      end
+
+      # Forgets the threads and returns their idle connections
+      def remove_threads(threads)
+        threads.flat_map { |thread| @threads.delete(thread).values }
+      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/thread_connections/settings.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module ThreadConnections
+    # ttl:          seconds a connection may live before it's closed and replaced
+    # 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(:ttl, :idle_timeout) do
+      def initialize(ttl: 30, idle_timeout: 2)
+        { ttl: ttl, idle_timeout: idle_timeout }.each do |name, value|
+          next if value.is_a?(Numeric) && value.positive?
+
+          raise ArgumentError, "#{name} must be a positive number of seconds, got #{value.inspect}"
+        end
+        super
+      end
+    end
+  end
+end

data/lib/client_api_builder/thread_connections.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Purpose: opt-in persistent HTTP connections dedicated to each thread. Include after
+# ClientApiBuilder::Router, instead of ClientApiBuilder::ConnectionPools:
+#
+#   class MyClient
+#     include ClientApiBuilder::Router
+#     include ClientApiBuilder::ThreadConnections
+#
+#     connection_per_thread ttl: 60
+#   end
+#
+# Each thread opens its own connection per host on its first request and reuses it for its
+# later ones, so there's no pool size to match to the thread count and no waiting for a
+# connection to free up.
+module ClientApiBuilder
+  module ThreadConnections
+    autoload :ConnectionSet, 'client_api_builder/thread_connections/connection_set'
+    autoload :Settings, 'client_api_builder/thread_connections/settings'
+
+    def self.included(base)
+      unless base.include?(::ClientApiBuilder::Router)
+        raise ArgumentError, 'include ClientApiBuilder::Router before ClientApiBuilder::ThreadConnections'
+      end
+      if base.include?(::ClientApiBuilder::ConnectionPools)
+        raise ArgumentError, 'include either ClientApiBuilder::ConnectionPools or ClientApiBuilder::ThreadConnections'
+      end
+      # HTTP2 falls back to these connections through super, so it must come after them
+      if base.ancestors.any? { |mod| mod.name == 'ClientApiBuilder::HTTP2' }
+        raise ArgumentError, 'include ClientApiBuilder::ThreadConnections before ClientApiBuilder::HTTP2'
+      end
+
+      base.extend ClassMethods
+      base.connection_per_thread
+    end
+
+    module ClassMethods
+      # Configures this class's per-thread connections, replacing any it already had.
+      # Subclasses share their parent's unless they call connection_per_thread themselves.
+      def connection_per_thread(**settings)
+        redefine_class_method(:thread_connections, ConnectionSet.new(Settings.new(**settings)))
+      end
+
+      # Closes every thread's idle connections now and in-use ones when their request ends,
+      # including those of sections that have their own
+      def close_connections
+        thread_connections.close
+        section_routers.each_value(&:close_connections)
+      end
+    end
+
+    def with_http_connection(uri, connection_options, &)
+      self.class.thread_connections.with_connection(uri, connection_options, &)
+    end
+  end
+end

data/lib/client_api_builder/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: client-api-builder
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Doug Youch
@@ -59,6 +59,9 @@ files:
 - lib/client_api_builder/route_value_validator.rb
 - lib/client_api_builder/router.rb
 - lib/client_api_builder/section.rb
+- lib/client_api_builder/thread_connections.rb
+- lib/client_api_builder/thread_connections/connection_set.rb
+- lib/client_api_builder/thread_connections/settings.rb
 - lib/client_api_builder/version.rb
 homepage: https://github.com/dougyouch/client-api-builder
 licenses: