client-api-builder 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b12b7717adcfba57478c6ac76da774640924fa40dd67b9e570db305989de711b
-  data.tar.gz: 56ca42f80c9d6b0ae90cdfc131978421ef8cf7f1f80b9e0e96148fb0e23e95eb
+  metadata.gz: c5a8b4e5fcad31bffb2d4234fb2d73205ae0e3aed33ba75ec32defa778ed456f
+  data.tar.gz: ff349350509add94a7108af7dddf9416b98265752735a510d46d35bc97897849
 SHA512:
-  metadata.gz: 1a4f218c711148e498517406e1893aac38cbba09a64062086b0986b4c187b87220ebce08dcba04d33472282f0998c8c299ac66fa89bd4021dfef6a2bda82b1d2
-  data.tar.gz: 8ba48b3d89d982669e7f7e3a9e2bc5951c96c9c2530b48cd95befd3fff22aed089be12cd04919ccfe43b43801139c65bdbb21364059cde7d55af888e18009d1b
+  metadata.gz: cea030b2bb67c167c3dc4f4a798cadd2e4a8c873fe71d19bed944b4263446f0befb3cbdbc6dccbd9741814aeedb52f0b0b7b2aff155f7800c221601d52383fbd
+  data.tar.gz: 62d3ccbfc3ad52500a29070c6bad1961ba06539e131fc53e5eb775616c8ca179d91c8bd4f0e3bfa150cb3c40a2f8897f3e8bb957d4ae867400c7ec6a872db42e

data/CHANGELOG.md

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

data/README.md

@@ -16,6 +16,8 @@ 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
 - **Comprehensive Error Handling** - Detailed error information for debugging
@@ -399,6 +401,77 @@ 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` 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
+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 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 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):
+
+| 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 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
 
 Configure automatic retries for transient failures:
@@ -719,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` |
@@ -743,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

@@ -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
 
@@ -21,11 +25,13 @@ 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'
   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,13 @@ 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'
+      end
 
       base.extend ClassMethods
       base.connection_pool

