http 5.3.1 → 6.0.0

data/lib/http/timeout/global.rb

@@ -7,104 +7,217 @@ require "http/timeout/null"
 
 module HTTP
   module Timeout
+    # Timeout handler with a single global timeout for the entire request
     class Global < Null
-      def initialize(*args)
+      # I/O wait result symbols returned by non-blocking operations
+      WAIT_RESULTS = %i[wait_readable wait_writable].freeze
+      # Initializes global timeout with options
+      #
+      # @example
+      #   HTTP::Timeout::Global.new(global_timeout: 5)
+      #
+      # @param [Numeric] global_timeout Global timeout in seconds
+      # @param [Numeric, nil] read_timeout Read timeout in seconds
+      # @param [Numeric, nil] write_timeout Write timeout in seconds
+      # @param [Numeric, nil] connect_timeout Connect timeout in seconds
+      # @api public
+      # @return [HTTP::Timeout::Global]
+      def initialize(global_timeout:, read_timeout: nil, write_timeout: nil, connect_timeout: nil)
         super
 
-        @timeout = @time_left = options.fetch(:global_timeout)
+        @timeout = @time_left = global_timeout
+        @read_timeout    = read_timeout
+        @write_timeout   = write_timeout
+        @connect_timeout = connect_timeout
       end
 
-      # To future me: Don't remove this again, past you was smarter.
+      # Resets the time left counter to initial timeout
+      #
+      # @example
+      #   timeout.reset_counter
+      #
+      # @api public
+      # @return [Numeric]
       def reset_counter
         @time_left = @timeout
       end
 
-      def connect(socket_class, host, port, nodelay = false)
+      # Connects to a socket with global timeout
+      #
+      # @example
+      #   timeout.connect(TCPSocket, "example.com", 80)
+      #
+      # @param [Class] socket_class
+      # @param [String] host
+      # @param [Integer] port
+      # @param [Boolean] nodelay
+      # @api public
+      # @return [void]
+      def connect(socket_class, host, port, nodelay: false)
         reset_timer
-        ::Timeout.timeout(@time_left, ConnectTimeoutError) do
-          @socket = socket_class.open(host, port)
-          @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if nodelay
-        end
+        @socket = open_socket(socket_class, host, port, connect_timeout: effective_timeout(@connect_timeout))
+        @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if nodelay
 
         log_time
       end
 
+      # Starts an SSL connection on a socket
+      #
+      # @example
+      #   timeout.connect_ssl
+      #
+      # @api public
+      # @return [void]
       def connect_ssl
         reset_timer
 
         begin
           @socket.connect_nonblock
         rescue IO::WaitReadable
-          wait_readable_or_timeout
+          wait_readable_or_timeout(@connect_timeout)
           retry
         rescue IO::WaitWritable
-          wait_writable_or_timeout
+          wait_writable_or_timeout(@connect_timeout)
           retry
         end
       end
 
       # Read from the socket
+      #
+      # @example
+      #   timeout.readpartial(1024)
+      #
+      # @param [Integer] size
+      # @param [String, nil] buffer
+      # @api public
+      # @return [String, :eof]
       def readpartial(size, buffer = nil)
-        perform_io { read_nonblock(size, buffer) }
+        perform_io(@read_timeout) { read_nonblock(size, buffer) }
       end
 
       # Write to the socket
+      #
+      # @example
+      #   timeout.write("GET / HTTP/1.1")
+      #
+      # @param [String] data
+      # @api public
+      # @return [Integer, :eof]
       def write(data)
-        perform_io { write_nonblock(data) }
+        perform_io(@write_timeout) { write_nonblock(data) }
       end
 
       alias << write
 
       private
 
+      # Reads from socket in non-blocking mode
+      #
+      # @api private
+      # @return [String, Symbol]
       def read_nonblock(size, buffer = nil)
-        @socket.read_nonblock(size, buffer, :exception => false)
+        @socket.read_nonblock(size, buffer, exception: false)
       end
 
+      # Writes to socket in non-blocking mode
+      #
+      # @api private
+      # @return [Integer, Symbol]
       def write_nonblock(data)
-        @socket.write_nonblock(data, :exception => false)
+        @socket.write_nonblock(data, exception: false)
       end
 
-      # Perform the given I/O operation with the given argument
-      def perform_io
+      # Performs I/O operation with timeout tracking
+      #
+      # @param [Numeric, nil] per_op_timeout per-operation timeout limit
+      # @api private
+      # @return [Object]
+      def perform_io(per_op_timeout = nil)
         reset_timer
 
         loop do
           result = yield
