client-api-builder 0.8.0 → 0.10.0

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

@@ -44,6 +44,21 @@ module ClientApiBuilder
                            "Allowed: #{INHERITABLE_SETTINGS.map(&:inspect).join(', ')}"
     end
 
+    # Gives this section its own connection pools (see ConnectionPools.connection_pool).
+    # Including ConnectionPools puts its connection_pool ahead of this one, so the call
+    # below configures the pools rather than recursing.
+    def self.connection_pool(**settings)
+      include ::ClientApiBuilder::ConnectionPools
+
+      connection_pool(**settings)
+    end
+
+    # Closes the pools of any nested sections that have their own; a section with its own
+    # pools uses ConnectionPools.close_connections, which closes those as well
+    def self.close_connections
+      section_routers.each_value(&:close_connections)
+    end
+
     def configured_headers
       inherits_from_root?(:headers) ? root_router.configured_headers.merge(super) : super
     end
@@ -64,6 +79,11 @@ module ClientApiBuilder
       root_router.handle_response(response, options, &)
     end
 
+    # Uses the root client's connections unless this section calls connection_pool
+    def with_http_connection(uri, connection_options, &)
+      root_router.with_http_connection(uri, connection_options, &)
+    end
+
     private
 
     def inherits_from_root?(setting)

data/lib/client_api_builder/net_http_request.rb

@@ -43,13 +43,19 @@ module ClientApiBuilder
         ssl_options = uri.scheme == 'https' ? DEFAULT_SECURE_OPTIONS.merge(use_ssl: true) : {}
         merged_options = ssl_options.merge(connection_options)
 
-        Net::HTTP.start(uri.hostname, uri.port, merged_options) do |http|
+        with_http_connection(uri, merged_options) do |http|
           http.request(request) do |response|
             yield response if block_given?
           end
         end
       end
 
+      # Yields a started Net::HTTP session for one request. By default each request opens
+      # and closes its own connection; ConnectionPools overrides this to reuse pooled ones.
+      def with_http_connection(uri, connection_options, &)
+        Net::HTTP.start(uri.hostname, uri.port, connection_options, &)
+      end
+
       # validate_response, when given, is called with the response before its body is streamed
       # and raises to reject it. A rejected body is read into response.body instead of being
       # streamed, so the error can still show it.