data/lib/client_api_builder/http2/connection.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+
+module ClientApiBuilder
+  module HTTP2
+    # One HTTP/2 connection carrying concurrent requests as streams. A reader thread feeds the
+    # socket's bytes to the http-2 client, whose callbacks hand each stream's events to its
+    # Exchange. Every call into the http-2 client, and so every socket write, happens under one
+    # mutex; the reader blocks in readpartial outside it. (OpenSSL never reads and writes at
+    # once: Ruby holds the GVL while calling SSL_read and SSL_write.)
+    #
+    # A connection stops taking new streams once either side sends GOAWAY or it fails, and
+    # closes its socket when its last stream finishes.
+    class Connection
+      READ_SIZE = 16_384
+
+      # Returns nil, after closing the socket, when the server chose HTTP/1.1
+      def self.open(host, port, authority, connection_options)
+        socket = TLSSocket.open(host, port, connection_options)
+        return new(socket, authority, connection_options[:read_timeout]) if socket.alpn_protocol == 'h2'
+
+        socket.close
+        nil
+      end
+
+      def initialize(socket, authority, read_timeout)
+        @socket = socket
+        @authority = authority
+        @read_timeout = read_timeout
+        @mutex = Mutex.new
+        @stream_closed = ConditionVariable.new
+        @exchanges = {}
+        @error = nil
+        @client = build_client
+        @mutex.synchronize { @client.send_connection_preface }
+        @reader = Thread.new { read_loop }
+      end
+
+      # Sends a Net::HTTP request and, like Net::HTTP#request, yields the response before its
+      # body is read, then reads whatever the block left and returns the response
+      def request(net_request)
+        exchange = start(net_request)
+        response = ResponseBuilder.build(exchange.response_headers, exchange, net_request)
+        yield response if block_given?
+        response.read_body
+        response
+      ensure
+        cancel(exchange) if exchange
+      end
+
+      # True while the connection can take new streams
+      def open?
+        @mutex.synchronize { @error.nil? && !@client.closed? }
+      end
+
+      # Says goodbye to the server and closes the socket; streams still in flight fail
+      def close
+        @mutex.synchronize do
+          send_goaway unless @error || @client.closed?
+          abort(ConnectionLost.new("HTTP/2 connection to #{@authority} was closed"))
+        end
+      end
+
+      private
+
+      def build_client
+        client = ::HTTP2::Client.new
+        client.on(:frame) { |bytes| @socket.write(bytes) }
+        client.on(:goaway) { |last_stream_id, _error, _payload| refuse_streams_after(last_stream_id) }
+        client
+      end
+
+      def start(net_request)
+        headers = RequestHeaders.build(net_request, @authority)
+        body = net_request.body
+        @mutex.synchronize do
+          stream = open_stream
+          exchange = @exchanges[stream.id] = Exchange.new(stream, @read_timeout)
+          stream.on(:close) { stream_closed(stream.id) }
+          stream.headers(headers, end_stream: body.nil?)
+          stream.data(body) if body
+          exchange
+        end
+      end
+
+      # Waits, up to read_timeout, while the server's limit on concurrent streams is reached
+      def open_stream
+        deadline = @read_timeout && (now + @read_timeout)
+        loop do
+          raise_if_failed!
+          return @client.new_stream
+        rescue ::HTTP2::Error::StreamLimitExceeded
+          wait_for_stream_slot(deadline)
+        end
+      rescue ::HTTP2::Error::ConnectionClosed
+        raise StreamRefused, "HTTP/2 connection to #{@authority} is no longer taking new streams"
+      end
+
+      def wait_for_stream_slot(deadline)
+        remaining = deadline && (deadline - now)
+        if remaining && !remaining.positive?
+          raise Net::ReadTimeout, "no HTTP/2 stream to #{@authority} became available within #{@read_timeout}s"
+        end
+
+        @stream_closed.wait(@mutex, remaining)
+      end
+
+      def raise_if_failed!
+        raise @error.exception(@error.message) if @error
+      end
+
+      # Resets a stream the caller gave up on (it raised or timed out) so the server stops sending.
+      # Streams that finished, were refused or failed with the connection are no longer tracked.
+      def cancel(exchange)
+        @mutex.synchronize do
+          exchange.stream.cancel if @exchanges.key?(exchange.stream.id)
+        end
+      end
+
+      # The peer may already be gone; the socket is closed next either way
+      def send_goaway
+        @client.goaway
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError => e
+        ::ClientApiBuilder.logger&.warn("HTTP/2 connection to #{@authority} failed to send GOAWAY: #{e.message}")
+      end
+
+      # Called from the reader thread, holding the mutex
+      def stream_closed(stream_id)
+        @exchanges.delete(stream_id)
+        @stream_closed.broadcast
+        close_if_drained
+      end
+
+      # Once no new streams may open, the socket closes with the last stream, which ends the reader
+      def close_if_drained
+        @socket.close if @client.closed? && @exchanges.empty?
+      end
+
+      # Streams the server will never process after GOAWAY are safe to retry elsewhere
+      def refuse_streams_after(last_stream_id)
+        @exchanges.select { |id, _| id > last_stream_id }.each do |id, exchange|
+          @exchanges.delete(id)
+          exchange.fail(StreamRefused.new("HTTP/2 server at #{@authority} went away before stream #{id} was processed"))
+        end
+        @stream_closed.broadcast
+        close_if_drained
+      end
+
+      def read_loop
+        loop do
+          data = @socket.readpartial(READ_SIZE)
+          @mutex.synchronize { @client << data }
+        end
+      rescue StandardError => e
+        fail_connection(e)
+      end
+
+      def fail_connection(exception)
+        @mutex.synchronize { abort(connection_error(exception)) }
+      end
+
+      # Holding the mutex: fails every stream in flight and closes the socket. The first error
+      # sticks, so closing the socket (which ends the reader) doesn't replace the real cause.
+      def abort(error)
+        @error ||= error
+        @exchanges.each_value { |exchange| exchange.fail(@error.exception(@error.message)) }
+        @exchanges.clear
+        @stream_closed.broadcast
+        @socket.close
+      end
+
+      def connection_error(exception)
+        if exception.is_a?(::HTTP2::Error::Error)
+          return ProtocolError.new("HTTP/2 protocol error from #{@authority}: #{exception.message}")
+        end
+
+        ConnectionLost.new("HTTP/2 connection to #{@authority} lost: #{exception.message} (#{exception.class})")
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/client_api_builder/http2/connection_set.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module HTTP2
+    # A client class's HTTP/2 connections: one per host, port and connection options, opened on
+    # first use and replaced once it stops taking new streams. Origins whose server chose
+    # HTTP/1.1 are remembered so they aren't asked again. After a fork the child starts empty;
+    # the parent's connections are dropped without being closed, since closing a shared TLS
+    # socket would disturb the parent.
+    class ConnectionSet
+      def initialize
+        reset
+      end
+
+      # Returns an open connection to the URI's origin, or nil when the server speaks only HTTP/1.1.
+      # A new connection is opened while holding the set's lock, so other origins wait for it.
+      def connection_for(uri, connection_options)
+        reset if forked?
+        key = [uri.hostname, uri.port, connection_options.dup.freeze].freeze
+        @mutex.synchronize do
+          return nil if @http1_origins.include?(key)
+
+          connection = @connections[key]
+          connection&.open? ? connection : open_connection(key, uri, connection_options)
+        end
+      end
+
+      def close
+        connections = @mutex.synchronize do
+          @http1_origins.clear
+          @connections.values.tap { @connections.clear }
+        end
+        connections.each(&:close)
+      end
+
+      private
+
+      def reset
+        @pid = Process.pid
+        @mutex = Mutex.new
+        @connections = {}
+        @http1_origins = Set.new
+      end
+
+      def forked?
+        @pid != Process.pid
+      end
+
+      def open_connection(key, uri, connection_options)
+        connection = Connection.open(uri.hostname, uri.port, authority(uri), connection_options)
+        connection ? @connections[key] = connection : @http1_origins << key
+        connection
+      end
+
+      # host keeps an IPv6 address's brackets; the port is left out when it's the default
+      def authority(uri)
+        uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+      end
+    end
+  end
+end

