client-api-builder 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b12b7717adcfba57478c6ac76da774640924fa40dd67b9e570db305989de711b
-  data.tar.gz: 56ca42f80c9d6b0ae90cdfc131978421ef8cf7f1f80b9e0e96148fb0e23e95eb
+  metadata.gz: d24a1d62d5ce8f7ace55ad6e7505fddb3663c51d032df031f4e058bb632b6f5e
+  data.tar.gz: a40b56b3f7ff04ecbe3507ea7ef9a7e5bbd8bc0aeb34ef9a0255038b62574948
 SHA512:
-  metadata.gz: 1a4f218c711148e498517406e1893aac38cbba09a64062086b0986b4c187b87220ebce08dcba04d33472282f0998c8c299ac66fa89bd4021dfef6a2bda82b1d2
-  data.tar.gz: 8ba48b3d89d982669e7f7e3a9e2bc5951c96c9c2530b48cd95befd3fff22aed089be12cd04919ccfe43b43801139c65bdbb21364059cde7d55af888e18009d1b
+  metadata.gz: '08cbffeca686d5299d7e294a25a750dc5ea7542ba017c3dbda817159b395bc51af51802f09326594b20968ac8f5628bf29d0e798bec84fddf4ff18c2e2613759'
+  data.tar.gz: 7a8476834697f1c8daf6498eeccd0a9fb256fd93b820e5fd407e586a49bdd3564459f005536b7eb0f29eba27c4925ffd8197289a77293df60310495f2c8c93a1

data/CHANGELOG.md

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

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
+- **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 +400,45 @@ The pools live on the class, like ActiveRecord's, so every instance shares them:
 
 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:

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,6 +25,7 @@ module ClientApiBuilder
   autoload :ActiveSupportNotifications, 'client_api_builder/active_support_notifications'
   autoload :ActiveSupportLogSubscriber, 'client_api_builder/active_support_log_subscriber'
   autoload :ConnectionPools, 'client_api_builder/connection_pools'
+  autoload :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.rb

@@ -26,6 +26,10 @@ module ClientApiBuilder
       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

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,69 @@
+# 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 when using both:
+#
+#   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 connection pools) 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 connection pools 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/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/version.rb

@@ -2,5 +2,5 @@
 
 module ClientApiBuilder
   # Gem version, bumped by release-please
-  VERSION = '0.9.0'
+  VERSION = '0.10.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.10.0
 platform: ruby
 authors:
 - Doug Youch
@@ -45,6 +45,14 @@ 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