+          return handle_io_result(result) unless WAIT_RESULTS.include?(result)
 
-          case result
-          when :wait_readable then wait_readable_or_timeout
-          when :wait_writable then wait_writable_or_timeout
-          when NilClass       then return :eof
-          else                return result
-          end
-        rescue IO::WaitReadable
-          wait_readable_or_timeout
-        rescue IO::WaitWritable
-          wait_writable_or_timeout
+          wait_for_io(result, per_op_timeout)
+        rescue IO::WaitReadable then wait_readable_or_timeout(per_op_timeout)
+        rescue IO::WaitWritable then wait_writable_or_timeout(per_op_timeout)
         end
       rescue EOFError
         :eof
       end
 
-      # Wait for a socket to become readable
-      def wait_readable_or_timeout
-        @socket.to_io.wait_readable(@time_left)
+      # Handles the result of an I/O operation
+      #
+      # @api private
+      # @return [Object, Symbol]
+      def handle_io_result(result)
+        result.nil? ? :eof : result
+      end
+
+      # Waits for an I/O readiness based on the result type
+      #
+      # @param [Symbol] result the I/O wait type
+      # @param [Numeric, nil] per_op_timeout per-operation timeout limit
+      # @api private
+      # @return [void]
+      def wait_for_io(result, per_op_timeout = nil)
+        if result == :wait_readable
+          wait_readable_or_timeout(per_op_timeout)
+        else
+          wait_writable_or_timeout(per_op_timeout)
+        end
+      end
+
+      # Waits for a socket to become readable
+      #
+      # @param [Numeric, nil] per_op per-operation timeout limit
+      # @api private
+      # @return [void]
+      def wait_readable_or_timeout(per_op = nil)
+        timeout = effective_timeout(per_op)
+        result = @socket.to_io.wait_readable(timeout)
         log_time
+
+        raise TimeoutError, "Read timed out after #{per_op} seconds" if per_op && result.nil?
       end
 
-      # Wait for a socket to become writable
-      def wait_writable_or_timeout
-        @socket.to_io.wait_writable(@time_left)
+      # Waits for a socket to become writable
+      #
+      # @param [Numeric, nil] per_op per-operation timeout limit
+      # @api private
+      # @return [void]
+      def wait_writable_or_timeout(per_op = nil)
+        timeout = effective_timeout(per_op)
+        result = @socket.to_io.wait_writable(timeout)
         log_time
+
+        raise TimeoutError, "Write timed out after #{per_op} seconds" if per_op && result.nil?
+      end
+
+      # Computes the effective timeout as the minimum of global and per-operation
+      #
+      # @param [Numeric, nil] per_op_timeout per-operation timeout limit
+      # @api private
+      # @return [Numeric]
+      def effective_timeout(per_op_timeout)
+        return @time_left unless per_op_timeout
+
+        [per_op_timeout, @time_left].min
       end
 
-      # Due to the run/retry nature of nonblocking I/O, it's easier to keep track of time
-      # via method calls instead of a block to monitor.
+      # Resets the I/O timer to current time
+      #
+      # @api private
+      # @return [Time]
       def reset_timer
         @started = Time.now
       end
 
+      # Logs elapsed time and checks for timeout
+      #
+      # @api private
+      # @return [void]
       def log_time
         @time_left -= (Time.now - @started)
         raise TimeoutError, "Timed out after using the allocated #{@timeout} seconds" if @time_left <= 0

data/lib/http/timeout/null.rb

@@ -1,36 +1,112 @@
 # frozen_string_literal: true
 
 require "io/wait"
+require "timeout"
 
 module HTTP
+  # Namespace for timeout handlers
   module Timeout
+    # Base timeout handler with no timeout enforcement
     class Null