data/lib/client_api_builder/http2/exchange.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module ClientApiBuilder
+  module HTTP2
+    # One request's stream, seen from the thread waiting on it. The connection's reader thread
+    # pushes the stream's events (headers, data, close) or a connection failure onto a queue;
+    # the waiting thread pops them, giving up after read_timeout seconds without one.
+    #
+    # Received data is acknowledged to the server as it arrives, so a consumer that reads
+    # slower than the server sends buffers the difference in memory.
+    class Exchange
+      attr_reader :stream
+
+      def initialize(stream, read_timeout)
+        @stream = stream
+        @read_timeout = read_timeout
+        @events = Thread::Queue.new
+        @finished = false
+        stream.on(:headers) { |headers| @events << [:headers, headers] }
+        stream.on(:data) { |chunk| @events << [:data, chunk] }
+        stream.on(:close) { |error| @events << [:close, error] }
+      end
+
+      # Called by the connection when the stream will never finish
+      def fail(error)
+        @events << [:error, error]
+      end
+
+      # Waits for the final response headers, skipping informational (1xx) ones
+      def response_headers
+        loop do
+          type, value = next_event
+          raise stream_closed_error(value || :no_error) if type == :close
+          return value unless informational?(value)
+        end
+      end
+
+      # Yields each chunk of the response body until the stream ends. Trailers are ignored.
+      def each_chunk
+        until @finished
+          type, value = next_event
+          yield value if type == :data
+          finish(value) if type == :close
+        end
+      end
+
+      private
+
+      def next_event
+        type, value = @events.pop(timeout: @read_timeout)
+        raise Net::ReadTimeout, "no response on HTTP/2 stream #{stream.id} within #{@read_timeout}s" if type.nil?
+        raise value if type == :error
+
+        [type, value]
+      end
+
+      def finish(error)
+        raise stream_closed_error(error) unless error.nil? || error == :no_error
+
+        @finished = true
+      end
+
+      def informational?(headers)
+        headers.any? { |name, value| name == ':status' && value.start_with?('1') }
+      end
+
+      def stream_closed_error(error)
+        return StreamRefused.new("server refused HTTP/2 stream #{stream.id}") if error == :refused_stream
+
+        StreamError.new("HTTP/2 stream #{stream.id} closed before the response finished (#{error})")
+      end
+    end
+  end
+end

