Enable Happy Eyeballs (RFC 8305)

Leverage Ruby 3.4's native Happy Eyeballs support in TCPSocket by
passing connect_timeout as a keyword argument instead of relying solely
on Timeout.timeout with Thread.raise, which can interfere with the Happy
Eyeballs state machine. On Ruby < 3.4 or with custom socket classes,
falls back to the existing Timeout.timeout behavior.

Extract shared socket opening logic (open_socket, open_with_timeout,
native_timeout?) into the Timeout::Null base class so all timeout
handlers benefit.

Closes #739.

Author: sferik

CHANGELOG.md

@@ -49,6 +49,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   supporting MD5, SHA-256, MD5-sess, and SHA-256-sess algorithms with
   quality-of-protection negotiation. Works as a chainable feature:
   `HTTP.digest_auth(user: "admin", pass: "secret").get(url)` ([#448])
+- Happy Eyeballs (RFC 8305) support via Ruby 3.4's native `TCPSocket`
+  implementation. Connection attempts now try multiple addresses (IPv6 and
+  IPv4) concurrently, improving reliability on dual-stack networks. Connect
+  timeouts are passed natively to `TCPSocket` instead of using
+  `Timeout.timeout`, avoiding `Thread.raise` interference with the Happy
+  Eyeballs state machine. ([#739])
 - `HTTP.base_uri` for setting a base URI that resolves relative request paths
   per RFC 3986. Supports chaining (`HTTP.base_uri("https://api.example.com/v1")
   .get("users")`), and integrates with `persistent` connections by deriving the

lib/http/connection.rb

@@ -47,6 +47,9 @@ class Connection
     def initialize(req, options)
       init_state(options)
       connect_socket(req, options)
+    rescue IO::TimeoutError => e
+      close
+      raise ConnectTimeoutError, e.message, e.backtrace
     rescue IOError, SocketError, SystemCallError => e
       raise ConnectionError, "failed to connect: #{e}", e.backtrace
     rescue TimeoutError

lib/http/timeout/global.rb

@@ -55,10 +55,8 @@ def reset_counter
       # @return [void]
       def connect(socket_class, host, port, nodelay: false)
         reset_timer
-        ::Timeout.timeout(effective_timeout(@connect_timeout), 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

lib/http/timeout/null.rb

@@ -1,12 +1,19 @@
 # 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
+      # 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
@@ -53,7 +60,7 @@ def initialize(read_timeout: nil, write_timeout: nil, connect_timeout: nil, glob
       # @api public
       # @return [void]
       def connect(socket_class, host, port, nodelay: false)
-        @socket = socket_class.open(host, port)
+        @socket = open_socket(socket_class, host, port)
         @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if nodelay
       end
 
@@ -164,6 +171,55 @@ def rescue_writable(timeout = write_timeout)
         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

lib/http/timeout/per_operation.rb

@@ -102,10 +102,8 @@ def initialize(read_timeout: nil, write_timeout: nil, connect_timeout: nil)
       # @api public
       # @return [void]
       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
+        @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

sig/deps.rbs

@@ -91,6 +91,10 @@ module IO::WaitWritable
 end
 
 class IO
+  # Missing from rbs core (available since Ruby 3.2)
+  class TimeoutError < IOError
+  end
+
   class EAGAINWaitReadable < Errno::EAGAIN
     include IO::WaitReadable
   end

sig/http.rbs

@@ -1164,6 +1164,8 @@ module HTTP
 
   module Timeout
     class Null
+      NATIVE_CONNECT_TIMEOUT: bool
+
       attr_reader options: Hash[Symbol, Numeric]
       attr_reader socket: untyped
 
@@ -1183,6 +1185,9 @@ module HTTP
       def write_timeout: () -> Numeric?
       def rescue_readable: (?Numeric? timeout) { () -> untyped } -> untyped
       def rescue_writable: (?Numeric? timeout) { () -> untyped } -> untyped
+      def open_socket: (untyped socket_class, String host, Integer port, ?connect_timeout: Numeric?) -> untyped
+      def open_with_timeout: (untyped socket_class, String host, Integer port, Numeric connect_timeout) -> untyped
+      def native_timeout?: (untyped socket_class) -> bool
     end
 
     class PerOperation < Null

test/http/connection_test.rb

@@ -39,6 +39,21 @@
         HTTP::Connection.new(req, tls_opts)
       end
     end
+
+    it "converts IO::TimeoutError to ConnectTimeoutError" do
+      io_timeout_socket = fake(
+        connect: ->(*) { raise IO::TimeoutError, "Connect timed out!" },
+        close:   nil,
+        closed?: false
+      )
+      io_timeout_class = fake(new: io_timeout_socket)
+      io_opts = HTTP::Options.new(timeout_class: io_timeout_class)
+
+      err = assert_raises(HTTP::ConnectTimeoutError) do
+        HTTP::Connection.new(req, io_opts)
+      end
+      assert_equal "Connect timed out!", err.message
+    end
   end
 
   describe "#read_headers!" do

test/http/timeout/null_test.rb

@@ -155,4 +155,79 @@
       end
     end
   end
+
+  describe "NATIVE_CONNECT_TIMEOUT" do
+    it "is true on Ruby 3.4+" do
+      assert_equal RUBY_VERSION >= "3.4", HTTP::Timeout::Null::NATIVE_CONNECT_TIMEOUT
+    end
+  end
+
+  describe "#open_socket (private)" do
+    it "opens a socket without timeout" do
+      tcp_socket = fake(closed?: false)
+      socket_class = fake(open: tcp_socket)
+
+      result = timeout.send(:open_socket, socket_class, "example.com", 80)
+
+      assert_same tcp_socket, result
+    end
+
+    it "passes connect_timeout natively when native timeout is supported" do
+      received_args = nil
+      stub_open = lambda do |*args, **kwargs|
+        received_args = [args, kwargs]
+        fake(closed?: false)
+      end
+
+      timeout.stub(:native_timeout?, true) do
+        TCPSocket.stub(:open, stub_open) do
+          timeout.send(:open_socket, TCPSocket, "127.0.0.1", 1, connect_timeout: 5)
+        end
+      end
+
+      assert_equal [["127.0.0.1", 1], { connect_timeout: 5 }], received_args
+    end
+
+    it "does not pass connect_timeout to non-TCPSocket classes" do
+      received_args = nil
+      tcp_socket = fake(closed?: false)
+      socket_class = fake(open: proc { |*args|
+        received_args = args
+        tcp_socket
+      })
+
+      timeout.send(:open_socket, socket_class, "example.com", 80, connect_timeout: 5)
+
+      assert_equal ["example.com", 80], received_args
+    end
+
+    it "converts IO::TimeoutError to ConnectTimeoutError" do
+      socket_class = fake(open: proc { |*| raise IO::TimeoutError, "Connect timed out!" })
+
+      err = assert_raises(HTTP::ConnectTimeoutError) do
+        timeout.send(:open_socket, socket_class, "example.com", 80, connect_timeout: 5)
+      end
+      assert_match(/Connect timed out/, err.message)
+    end
+  end
+
+  describe "#native_timeout? (private)" do
+    if RUBY_VERSION >= "3.4"
+      it "returns true for TCPSocket on Ruby 3.4+" do
+        assert timeout.send(:native_timeout?, TCPSocket)
+      end
+    else
+      it "returns false for TCPSocket on Ruby < 3.4" do
+        refute timeout.send(:native_timeout?, TCPSocket)
+      end
+    end
+
+    it "returns false for non-TCPSocket classes" do
+      refute timeout.send(:native_timeout?, OpenSSL::SSL::SSLSocket)
+    end
+
+    it "returns false for non-class objects" do
+      refute timeout.send(:native_timeout?, fake(open: nil))
+    end
+  end
 end