-      attr_reader :options, :socket
-
-      def initialize(options = {})
-        @options = options
+      # Whether TCPSocket natively supports connect_timeout and
+      # Happy Eyeballs (RFC 8305). Available in Ruby 3.4+.
+      #
+      # @api private
+      NATIVE_CONNECT_TIMEOUT = RUBY_VERSION >= "3.4"
+
+      # Timeout configuration options
+      #
+      # @example
+      #   timeout.options # => {read_timeout: 5}
+      #
+      # @return [Hash] timeout options
+      # @api public
+      attr_reader :options
+
+      # The underlying socket
+      #
+      # @example
+      #   timeout.socket
+      #
+      # @return [Object] the underlying socket
+      # @api public
+      attr_reader :socket
+
+      # Initializes the null timeout handler
+      #
+      # @example
+      #   HTTP::Timeout::Null.new(read_timeout: 5)
+      #
+      # @param [Numeric, nil] read_timeout Read timeout in seconds
+      # @param [Numeric, nil] write_timeout Write timeout in seconds
+      # @param [Numeric, nil] connect_timeout Connect timeout in seconds
+      # @param [Numeric, nil] global_timeout Global timeout in seconds
+      # @api public
+      # @return [HTTP::Timeout::Null]
+      def initialize(read_timeout: nil, write_timeout: nil, connect_timeout: nil, global_timeout: nil)
+        @options = { read_timeout: read_timeout, write_timeout: write_timeout,
+                     connect_timeout: connect_timeout, global_timeout: global_timeout }.compact
       end
 
       # Connects to a socket
-      def connect(socket_class, host, port, nodelay = false)
-        @socket = socket_class.open(host, port)
+      #
+      # @example
+      #   timeout.connect(TCPSocket, "example.com", 80)
+      #
+      # @param [Class] socket_class
+      # @param [String] host
+      # @param [Integer] port
+      # @param [Boolean] nodelay
+      # @api public
+      # @return [void]
+      def connect(socket_class, host, port, nodelay: false)
+        @socket = open_socket(socket_class, host, port)
         @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if nodelay
       end
 
       # Starts a SSL connection on a socket
+      #
+      # @example
+      #   timeout.connect_ssl
+      #
+      # @api public
+      # @return [void]
       def connect_ssl
         @socket.connect
       end
 
+      # Closes the underlying socket
+      #
+      # @example
+      #   timeout.close
+      #
+      # @api public
+      # @return [void]
       def close
         @socket&.close
       end
 
+      # Checks whether the socket is closed
+      #
+      # @example
+      #   timeout.closed?
+      #
+      # @api public
+      # @return [Boolean]
       def closed?
         @socket&.closed?
       end
 
-      # Configures the SSL connection and starts the connection
+      # Configures the SSL connection and starts it
+      #
+      # @example
+      #   timeout.start_tls("example.com", ssl_class, ssl_ctx)
+      #
+      # @param [String] host
+      # @param [Class] ssl_socket_class
+      # @param [OpenSSL::SSL::SSLContext] ssl_context
+      # @api public
+      # @return [void]
       def start_tls(host, ssl_socket_class, ssl_context)
         @socket = ssl_socket_class.new(socket, ssl_context)
         @socket.hostname = host if @socket.respond_to? :hostname=
@@ -45,6 +121,14 @@ module HTTP
       end
 
       # Read from the socket
+      #
+      # @example
+      #   timeout.readpartial(1024)
+      #
+      # @param [Integer] size
+      # @param [String, nil] buffer
+      # @api public
+      # @return [String, :eof]
       def readpartial(size, buffer = nil)
         @socket.readpartial(size, buffer)
       rescue EOFError
@@ -52,6 +136,13 @@ module HTTP
       end
 
       # Write to the socket
+      #
+      # @example
+      #   timeout.write("GET / HTTP/1.1")
+      #
+      # @param [String] data
+      # @api public
+      # @return [Integer]
       def write(data)
         @socket.write(data)
       end
@@ -59,7 +150,10 @@ module HTTP
 
       private
 
-      # Retry reading
+      # Retries reading on wait readable
+      #
+      # @api private
+      # @return [Object]
       def rescue_readable(timeout = read_timeout)
         yield
       rescue IO::WaitReadable
@@ -67,13 +161,65 @@ module HTTP
         raise TimeoutError, "Read timed out after #{timeout} seconds"
       end
 
-      # Retry writing
+      # Retries writing on wait writable
+      #
+      # @api private
+      # @return [Object]
       def rescue_writable(timeout = write_timeout)
         yield
       rescue IO::WaitWritable
         retry if @socket.to_io.wait_writable(timeout)
         raise TimeoutError, "Write timed out after #{timeout} seconds"
       end
