httpx 1.8.4 → 1.9.1

data/lib/httpx/plugins/fiber_concurrency.rb

@@ -76,10 +76,10 @@ module HTTPX
           super
         end
 
-        def interests
-          return if connecting? && @pending.none?(&:current_context?)
-
-          super
+        def closed_for_select?
+          # @fiber-switch-guard
+          # a closed connection still holding requests will reconnect once the fiber closing its socket resumes.
+          super && @pending.empty?
         end
 
         def on_io_error(e)
@@ -88,17 +88,12 @@ module HTTPX
           # @fiber-switch-guard
           # sockets closed during fiber scheduler switches are raised in separate fibers than the fiber the
           # socket may be used in. this check verifies that this is actually about this socket.
-          return unless to_io.closed?
-
-          if @state == :closing
-            # @fiber-switch-guard
-            # if the connection is reused across fibers, the socket may have been closed in the other fiber
-            # and switched here during the process, so continue what it was doing and transition to closed
-            # via #call.
+          unless to_io.closed? && !backlog?
             call
-          elsif !backlog?
-            super
+            return
           end
+
+          super
         end
 
         def on_connect_error(e)
@@ -107,18 +102,50 @@ module HTTPX
           # @fiber-switch-guard
           # sockets closed during fiber scheduler switches are raised in separate fibers than the fiber the
           # socket may be used in. this check verifies that this is actually about this socket.
-          return unless to_io.closed? && !backlog?
+          unless to_io.closed? && !backlog?
+            call
+            return
+          end
+
+          super
+        end
+
+        def pending_count
+          @pending.count(&:current_context?)
+        end
+
+        def interests
+          idling if (@state == :closed) && !no_more_requests?
 
           super
         end
 
         private
 
+        def handle_transition(nextstate)
+          case nextstate
+          when :inactive
+            # @fiber-switch-guard
+            # connections may have requests (pending or inflight) from other fibers.
+            return if @state == :open && backlog?
+          end
+          super
+        end
+
+        def no_requests_to_handle?
+          pending_count.zero? && @parser&.no_requests_to_handle?
+        end
+
+        # @fiber-switch-guard
+        # pending requests from other fibers are still being waited for.
+        def clear_pending_requests
+          @pending.reject!(&:current_context?)
+        end
+
         # checks whether the connection has any pending request (which the connection itself may
         # have stored, or it may be somewhere in the parser).
         def backlog?
-          @pending.any? ||
-            (@parser && (@parser.pending.any? || @parser.requests.any?))
+          @pending.any? || @parser&.backlog? || @parser&.waiting_for_ping?
         end
       end
 
@@ -132,6 +159,14 @@ module HTTPX
 
           super
         end
+
+        def backlog?
+          !no_more_requests?
+        end
+
+        def no_requests_to_handle?
+          @requests.none?(&:current_context?)
+        end
       end
 
       module HTTP2Methods
@@ -156,6 +191,14 @@ module HTTPX
           super
         end
 
+        def backlog?
+          !no_more_requests?
+        end
+
+        def no_requests_to_handle?
+          @streams.each_key.none?(&:current_context?)
+        end
+
         private
 
         def on_close(_, error, _)

data/lib/httpx/plugins/follow_redirects.rb

@@ -61,7 +61,7 @@ module HTTPX
       end
 
       module InstanceMethods
-        # returns a session with the *max_redirects* option set to +n+
+        # returns a session with the <tt>:max_redirects</tt> option set to +n+.
         def max_redirects(n)
           with(max_redirects: n.to_i)
         end

data/lib/httpx/plugins/grpc.rb

@@ -69,6 +69,17 @@ module HTTPX
         end
       end
 
+      # adds support for the following options:
+      #
+      # :grpc_service :: name of the GRPC service service.
+      # :grpc_compression :: whether payloads should be GZIP-compressed (<tt>false</tt> by default).
+      # :grpc_rpcs :: maps local rpc names to the service RCP information.
+      # :grpc_deadline :: sets the service call deadline that the peer should stick to.
+      # :call_credentials :: callable which should yield a key-value hash which will be passed in the
+      #                      request HTTP headers.
+      #
+      # You're recommended not to set any of these options directly, and instead use methods such as
+      # InstanceMethods#rpc and InstanceMethods#build_stub.
       module OptionsMethods
         private
 
@@ -125,6 +136,9 @@ module HTTPX
       end
 
       module InstanceMethods