data/lib/client_api_builder/http2/request_headers.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module HTTP2
+    # Turns a Net::HTTP request into an HTTP/2 header list: the pseudo-headers first, then the
+    # request's own headers (already lowercase) without the connection-specific ones HTTP/2
+    # forbids (RFC 9113 section 8.2.2). Host becomes :authority.
+    module RequestHeaders
+      CONNECTION_HEADERS = %w[connection host keep-alive proxy-connection transfer-encoding upgrade].freeze
+
+      module_function
+
+      def build(net_request, authority)
+        headers = pseudo_headers(net_request, authority)
+        net_request.each_header do |name, value|
+          headers << [name, value] unless connection_header?(name, value)
+        end
+        body = net_request.body
+        headers << ['content-length', body.bytesize.to_s] if body && !net_request.key?('content-length')
+        headers
+      end
+
+      def pseudo_headers(net_request, authority)
+        [
+          [':method', net_request.method],
+          [':scheme', 'https'],
+          [':authority', net_request['host'] || authority],
+          [':path', net_request.path]
+        ]
+      end
+
+      # te is allowed only as "trailers"
+      def connection_header?(name, value)
+        CONNECTION_HEADERS.include?(name) || (name == 'te' && value != 'trailers')
+      end
+    end
+  end
+end

data/lib/client_api_builder/http2/response_body.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'zlib'
+
+module ClientApiBuilder
+  module HTTP2
+    # Extended onto a Net::HTTPResponse built by ResponseBuilder: read_body reads the HTTP/2
+    # stream instead of a socket, with Net::HTTP's semantics (into a string, a given buffer or a
+    # block, once). A body that isn't expected is drained and left nil.
+    module ResponseBody
+      def http2_body(exchange, inflate:, expected:)
+        @http2_exchange = exchange
+        @http2_inflate = inflate
+        @http2_body_expected = expected
+      end
+
+      def read_body(dest = nil, &block)
+        if @read
+          raise IOError, "#{self.class}#read_body called twice" if dest || block
+
+          return @body
+        end
+        raise ArgumentError, 'both arg and block given for HTTP method' if dest && block
+
+        @body = @http2_body_expected ? read_http2_body(body_destination(dest, block)) : drain
+        @read = true
+        @body
+      end
+
+      private
+
+      def body_destination(dest, block)
+        return Net::ReadAdapter.new(block) if block
+
+        dest || String.new
+      end
+
+      def read_http2_body(dest)
+        inflater = Zlib::Inflate.new(32 + Zlib::MAX_WBITS) if @http2_inflate
+        @http2_exchange.each_chunk { |chunk| dest << (inflater ? inflater.inflate(chunk) : chunk) }
+        dest << inflater.finish if inflater
+        dest
+      ensure
+        inflater&.close
+      end
+
+      def drain
+        @http2_exchange.each_chunk { |_chunk| nil }
+        nil
+      end
+    end
+  end
+end