+
+      # Opens a TCP socket, using native connect_timeout when available
+      #
+      # On Ruby 3.4+ with TCPSocket, passes connect_timeout natively to
+      # enable proper Happy Eyeballs (RFC 8305) support. Falls back to
+      # Timeout.timeout on older Rubies or with custom socket classes.
+      #
+      # @param [Class] socket_class socket class to create
+      # @param [String] host remote hostname
+      # @param [Integer] port remote port
+      # @param [Numeric, nil] connect_timeout timeout in seconds
+      # @return [Object] the connected socket
+      # @api private
+      def open_socket(socket_class, host, port, connect_timeout: nil)
+        if connect_timeout
+          ::Timeout.timeout(connect_timeout, ConnectTimeoutError) do
+            open_with_timeout(socket_class, host, port, connect_timeout)
+          end
+        else
+          socket_class.open(host, port)
+        end
+      rescue IO::TimeoutError
+        raise ConnectTimeoutError, "Connect timed out after #{connect_timeout} seconds"
+      end
+
+      # Opens a socket, passing connect_timeout natively when supported
+      #
+      # @param [Class] socket_class socket class to create
+      # @param [String] host remote hostname
+      # @param [Integer] port remote port
+      # @param [Numeric] connect_timeout timeout in seconds
+      # @return [Object] the connected socket
+      # @api private
+      def open_with_timeout(socket_class, host, port, connect_timeout)
+        if native_timeout?(socket_class)
+          socket_class.open(host, port, connect_timeout: connect_timeout)
+        else
+          socket_class.open(host, port)
+        end
+      end
+
+      # Whether the socket class supports native connect_timeout
+      #
+      # @param [Class] socket_class socket class to check
+      # @return [Boolean]
+      # @api private
+      def native_timeout?(socket_class)
+        NATIVE_CONNECT_TIMEOUT && socket_class.is_a?(Class) && socket_class <= TCPSocket
+      end
     end
   end
 end

data/lib/http/timeout/per_operation.rb

@@ -6,26 +6,113 @@ require "http/timeout/null"
 
 module HTTP
   module Timeout
+    # Timeout handler with separate timeouts for connect, read, and write
     class PerOperation < Null
-      CONNECT_TIMEOUT = 0.25
-      WRITE_TIMEOUT = 0.25
-      READ_TIMEOUT = 0.25
+      # Mapping of shorthand option keys to their full forms
+      KEYS = %i[read write connect].to_h { |k| [k, :"#{k}_timeout"] }.freeze
 
-      def initialize(*args)
+      # Normalize and validate timeout options
+      #
+      # @example
+      #   PerOperation.normalize_options(read: 5, write: 3)
+      #
+      # @param [Hash] options timeout options with short or long keys
+      # @return [Hash] normalized options with long keys
+      # @raise [ArgumentError] if options are invalid
+      # @api public
+      def self.normalize_options(options)
+        remaining  = options.dup
+        normalized = {} #: Hash[Symbol, Numeric]
+
+        KEYS.each do |short, long|
+          next if !remaining.key?(short) && !remaining.key?(long)
+
+          normalized[long] = resolve_timeout_value!(remaining, short, long)
+        end
+
+        raise ArgumentError, "unknown timeout options: #{remaining.keys.join(', ')}" unless remaining.empty?
+        raise ArgumentError, "no timeout options given" if normalized.empty?
+
+        normalized
+      end
+
+      # Extract and validate global timeout from options hash
+      #
+      # @example
+      #   extract_global_timeout!({global: 60, read: 5})
+      #
+      # @param [Hash] options mutable options hash (global key is deleted if found)
+      # @return [Numeric, nil] the global timeout value, or nil if not present
+      # @raise [ArgumentError] if both forms given or value is not numeric
+      # @api private
+      private_class_method def self.extract_global_timeout!(options)
+        return unless options.key?(:global) || options.key?(:global_timeout)
+
+        resolve_timeout_value!(options, :global, :global_timeout)
+      end
+
+      # Resolve a single timeout value from the options hash
+      #
+      # @example
+      #   resolve_timeout_value!({read: 5}, :read, :read_timeout)
+      #
+      # @param [Hash] options mutable options hash (keys are deleted as consumed)
+      # @param [Symbol] short short key name (e.g. :read)
+      # @param [Symbol] long long key name (e.g. :read_timeout)
+      # @return [Numeric] the timeout value
+      # @raise [ArgumentError] if both forms given or value is not numeric
+      # @api private
+      private_class_method def self.resolve_timeout_value!(options, short, long)
+        raise ArgumentError, "can't pass both #{short} and #{long}" if options.key?(short) && options.key?(long)
+
+        value = options.delete(options.key?(long) ? long : short)
+
+        raise ArgumentError, "#{long} must be numeric" unless value.is_a?(Numeric)
+
+        value
+      end
+
+      # Initializes per-operation timeout with options
+      #
+      # @example
+      #   HTTP::Timeout::PerOperation.new(read_timeout: 5)
+      #
+      # @param [Numeric, nil] read_timeout Read timeout in seconds (nil for no timeout)
+      # @param [Numeric, nil] write_timeout Write timeout in seconds (nil for no timeout)
+      # @param [Numeric, nil] connect_timeout Connect timeout in seconds (nil for no timeout)
+      # @api public
+      # @return [HTTP::Timeout::PerOperation]
+      def initialize(read_timeout: nil, write_timeout: nil, connect_timeout: nil)
         super
 