+        # returns a new session which sets the TLS channel credentials (+ca_path+ as the CA file,
+        # +key+ and +cert+ as the TLS public key and certificate, as well as other TLS options via
+        # +ssl_opts+, which should be compatible with what OpenSSL::SSL::SSLContext#set_params receives).
         def with_channel_credentials(ca_path, key = nil, cert = nil, **ssl_opts)
           # @type var ssl_params: ::Hash[::Symbol, untyped]
           ssl_params = {
@@ -144,6 +158,8 @@ module HTTPX
           with(ssl: ssl_params)
         end
 
+        # returns a new session with a service RPC identified by +rpc_name+, passing +input+ and +output+ as its
+        # input encoder and output decoder respectively; extra options (like <tt>:deadline</tt>) can be passed using +opts+.
         def rpc(rpc_name, input, output, **opts)
           rpc_name = rpc_name.to_s
           raise Error, "rpc #{rpc_name} already defined" if @options.grpc_rpcs.key?(rpc_name)
@@ -179,6 +195,9 @@ module HTTPX
                             ))
         end
 
+        # returns a new GRPC Service enabled session pointing to a +origin+ URI; when the
+        # +service+ is a GRPC Service object (as the ones provided by the `grpc` gem), it'll
+        # automatically generate the RPC methods.
         def build_stub(origin, service: nil, compression: false)
           scheme = @options.ssl.empty? ? "http" : "https"
 
@@ -212,6 +231,8 @@ module HTTPX
           session.with(origin: origin, grpc_service: service, grpc_compression: compression)
         end
 