data/lib/client_api_builder/http2/response_builder.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module ClientApiBuilder
+  module HTTP2
+    # Builds the Net::HTTPResponse for an HTTP/2 response, so code written against Net::HTTP
+    # (handle_response, UnexpectedResponse#response, response['header']) works unchanged.
+    # HTTP/2 has no reason phrase, so message is empty. Like Net::HTTP, a gzip or deflate body
+    # is inflated when Net::HTTP chose accept-encoding itself (request.decode_content); its
+    # content-encoding and content-length headers are then removed.
+    module ResponseBuilder
+      INFLATABLE_ENCODINGS = %w[gzip deflate].freeze
+
+      module_function
+
+      def build(headers, exchange, net_request)
+        status = headers.assoc(':status').last
+        response = response_class(status).new('2.0', status, '')
+        headers.each { |name, value| response.add_field(name, value) unless name.start_with?(':') }
+        inflate = net_request.decode_content && inflatable?(response)
+        response.delete('content-encoding') if inflate
+        response.delete('content-length') if inflate
+        response.extend(ResponseBody)
+        response.http2_body(exchange, inflate: inflate, expected: body_expected?(response, net_request))
+        response
+      end
+
+      def response_class(status)
+        Net::HTTPResponse::CODE_TO_OBJ[status] ||
+          Net::HTTPResponse::CODE_CLASS_TO_OBJ[status[0]] ||
+          Net::HTTPUnknownResponse
+      end
+
+      def inflatable?(response)
+        INFLATABLE_ENCODINGS.include?(response['content-encoding']&.downcase)
+      end
+
+      # A HEAD request or a 204/304 response has no body; Net::HTTP leaves it nil
+      def body_expected?(response, net_request)
+        net_request.response_body_permitted? && response.class.body_permitted?
+      end
+    end
+  end
+end

data/lib/client_api_builder/http2/tls_socket.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'resolv'
+require 'socket'
+
+module ClientApiBuilder
+  module HTTP2
+    # Opens a TLS connection that offers h2 and http/1.1 through ALPN, applying Net::HTTP's
+    # SSL connection options and certificate checks. The caller reads alpn_protocol to see
+    # which one the server chose.
+    module TLSSocket
+      ALPN_PROTOCOLS = %w[h2 http/1.1].freeze
+
+      # Net::HTTP connection option => SSLContext attribute
+      SSL_OPTIONS = %i[
+        ca_file ca_path cert cert_store ciphers extra_chain_cert key min_version max_version
+        ssl_version verify_callback verify_depth verify_hostname verify_mode
+      ].to_h { |name| [name, name] }.merge(ssl_timeout: :timeout).freeze
+
+      WAIT_EVENTS = { wait_readable: IO::READABLE, wait_writable: IO::WRITABLE }.freeze
+
+      module_function
+
+      def open(host, port, connection_options)
+        context = ssl_context(connection_options)
+        tcp = Socket.tcp(host, port, connect_timeout: connection_options[:open_timeout])
+        begin
+          ssl = start_tls(tcp, host, context, connection_options[:open_timeout])
+          ssl.post_connection_check(host) if verify_hostname?(context)
+          ssl
+        rescue StandardError
+          tcp.close
+          raise
+        end
+      end
+
+      def ssl_context(connection_options)
+        params = SSL_OPTIONS.filter_map do |option, attribute|
+          [attribute, connection_options[option]] unless connection_options[option].nil?
+        end
+        OpenSSL::SSL::SSLContext.new.tap do |context|
+          context.set_params(params.to_h)
+          context.alpn_protocols = ALPN_PROTOCOLS
+        end
+      end
+
+      def start_tls(tcp, host, context, timeout)
+        ssl = OpenSSL::SSL::SSLSocket.new(tcp, context)
+        ssl.sync_close = true
+        ssl.hostname = host unless ip_address?(host)
+        handshake(ssl, timeout && (now + timeout))
+        ssl
+      end
+
+      def handshake(ssl, deadline)
+        while (state = ssl.connect_nonblock(exception: false)).is_a?(Symbol)
+          remaining = deadline && (deadline - now)
+          next if ssl.to_io.wait(WAIT_EVENTS.fetch(state), remaining)
+
+          raise Net::OpenTimeout, 'TLS handshake timed out'
+        end
+      end
+
+      # Same rule as Net::HTTP: the certificate must match the host unless verification is off
+      def verify_hostname?(context)
+        context.verify_mode != OpenSSL::SSL::VERIFY_NONE && context.verify_hostname != false
+      end
+
+      def ip_address?(host)
+        host.match?(Resolv::IPv4::Regex) || host.match?(Resolv::IPv6::Regex)
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/client_api_builder/http2.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# 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 or ClientApiBuilder::ThreadConnections when using either:
+#
+#   class MyClient
+#     include ClientApiBuilder::Router
+#     include ClientApiBuilder::HTTP2
+#
+#     base_url 'https://api.example.com'
+#   end
+#
+# 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 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'
+    autoload :ConnectionSet, 'client_api_builder/http2/connection_set'
+    autoload :Exchange, 'client_api_builder/http2/exchange'
+    autoload :RequestHeaders, 'client_api_builder/http2/request_headers'
+    autoload :ResponseBody, 'client_api_builder/http2/response_body'
+    autoload :ResponseBuilder, 'client_api_builder/http2/response_builder'
+    autoload :TLSSocket, 'client_api_builder/http2/tls_socket'
+
+    # The connection dropped (or was closed) before the response finished
+    class ConnectionLost < ::ClientApiBuilder::RetryableError; end
+
+    # The server refused the stream, or announced it would stop (GOAWAY) before processing it
+    class StreamRefused < ::ClientApiBuilder::RetryableError; end
+
+    # The server reset the stream with an error code
+    class StreamError < ::ClientApiBuilder::Error; end
+
+    # The server broke the HTTP/2 protocol; the connection is closed
+    class ProtocolError < ::ClientApiBuilder::Error; end
+
+    def self.included(base)
+      unless base.include?(::ClientApiBuilder::Router)
+        raise ArgumentError, 'include ClientApiBuilder::Router before ClientApiBuilder::HTTP2'
+      end
+
+      require_http2_gem
+      base.extend ClassMethods
+      base.redefine_class_method(:http2_connections, ConnectionSet.new)
+    end
+
+    def self.require_http2_gem
+      require 'http/2'
+    rescue LoadError
+      raise LoadError, "ClientApiBuilder::HTTP2 needs the http-2 gem; add gem 'http-2' to your Gemfile"
+    end
+
+    module ClassMethods
+      # 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)
+      end
+    end
+
+    def with_http_connection(uri, connection_options, &)
+      connection = uri.scheme == 'https' && self.class.http2_connections.connection_for(uri, connection_options)
+      connection ? yield(connection) : super
+    end
+  end
+end

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