-        @read_timeout = options.fetch(:read_timeout, READ_TIMEOUT)
-        @write_timeout = options.fetch(:write_timeout, WRITE_TIMEOUT)
-        @connect_timeout = options.fetch(:connect_timeout, CONNECT_TIMEOUT)
+        @read_timeout = read_timeout
+        @write_timeout = write_timeout
+        @connect_timeout = connect_timeout
       end
 
-      def connect(socket_class, host, port, nodelay = false)
-        ::Timeout.timeout(@connect_timeout, ConnectTimeoutError) do
-          @socket = socket_class.open(host, port)
-          @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if nodelay
-        end
+      # Connects to a socket with connect timeout
+      #
+      # @example
+      #   timeout.connect(TCPSocket, "example.com", 80)
+      #
+      # @param [Class] socket_class
+      # @param [String] host
+      # @param [Integer] port
+      # @param [Boolean] nodelay
+      # @api public
+      # @return [void]
+      def connect(socket_class, host, port, nodelay: false)
+        @socket = open_socket(socket_class, host, port, connect_timeout: @connect_timeout)
+        @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if nodelay
       end
 
+      # Starts an SSL connection with connect timeout
+      #
+      # @example
+      #   timeout.connect_ssl
+      #
+      # @api public
+      # @return [void]
       def connect_ssl
         rescue_readable(@connect_timeout) do
           rescue_writable(@connect_timeout) do
@@ -34,14 +121,25 @@ module HTTP
         end
       end
 
+      # I/O wait result symbols returned by non-blocking operations
+      WAIT_RESULTS = %i[wait_readable wait_writable].freeze
+
       # Read data from the socket
+      #
+      # @example
+      #   timeout.readpartial(1024)
+      #
+      # @param [Integer] size
+      # @param [String, nil] buffer
+      # @api public
+      # @return [String, :eof]
       def readpartial(size, buffer = nil)
         timeout = false
         loop do
-          result = @socket.read_nonblock(size, buffer, :exception => false)
+          result = @socket.read_nonblock(size, buffer, exception: false)
 
           return :eof   if result.nil?
-          return result if result != :wait_readable
+          return result unless WAIT_RESULTS.include?(result)
 
           raise TimeoutError, "Read timed out after #{@read_timeout} seconds" if timeout
 
@@ -55,20 +153,43 @@ module HTTP
           # timeout. Else, the first timeout was a proper timeout.
           # This hack has to be done because io/wait#wait_readable doesn't provide a value for when
           # the socket is closed by the server, and HTTP::Parser doesn't provide the limit for the chunks.
-          timeout = true unless @socket.to_io.wait_readable(@read_timeout)
+          timeout = true unless wait_for_io(result, @read_timeout)
         end
       end
 
       # Write data to the socket
+      #
+      # @example
+      #   timeout.write("GET / HTTP/1.1")
+      #
+      # @param [String] data
+      # @api public
+      # @return [Integer]
       def write(data)
         timeout = false
         loop do
-          result = @socket.write_nonblock(data, :exception => false)
-          return result unless result == :wait_writable
+          result = @socket.write_nonblock(data, exception: false)
+          return result unless WAIT_RESULTS.include?(result)
 
           raise TimeoutError, "Write timed out after #{@write_timeout} seconds" if timeout
 
-          timeout = true unless @socket.to_io.wait_writable(@write_timeout)
+          timeout = true unless wait_for_io(result, @write_timeout)
+        end
+      end
+
+      private
+
+      # Waits for I/O readiness based on the result type
+      #
+      # @param [Symbol] result the I/O wait type (:wait_readable or :wait_writable)
+      # @param [Numeric, nil] timeout per-operation timeout limit
+      # @return [Object, nil] the socket if ready, nil on timeout
+      # @api private
+      def wait_for_io(result, timeout)
+        if result == :wait_readable
+          @socket.to_io.wait_readable(timeout)
+        else
+          @socket.to_io.wait_writable(timeout)
         end
       end
     end