+        # executes an RPC service identified by +rpc_method+. You're recommended to use the generated
+        # RPC methods directly though, in case you're using #build_stub.
         def execute(rpc_method, input,
                     deadline: DEADLINE,
                     metadata: nil,

data/lib/httpx/plugins/h2c.rb

@@ -68,29 +68,30 @@ module HTTPX
         end
 
         def upgrade_to_h2c(request, response)
-          enqueue_pending_requests_from_parser(@parser)
+          @parser.reset_requests
 
-          @parser = request.options.h2c_class.new(@write_buffer, @options)
+          @parser = request.options.h2c_class.new(@write_buffer, @pending, @options)
           set_parser_callbacks(@parser)
-          @inflight += 1 # request is being completed below
           @parser.upgrade(request, response)
           @upgrade_protocol = "h2c"
         end
 
         private
 
-        def send_request_to_parser(request)
-          super
+        def send_request_to_parser(request, *)
+          super.tap do |is_inflight|
+            next unless is_inflight
 
-          return unless request.headers["upgrade"] == "h2c" && parser.is_a?(Connection::HTTP1)
+            next unless request.headers["upgrade"] == "h2c" && parser.is_a?(Connection::HTTP1)
 
-          max_concurrent_requests = parser.max_concurrent_requests
+            max_concurrent_requests = parser.max_concurrent_requests
 
-          return if max_concurrent_requests == 1
+            next if max_concurrent_requests == 1
 
-          parser.max_concurrent_requests = 1
-          request.once(:response) do
-            parser.max_concurrent_requests = max_concurrent_requests
+            parser.max_concurrent_requests = 1
+            request.once(:response) do
+              parser.max_concurrent_requests = max_concurrent_requests
+            end
           end
         end
       end

data/lib/httpx/plugins/hedging.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module HTTPX
+  module Plugins
+    #
+    # This plugin adds support for request hedging, i.e. a latency-mitigation strategy that involves
+    # sending requests through multiple connections and returning the fastest response.
+    #
+    # https://gitlab.com/os85/httpx/wikis/Hedging#hedging
+    #
+    module Hedging
+      # :hedge_after:: seconds after which, if the request didn't complete yet, it'll be sent on a different connection
+      module OptionsMethods
+        private
+
+        def option_hedge_after(value)
+          if value.respond_to?(:call)
+            value1 = value
+            value1 = value1.method(:call) unless value1.respond_to?(:arity)
+
+            # allow ->(*) arity as well, which is < 0
+            raise TypeError, "`:hedge_after` proc has invalid number of parameters" unless value1.arity.negative? || value1.arity.between?(
+              1, 2
+            )
+
+          else
+            value = Float(value)
+            raise TypeError, "`:hedge_after` must be positive" unless value.positive?
+          end
+
+          value
+        end
+      end
+
+      module InstanceMethods
+        def select_connection(connection, selector)
+          connection.try_yield_hedge_connection do |hedge_conn|
+            super.tap do
+              select_connection(hedge_conn, selector) if hedge_conn
+            end
+          end
+        end
+
+        private
+
+        def do_request(request, connection, selector)
+          super.tap do
+            # forego hedging if the connection is already open, or if
+            # the connection is scheduled for DNS resolution, as pending requests
+            # will be hedged afterwards.
+            next if connection.open? || !connection.addresses?
+
+            hedge_request!(request, connection, selector)
+          end
+        end
+
+        # creates the hedge connection before a connection initiates the connection handshake.
+        # This excludes connections which are already open.
+        def on_resolver_connection(connection, selector)
+          super.tap do
+            next if connection.open? || connection.hedge_connection
+
+            connection.pending.each do |request|
+              hedge_request!(request, connection, selector)
+            end
+
+            on_resolver_connection(connection.hedge_connection, selector) if connection.hedge_connection
+          end
+        end
+
+        def hedge_connection(connection)
+          connection.hedge_connection || begin
+            new_connection = connection.dup
+            new_connection.log { "cloning hedge connection of connection##{connection.object_id}..." }
+            connection.hedge_connection = new_connection
+            new_connection
+          end
+        end
+
+        def hedge_request!(request, connection, selector)
+          hedge_after = when_to_hedge(request)
+
+          if hedge_after&.positive?
+            # hedge after interval
+            cb = selector.after(hedge_after) do
+              next if request.response
+
+              request.hedge_request = hedge_request = request.dup
+              hedge_conn = hedge_connection(connection)
+              hedge_conn.send(hedge_request)
+              select_connection(hedge_conn, selector)
+            end
+
+            # forego hedging if request is over
+            request.once(:response) do
+              cb.cancel
+            end
+          else
+            request.hedge_request = hedge_request = request.dup
+            hedge_connection(connection).send(hedge_request)
+          end
+        end
+
+        def when_to_hedge(request)
+          hedge_after = request.options.hedge_after
+
+          return unless hedge_after
+
+          hedge_after = hedge_after.call(request) if hedge_after.respond_to?(:call)
+
+          hedge_after
+        end
+
+        # hedge connections should not deactivate, instead they should terminate.
+        # this ensures that persistent hedge connections aren't treated as persistent,
+        # and close instead of deactivating.
+        def deactivate(selector, *)
+          hedge_connections = selector.each_connection.select(&:is_hedge_connection)
+
+          return super unless hedge_connections.any?
+
+          selector_close(selector, hedge_connections)
+
+          super
+        end
+
+        # do not check hedge connections back in
+        def can_checkin?(connection)
+          super && !connection.is_hedge_connection
+        end
+      end
+
+      module RequestMethods
+        # TODO: would be nice to get rid of this
+        attr_reader :connection
+
+        attr_reader :hedge_request
+
+        def initialize(*)
+          super
+          @is_hedge_request = false
+        end
+
+        def hedge_request=(request)
+          @hedge_request = request
+
+          return unless request
+
+          @is_hedge_request = !request.hedge_request.nil?
+
+          return if @is_hedge_request
+
+          request.hedge_request = self
+        end
+
+        def response=(response)
+          return super unless @hedge_request # rubocop:disable Lint/ReturnInVoidContext
+
+          prev_response = @response
+
+          begin
+            super
+          ensure
+            @response = prev_response if prev_response
+          end
+        end
+
+        def emit_response(response)
+          hedge_request = @hedge_request
+
+          return super unless hedge_request
+
+          return super unless hedge_request &&
+                              (
+                                hedge_request.response.nil? ||
+                                !hedge_request.response.finished?
+                              )
+
+          # if this response is for a hedge request, and the main request
+          # didn't complete yet, then we replace it.
+
+          super.tap do
+            hedge_request.response = response
+
+            # should cancel any pending HTTP/2 stream; there's no way to
+            # cancel an HTTP/1 request, so that one will run to completion.
+            hedge_request.emit(:refuse)
+          end
+        ensure
+          self.hedge_request = nil
+        end
+      end
+
+      module ResponseMethods
+        def finish!
+          connection = @request.connection
+
+          super
+
+          return unless connection && (hedge_connection = connection.hedge_connection)
+
+          # disconnect connection with its hedge, so that objects do not leak after
+          # they're not needed.
+          connection.hedge_connection = hedge_connection.hedge_connection = nil
+
+          # remarking itself as the main connection, so that it's not discarded when
+          # going back to the pool.
+          connection.is_hedge_connection = false
+          hedge_connection.is_hedge_connection = true
+        end
+      end
+
+      module ConnectionMethods
+        attr_reader :hedge_connection
+
+        attr_accessor :is_hedge_connection
+
+        def initialize(*)
+          super
+          @is_hedge_connection = false
+        end
+
+        def addresses=(addrs)
+          try_yield_hedge_connection do |hedge_conn|
+            super.tap do
+              hedge_conn.addresses = addrs if hedge_conn
+            end
+          end
+        end
+
+        def hedge_connection=(connection)
+          @hedge_connection = connection
+
+          return unless connection
+
+          @is_hedge_connection = !connection.hedge_connection.nil?
+
+          return if @is_hedge_connection
+
+          connection.hedge_connection = self
+        end
+
+        def try_yield_hedge_connection
+          return yield(nil) unless (hedge_conn = @hedge_connection)
+
+          @hedge_connection = nil
+
+          begin
+            hedge_conn.try_yield_hedge_connection do
+              yield(hedge_conn)
+            end
+          ensure
+            @hedge_connection = hedge_conn
+          end
+        end
+
+        # connections should not merge with their hedge connections
+        def mergeable?(connection)
+          super && connection.hedge_connection != self
+        end
+
+        def send(request)
+          super.tap do
+            if @hedge_connection && !request.hedge_request
+              request.hedge_request = hedge_request = request.dup
+              @hedge_connection.send(hedge_request)
+            end
+          end
+        end
+
+        private
+
+        def send_request_to_parser(request, *)
+          # if original request was in the queue, but has since been finished
+          # in the hedge connection.
+          return false if request.response&.finished?
+
+          super
+        end
+      end
+    end
+    register_plugin(:hedging, Hedging)
+  end
+end

data/lib/httpx/plugins/ntlm_auth.rb

@@ -28,6 +28,7 @@ module HTTPX
       end
 
       module InstanceMethods
+        # returns a new session which authenticates requests using NTLM auth.
         def ntlm_auth(user, password, domain = nil)
           with(ntlm: Authentication::Ntlm.new(user, password, domain: domain))
         end
@@ -40,9 +41,10 @@ module HTTPX
 
             if ntlm
               request.authorize(ntlm.negotiate)
-              probe_response = wrap { super(request).first }
+              responses = wrap { super(request) }
+              probe_response = responses.first
 
-              return probe_response unless probe_response.is_a?(Response)
+              return responses unless probe_response.is_a?(Response)
 
               if probe_response.status == 401 && ntlm.can_authenticate?(probe_response.headers["www-authenticate"])
                 request.transition(:idle)
@@ -50,7 +52,7 @@ module HTTPX
                 request.authorize(ntlm.authenticate(request, probe_response.headers["www-authenticate"]).encode("utf-8"))
                 super(request)
               else
-                probe_response
+                responses
               end
             else
               super(request)

data/lib/httpx/plugins/ntlm_v2_auth.rb

@@ -54,6 +54,7 @@ module HTTPX
       end
 
       module InstanceMethods
+        # returns a new session which authenticates requests using NTLM v2 auth.
         def ntlm_auth(user, password, domain = nil)
           with(ntlm: Authenticator.new(user, password, domain: domain))
         end
@@ -66,9 +67,10 @@ module HTTPX
 
             if ntlm
               request.authorize(ntlm.negotiate)
-              probe_response = wrap { super(request).first }
+              responses = wrap { super(request) }
+              probe_response = responses.first
 
-              return probe_response unless probe_response.is_a?(Response)
+              return responses unless probe_response.is_a?(Response)
 
               if probe_response.status == 401 && ntlm.can_authenticate?(probe_response.headers["www-authenticate"])
                 request.transition(:idle)
@@ -77,7 +79,7 @@ module HTTPX
                                                     probe_response.headers["www-authenticate"]).encode("utf-8"))
                 super(request)
               else
-                probe_response
+                responses
               end
             else
               super(request)

data/lib/httpx/plugins/oauth.rb

@@ -290,7 +290,7 @@ module HTTPX
 
         def reset_auth_header_value!
           super.tap do
-            @oauth_session.reset if @oauth_session
+            @oauth_session&.reset!
           end
         end
 
@@ -323,7 +323,7 @@ module HTTPX
         module InstanceMethods
           private
 
-          def prepare_to_retry(_request, response)
+          def prepare_to_retry(*)
             @oauth_session.reset! if @oauth_session
 
             super