@@ -6,6 +6,9 @@ require 'json'
 
 module ClientApiBuilder
   module Router
+    # Status codes accepted when a route lists no expected_response_codes
+    SUCCESS_CODE = /\A2\d\d\z/
+
     def self.included(base)
       base.extend InheritanceHelper::Methods
       base.extend ClassMethods
@@ -578,8 +581,10 @@ module ClientApiBuilder
       url
     end
 
+    # Checks the status code rather than the response class, so any response object with a
+    # Net::HTTPResponse-style string code works (e.g. from a non-Net::HTTP transport)
     def expected_response_code!(response, expected_response_codes, _options)
-      return if expected_response_codes.empty? && response.is_a?(Net::HTTPSuccess)
+      return if expected_response_codes.empty? && SUCCESS_CODE.match?(response.code.to_s)
       return if expected_response_codes.include?(response.code)
 
       raise(::ClientApiBuilder::UnexpectedResponse.new("unexpected response code #{response.code}", response))
@@ -686,7 +691,7 @@ module ClientApiBuilder
     def retry_request?(exception, _options)
       case exception
       when Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
-           Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, EOFError
+           Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, EOFError, ::ClientApiBuilder::RetryableError
         true
       else
         false

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.9.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.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Doug Youch
@@ -45,12 +45,23 @@ files:
 - 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/http2.rb
+- lib/client_api_builder/http2/connection.rb
+- lib/client_api_builder/http2/connection_set.rb
+- lib/client_api_builder/http2/exchange.rb
+- lib/client_api_builder/http2/request_headers.rb
+- lib/client_api_builder/http2/response_body.rb
+- lib/client_api_builder/http2/response_builder.rb
+- lib/client_api_builder/http2/tls_socket.rb
 - lib/client_api_builder/nested_router.rb
 - lib/client_api_builder/net_http_request.rb
 - lib/client_api_builder/query_params.rb
 - 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: