faraday-happy-eyeballs 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 457ecae8f7ee6fe96b4e54ded90e335e3992c9cb7a988f3f8846ea74642b4f76
+  data.tar.gz: d30d85f69685f3e5edf6cc383857c87bd51f1c10013f2325f0198f29a6960f1e
+SHA512:
+  metadata.gz: a447249ce1d028c712a91fb9ee9518157614fb3233f34118d301ac7eac5f17671982b674b958df7df2b6c74bde1f6771fc4e4d934de4a9b58d9f24f364cf91ef
+  data.tar.gz: 205f053fcc3e18b5d2670fee13b73297aa15d9bfa951b968e25681ba1ef1af0f86bbe7bc57178439449427d9b73a194a255f6dc013cc74ed49486bca96f24a78

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,130 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.7
+  SuggestExtensions: false
+  Exclude:
+    - "vendor/**/*"
+    - "pkg/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Metrics/MethodLength:
+  Max: 40
+
+Metrics/AbcSize:
+  Max: 45
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
+Layout/LineLength:
+  Max: 130
+
+Metrics/CyclomaticComplexity:
+  Max: 18
+
+Metrics/PerceivedComplexity:
+  Max: 18
+
+# This codebase intentionally uses a compact, single-space-indent style
+# throughout (not unique to this gem - it's the author's house style across
+# the whole project this gem was extracted from). The cops below are purely
+# about indentation width/alignment and formatting density; disabling them
+# avoids fighting a deliberate, consistently-applied style rather than
+# flagging real bugs or public-API concerns.
+Layout/IndentationWidth:
+  Enabled: false
+Layout/IndentationConsistency:
+  Enabled: false
+Layout/CaseIndentation:
+  Enabled: false
+Layout/AccessModifierIndentation:
+  Enabled: false
+Layout/EndAlignment:
+  Enabled: false
+Layout/DefEndAlignment:
+  Enabled: false
+Layout/BeginEndAlignment:
+  Enabled: false
+Layout/BlockEndNewline:
+  Enabled: false
+Layout/ExtraSpacing:
+  Enabled: false
+Layout/EmptyLineAfterMagicComment:
+  Enabled: false
+Layout/EmptyLinesAroundAccessModifier:
+  Enabled: false
+Layout/RescueEnsureAlignment:
+  Enabled: false
+Layout/FirstHashElementIndentation:
+  Enabled: false
+Layout/HashAlignment:
+  Enabled: false
+Layout/MultilineOperationIndentation:
+  Enabled: false
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+Layout/MultilineHashBraceLayout:
+  Enabled: false
+Layout/SpaceInsideParens:
+  Enabled: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+Layout/EmptyLinesAroundExceptionHandlingKeywords:
+  Enabled: false
+Layout/EmptyLineBetweenDefs:
+  Enabled: false
+Style/TrailingMethodEndStatement:
+  Enabled: false
+Style/SingleLineDoEndBlock:
+  Enabled: false
+Style/SingleLineMethods:
+  Enabled: false
+Style/BlockDelimiters:
+  Enabled: false
+Style/ColonMethodCall:
+  Enabled: false
+Style/CommentedKeyword:
+  Enabled: false
+Style/IfUnlessModifier:
+  Enabled: false
+Style/RescueModifier:
+  Enabled: false
+Style/RescueStandardError:
+  Enabled: false
+Style/ConditionalAssignment:
+  Enabled: false
+Style/TernaryParentheses:
+  Enabled: false
+Style/RedundantBegin:
+  Enabled: false
+Style/RedundantReturn:
+  Enabled: false
+Style/NumericPredicate:
+  Enabled: false
+Style/MapIntoArray:
+  Enabled: false
+Style/SafeNavigation:
+  Enabled: false
+Lint/ScriptPermission:
+  Enabled: false
+Lint/IncompatibleIoSelectWithFiberScheduler:
+  Enabled: false
+
+# `has_connection?` etc. are established public API; renaming to satisfy
+# this cop would be a breaking change for zero functional benefit.
+Naming/PredicatePrefix:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.3.0] - 2026-08-26
+
+### Fixed
+- **Critical**: DNS resolution no longer discards an entire address family once
+  the other family resolves. Previously, if `prefer_ipv6` resolved any AAAA
+  records, all A records were thrown away before the connection race ever
+  ran - so on any host with no real IPv6 route (a very common environment:
+  many corporate networks, VPNs, and containers), every single request
+  failed, even though working IPv4 addresses were available. DNS answering
+  for a family says nothing about whether that family is actually routable;
+  that determination now correctly happens during the connection race, not
+  during resolution.
+- Fixed a file path collision: the adapter previously shipped as
+  `lib/faraday/adapter.rb`, which is the exact path Faraday's own gem uses
+  for its base `Faraday::Adapter` class. Depending on gem load-path
+  ordering, `require "faraday/adapter"` could resolve to this gem's file
+  instead of Faraday's, raising `uninitialized constant Faraday::Adapter`.
+  All adapter/pool/resolver files now live under `lib/faraday/happy_eyeballs/`,
+  matching the module namespace.
+- `dual_stack_resolver.rb`, `adapter.rb`, and `connection_pool.rb` now
+  `require` the stdlib they each use (`resolv`, `timeout`, `socket`,
+  `net/http`, `openssl`) instead of relying on the entry-point file having
+  required them first.
+- Fixed the "stop launching more connection attempts once one succeeds"
+  early-exit, which called `break` inside a `Mutex#synchronize` block - that
+  only exits the `synchronize` block, not the enclosing loop, so every
+  candidate address was still attempted regardless of an earlier success.
+- The connection-attempt wait loop no longer blocks for the full
+  `connection_timeout` when every candidate has already failed; it now
+  exits as soon as no attempt threads remain.
+- `connection_timeout` now actually bounds the real HTTP request
+  (`open_timeout`/`read_timeout`/`write_timeout` on the underlying
+  `Net::HTTP`), not just the Happy Eyeballs connection race. Previously a
+  slow or unresponsive server could hang for `Net::HTTP`'s 60s default
+  regardless of the configured `connection_timeout`.
+- Replaced `http.instance_variable_set(:@ipaddr, ...)` with the public
+  `Net::HTTP#ipaddr=` API for dialing a specific address while keeping the
+  original hostname for SNI/Host.
+
+### Added
+- Connection result caching (`enable_cache`/`cache_ttl`) is now actually
+  wired into the request path. Previously `ConnectionPool` was instantiated
+  but never consulted, so every request re-ran the full DNS + connection
+  race regardless of the option. A cached address that later fails triggers
+  one fresh race rather than a hard failure.
+- DNS resolution results are now cached per-hostname (respecting
+  `cache_ttl`), reusing the previously-unused `@resolution_cache`.
+- `Socket.getaddrinfo`-based direct resolution is now used as a genuine
+  last-resort fallback when manual `Resolv::DNS` A/AAAA lookups return
+  nothing.
+- Test suite (RSpec), Rakefile, `.rspec`, RuboCop config, and a GitHub
+  Actions CI workflow.
+- `LICENSE.txt`.
+
+### Changed
+- `required_ruby_version` corrected from `>= 4.0.0` (a local-machine
+  artifact) to `>= 2.7.0`, matching the README's documented compatibility
+  and the actual syntax used in the gem.
+- Gemspec `homepage`/`source_code_uri`/`changelog_uri` corrected to match
+  the actual repository name (`happy_eye_balls`), which had diverged from
+  the gem name (`faraday-happy-eyeballs`).
+
+## [0.2.0] - 2026-08-20
+- Adjusted CA cert handling for HTTPS requests.
+
+## [0.1.0] - 2025-06-30 to 2025-08-19
+- Initial gem structure, adapter implementation (moved from a Faraday
+  middleware to a Faraday adapter), dual-stack DNS resolution, connection
+  pooling, and debug logging via `DEBUG_HAPPYEYES`.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.0"
+  gem "rubocop", "~> 1.21"
+  gem "webmock", "~> 3.0"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MarkT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+# Faraday Happy Eyeballs
+
+A Faraday adapter that implements the Happy Eyeballs algorithm (RFC 6555) for intelligent IPv4/IPv6 dual-stack connections.
+
+## What is Happy Eyeballs?
+
+Happy Eyeballs (RFC 6555) is an algorithm that makes dual-stack applications (IPv4 and IPv6) more responsive by racing IPv4 and IPv6 connection attempts. Instead of waiting for one protocol to timeout before trying the other, it attempts both simultaneously with intelligent timing to minimize connection delays.
+
+## Features
+
+- **RFC 6555 Compliant**: Implements the official Happy Eyeballs algorithm
+- **Automatic Fallback**: Seamlessly falls back between IPv6 and IPv4
+- **Connection Caching**: Caches successful connection preferences to avoid repeated resolution
+- **Configurable Timing**: Customize connection delays and timeouts
+- **Thread Safety**: Safe for concurrent use
+- **Small Dependency Surface**: Requires Faraday and Ruby standard library
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faraday-happy-eyeballs'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install faraday-happy-eyeballs
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'faraday'
+require 'faraday/happy_eyeballs'
+
+client = Faraday.new('https://example.com') do |faraday|
+  faraday.adapter :happy_eyeballs
+end
+
+response = client.get('/')
+```
+
+### Custom Configuration
+
+```ruby
+client = Faraday.new('https://example.com') do |faraday|
+  faraday.adapter :happy_eyeballs, {
+    connection_attempt_delay: 0.25,  # Delay between connection attempts (seconds)
+    resolution_delay: 0.05,          # Delay between DNS resolutions (seconds)
+    first_address_family_count: 1,   # Number of preferred family addresses to try first
+    connection_timeout: 10,          # Total timeout for all connection attempts
+    cache_ttl: 300,                  # Cache TTL for successful connections (seconds)
+    prefer_ipv6: true,               # Prefer IPv6 addresses (RFC recommendation)
+    enable_cache: true,              # Enable connection result caching
+    ca_file: '/path/to/custom-ca-bundle.pem' # Optional CA bundle for HTTPS
+  }
+end
+
+# The CA file can also be supplied through Faraday's SSL options:
+client = Faraday.new('https://example.com', ssl: {
+  ca_file: '/path/to/custom-ca-bundle.pem'
+}) do |faraday|
+  faraday.adapter :happy_eyeballs
+end
+```
+
+### Stacking with Other Middleware
+
+```ruby
+client = Faraday.new('https://example.com') do |faraday|
+  faraday.use :retry, max: 3
+  faraday.use :gzip
+  faraday.adapter :happy_eyeballs, prefer_ipv6: false
+end
+```
+
+### Twilio Ruby Client
+
+The Twilio constructor does not take Faraday SSL options. Configure the
+Twilio HTTP client before making a request:
+
+```ruby
+twilio = Twilio::REST::Client.new(api_key_sid, api_secret, account_sid)
+
+twilio.http_client.configure_connection do |faraday|
+  faraday.ssl[:ca_file] = '/path/to/custom-ca-bundle.pem'
+end
+
+twilio.http_client.adapter = :happy_eyeballs
+```
+
+For Account SID plus Auth Token authentication, use:
+
+```ruby
+twilio = Twilio::REST::Client.new(account_sid, auth_token)
+twilio.http_client.adapter = :happy_eyeballs
+```
+
+### IPv4-Only Preference
+
+```ruby
+client = Faraday.new('https://example.com') do |faraday|
+  faraday.adapter :happy_eyeballs, {
+    prefer_ipv6: false,              # Prefer IPv4
+    connection_attempt_delay: 0.1,   # Faster attempts for IPv4 preference
+    first_address_family_count: 2    # Try more IPv4 addresses first
+  }
+end
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `connection_attempt_delay` | Float | 0.25 | Delay in seconds between connection attempts |
+| `resolution_delay` | Float | 0.05 | Delay in seconds between IPv6 and IPv4 DNS resolution |
+| `first_address_family_count` | Integer | 1 | Number of preferred address family addresses to try first |
+| `connection_timeout` | Float | 10 | Total timeout in seconds for all connection attempts |
+| `cache_ttl` | Integer | 300 | Time-to-live in seconds for cached connection preferences |
+| `prefer_ipv6` | Boolean | true | Whether to prefer IPv6 addresses (RFC 6555 recommendation) |
+| `enable_cache` | Boolean | true | Whether to cache successful connection results |
+| `ca_file` | String | detected | CA bundle path used for HTTPS certificate verification |
+
+## How It Works
+
+1. **DNS Resolution**: Simultaneously resolves both IPv4 (A) and IPv6 (AAAA) records with a small delay favoring the preferred protocol
+2. **Address Sorting**: Sorts addresses according to preference (IPv6 first by default, as per RFC)
+3. **Connection Racing**: Attempts connections with staggered timing:
+   - Starts with the first address of the preferred family
+   - After a delay, starts attempting alternate addresses
+   - Continues until a connection succeeds or all attempts fail
+4. **HTTP Request**: Uses the successful connection to make the actual HTTP request
+5. **Caching**: Caches successful connection information to speed up future requests
+
+For HTTPS, the adapter preserves the original hostname for SNI and certificate
+hostname verification while dialing the address selected by the connection
+race. Certificate verification remains enabled.
+
+## Error Handling
+
+The adapter raises standard Faraday exceptions:
+
+- `Faraday::ConnectionFailed`: When all connection attempts fail
+- `Faraday::TimeoutError`: When the overall connection timeout is exceeded
+
+```ruby
+begin
+  response = client.get('/')
+rescue Faraday::ConnectionFailed => e
+  puts "All connections failed: #{e.message}"
+rescue Faraday::TimeoutError => e
+  puts "Connection timed out: #{e.message}"
+end
+```
+
+## Performance Considerations
+
+- **First Request**: May be slightly slower due to DNS resolution and connection racing
+- **Subsequent Requests**: Faster due to connection caching
+- **Memory Usage**: Minimal - only caches successful connection metadata
+- **Thread Safety**: Safe for concurrent use across multiple threads
+
+## Compatibility
+
+- **Ruby**: >= 2.7.0
+- **Faraday**: >= 1.0
+- **IPv6 Support**: Requires system IPv6 support for full functionality
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+## Debug
+ export DEBUG_HAPPYEYES='true' # puts progress
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## References
+
+- [RFC 6555: Happy Eyeballs](https://tools.ietf.org/html/rfc6555)
+- [Faraday HTTP Client](https://github.com/lostisland/faraday)

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+rescue LoadError
+  nil
+end
+
+task default: %i[spec rubocop]

data/example_usage.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/happy_eyeballs"
+
+# Example 1: Basic usage with default settings
+puts "=== Basic Happy Eyeballs Example ==="
+
+client = Faraday.new("https://www.google.com") do |faraday|
+ faraday.adapter :happy_eyeballs end
+
+begin
+ response = client.get("/")
+ puts "✓ Connection successful! Status: #{response.status}"
+ puts "✓ Happy Eyeballs automatically chose the fastest IP version"
+rescue => e
+ puts "✗ Connection failed: #{e.message}" end
+
+# Example 2: Custom configuration
+puts "\n=== Custom Configuration Example ==="
+
+client = Faraday.new("https://httpbin.org") do |faraday|
+ faraday.adapter :happy_eyeballs, {
+  connection_attempt_delay: 0.1,    # Faster attempts (100ms instead of 250ms)
+  prefer_ipv6: false,               # Prefer IPv4
+  connection_timeout: 5,            # 5 second total timeout
+  cache_ttl: 600,                   # Cache successful connections for 10 minutes
+  enable_cache: true                # Enable connection caching
+ }
+end
+
+begin
+ response = client.get("/get")
+ puts "✓ Custom configuration successful! Status: #{response.status}"
+rescue => e
+ puts "✗ Connection failed: #{e.message}" end
+
+# Example 3: Multiple requests showing caching
+puts "\n=== Connection Caching Example ==="
+
+client = Faraday.new("https://httpbin.org") do |faraday|
+ faraday.adapter :happy_eyeballs, enable_cache: true end
+
+3.times do |i|
+ begin
+  start_time = Time.now
+  response = client.get("/get")
+  end_time = Time.now
+
+  puts "✓ Request #{i + 1}: Status #{response.status}, Time: #{(end_time - start_time).round(3)}s"
+  puts "  (Subsequent requests should be faster due to caching)"
+ rescue => e
+  puts "✗ Request #{i + 1} failed: #{e.message}" end
+ sleep(1) if i < 2 end
+
+# Example 4: Error handling
+puts "\n=== Error Handling Example ==="
+
+client = Faraday.new("https://nonexistent-domain-12345.com") do |faraday|
+ faraday.adapter :happy_eyeballs end
+
+begin
+response = client.get("/")
+ puts "✓ Unexpected success: #{response.status}"
+ rescue Faraday::ConnectionFailed => e
+  puts "✗ Expected connection failure: #{e.message}"
+ rescue Faraday::TimeoutError => e
+  puts "✗ Expected timeout: #{e.message}"
+ rescue => e
+  puts "✗ Other error: #{e.message}" end
+
+# Example 5: IPv4-only configuration
+puts "\n=== IPv4-Only Configuration Example ==="
+
+client = Faraday.new("https://www.cloudflare.com") do |faraday|
+ faraday.adapter :happy_eyeballs, {
+  prefer_ipv6: false,               # Prefer IPv4
+  connection_attempt_delay: 0.05,   # Very fast IPv4 preference
+  first_address_family_count: 2     # Try 2 IPv4 addresses before IPv6
+ } end
+
+begin
+response = client.get("/")
+puts "✓ IPv4-preferred connection successful! Status: #{response.status}"
+rescue => e
+ puts "✗ Connection failed: #{e.message}" end
+
+# Example 6: Custom CA file
+puts "\n=== Custom CA File Example ==="
+
+client = Faraday.new("https://example.com", ssl: {
+ ca_file: "/path/to/custom-ca-bundle.pem"
+}) do |faraday|
+ faraday.adapter :happy_eyeballs end
+
+# Twilio uses its own Faraday connection. Configure SSL through its HTTP client:
+# twilio = Twilio::REST::Client.new(api_key_sid, api_secret, account_sid)
+# twilio.http_client.configure_connection do |faraday|
+#  faraday.ssl[:ca_file] = '/path/to/custom-ca-bundle.pem' end
+# twilio.http_client.adapter = :happy_eyeballs
+
+puts "\n=== Happy Eyeballs Examples Complete ==="

data/lib/faraday/happy_eyeballs/adapter.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+require "socket"
+require "timeout"
+require "net/http"
+require "openssl"
+module Faraday
+module HappyEyeballs
+class Adapter < Faraday::Adapter
+ NET_HTTP_REQUEST_CLASSES = {
+   "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post, "PUT" => Net::HTTP::Put,
+   "DELETE" => Net::HTTP::Delete, "PATCH" => Net::HTTP::Patch, "HEAD" => Net::HTTP::Head
+ }.freeze
+
+ def initialize(app = nil, options = {})
+  super(app)
+  @options = { connection_attempt_delay: 0.25, resolution_delay: 0.05, first_address_family_count: 1,
+   connection_timeout: 10, cache_ttl: 300, prefer_ipv6: true, enable_cache: true }.merge(options)
+  @connection_pool = ConnectionPool.new(@options) if @options[:enable_cache]
+  @resolver = DualStackResolver.new(@options) end
+
+ def call(env)
+  puts "=== HAPPY EYEBALLS ADAPTER CALLED ===" if ENV["DEBUG_HAPPYEYES"] == "true"
+  puts "Original URL: #{env[:url]}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  uri = env[:url]  # Extract connection details
+  original_hostname = uri.hostname
+  port = uri.port || (uri.scheme == "https" ? 443 : 80)
+  puts "Resolving #{original_hostname}:#{port}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  begin
+  connection_key = "#{original_hostname}:#{port}"
+  successful_address = @connection_pool && @connection_pool.get_connection(connection_key)
+  used_cached_address = !successful_address.nil?
+  unless successful_address
+   # Resolve addresses using your DualStackResolver
+   addresses = @resolver.resolve_dual_stack(original_hostname)
+   raise AllConnectionsFailed, "No addresses resolved for #{original_hostname}" if addresses.empty?
+   sorted_addresses = sort_addresses(addresses) # Sort addresses according to preference
+   successful_address = attempt_connections(sorted_addresses, port)  # Attempt connections with Happy Eyeballs algorithm
+   @connection_pool.cache_connection(connection_key, successful_address) if @connection_pool end
+  begin
+   make_request_with_address(env, successful_address, port) # Make the actual HTTP request with proper SNI
+  rescue Faraday::ConnectionFailed
+   # Only worth a fresh race if the failure came from a stale cached address.
+   raise unless used_cached_address
+   @connection_pool.clear_connection(connection_key)
+   addresses = @resolver.resolve_dual_stack(original_hostname)
+   raise AllConnectionsFailed, "No addresses resolved for #{original_hostname}" if addresses.empty?
+   successful_address = attempt_connections(sort_addresses(addresses), port)
+   @connection_pool.cache_connection(connection_key, successful_address)
+   make_request_with_address(env, successful_address, port) end
+  rescue AllConnectionsFailed, ConnectionTimeout => e
+   raise Faraday::ConnectionFailed, e.message
+  rescue Timeout::Error
+   raise Faraday::TimeoutError, "Connection timeout after #{@options[:connection_timeout]}s" end end
+
+ private
+ def sort_addresses(addresses)
+  if @options[:prefer_ipv6] # IPv6 first, then IPv4
+   ipv6_addrs = addresses.select { |addr| addr[:family] == :ipv6 }
+   ipv4_addrs = addresses.select { |addr| addr[:family] == :ipv4 }
+   ipv6_addrs + ipv4_addrs
+  else # IPv4 first, then IPv6
+   ipv4_addrs = addresses.select { |addr| addr[:family] == :ipv4 }
+   ipv6_addrs = addresses.select { |addr| addr[:family] == :ipv6 }
+   ipv4_addrs + ipv6_addrs end end
+
+ def attempt_connections(addresses, port)
+  successful_address = nil
+  threads = []
+  mutex = Mutex.new
+
+  addresses.each_with_index do |address, index|
+   break if mutex.synchronize { successful_address }
+   sleep(@options[:connection_attempt_delay]) if index > 0
+
+   thread = Thread.new do
+     begin
+       puts "Testing connection: #{address[:ip]}:#{port} (Family: #{address[:family]})" if ENV["DEBUG_HAPPYEYES"] == "true"
+       if test_connection(address[:ip], port, address[:family])
+         mutex.synchronize do
+           if successful_address.nil?
+             successful_address = address
+             puts "Success! Using #{address[:ip]}:#{port}" if ENV["DEBUG_HAPPYEYES"] == "true"
+           end
+         end
+       end
+     rescue => e
+       puts "Connection attempt failed for #{address[:ip]}: #{e.message}" if ENV["DEBUG_HAPPYEYES"] == "true"
+     end
+   end
+
+   threads << thread
+   sleep(0.05) # Small delay to allow threads to start
+  end
+
+  # Wait for first success or all failures
+  start_time = Time.now
+  while successful_address.nil? && (Time.now - start_time) < @options[:connection_timeout]
+    sleep(0.1)
+    threads.reject!(&:alive?)
+    break if threads.empty?
+  end
+
+  # Clean up remaining threads
+  threads.each { |t| t.kill if t.alive? }
+
+  successful_address || raise(AllConnectionsFailed, "All connection attempts failed")
+ end
+
+ def test_connection(ip, port, family)
+ socket = nil
+ begin
+  domain = family == :ipv6 ? Socket::AF_INET6 : Socket::AF_INET
+  socket = Socket.new(domain, Socket::SOCK_STREAM, 0)
+  sockaddr = Socket.sockaddr_in(port, ip)
+
+  puts "Testing connection to #{ip}:#{port} (#{family})" if ENV["DEBUG_HAPPYEYES"] == "true"
+
+  # Set socket to non-blocking mode
+  socket.connect_nonblock(sockaddr)
+  true # Connection succeeded immediately
+ rescue IO::WaitWritable
+  # Connection in progress, wait for completion
+  puts "Connection in progress for #{ip}:#{port}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  if IO.select(nil, [socket], nil, @options[:connection_timeout])
+   begin
+    # Check if connection completed successfully
+    socket.connect_nonblock(sockaddr)
+    true
+   rescue Errno::EISCONN
+    # Already connected - success
+    puts "Connection successful to #{ip}:#{port}" if ENV["DEBUG_HAPPYEYES"] == "true"
+    true
+   rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH => e
+    puts "Connection failed to #{ip}:#{port}: #{e.class}" if ENV["DEBUG_HAPPYEYES"] == "true"
+    false end
+  else
+   puts "Connection timeout to #{ip}:#{port}" if ENV["DEBUG_HAPPYEYES"] == "true"
+   false end
+ rescue Errno::EISCONN
+  # Already connected
+  puts "Already connected to #{ip}:#{port}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  true
+ rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH => e
+  puts "Connection refused to #{ip}:#{port}: #{e.class}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  false
+ rescue => e
+  puts "Unexpected error connecting to #{ip}:#{port}: #{e.class} - #{e.message}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  false
+ ensure
+  socket&.close end end
+
+ def make_request_with_address(env, address, port)
+  original_hostname = env[:url].hostname
+  puts "Making direct Net::HTTP request to #{address[:ip]} with SNI #{original_hostname}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  begin
+  # Keep the hostname for SNI and certificate verification while dialing the
+  # address selected by Happy Eyeballs.
+  http = Net::HTTP.new(original_hostname, port)
+  http.ipaddr = address[:ip]
+  request_timeout = @options[:connection_timeout]
+  http.open_timeout = request_timeout
+  http.read_timeout = request_timeout
+  http.write_timeout = request_timeout if http.respond_to?(:write_timeout=)
+  request = build_net_http_request(env, original_hostname)
+
+  if env[:url].scheme == "https"
+    configure_ssl(http, env)
+    response = http.start { |http_conn| http_conn.request(request) }
+  else
+    response = http.request(request)
+  end
+
+  puts "Response received: #{response.code} #{response.message}" if ENV["DEBUG_HAPPYEYES"] == "true"
+  build_faraday_response(env, response)
+
+  rescue => e
+   puts "Direct Net::HTTP request failed: #{e.class} - #{e.message}" if ENV["DEBUG_HAPPYEYES"] == "true"
+   puts e.backtrace.first(5) if ENV["DEBUG_HAPPYEYES"] == "true"
+   raise Faraday::ConnectionFailed, e.message end end
+
+ def configure_ssl(http, env)
+  http.use_ssl = true
+  http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+  ca_file = @options[:ca_file] || env.dig(:ssl, :ca_file) || ENV["SSL_CERT_FILE"] || ENV["SSL_CA_FILE"] ||
+    ["/etc/ssl/certs/ca-certificates.crt", OpenSSL::X509::DEFAULT_CERT_FILE].find { |path| File.file?(path) }
+  http.ca_file = ca_file if ca_file
+  puts "ca_file => #{ca_file}" if ENV["DEBUG_HAPPYEYES"] == "true" end
+
+ def build_net_http_request(env, hostname)
+  request_class = NET_HTTP_REQUEST_CLASSES.fetch(env[:method].to_s.upcase, Net::HTTP::Get)
+  request = request_class.new(env[:url].request_uri)
+  request["Host"] = hostname
+
+  (env[:request_headers] || {}).each { |key, value| request[key] = value }
+
+  if env[:body] && request.respond_to?(:body=)
+   request.body = env[:body]
+   request["Content-Length"] = env[:body].bytesize.to_s
+  end
+  request end
+
+ def build_faraday_response(env, response)
+  faraday_headers = Faraday::Utils::Headers.new
+  response.each_header { |key, value| faraday_headers[key] = value }
+
+  env[:status] = response.code.to_i
+  env[:response_headers] = faraday_headers
+  env[:body] = response.body
+  Faraday::Response.new(env) end
+
+ def determine_default_adapter # Return Net::HTTP adapter as default, or whatever Faraday's default is
+  Faraday::Adapter::NetHttp end end end end

data/lib/faraday/happy_eyeballs/connection_pool.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+require "socket"
+module Faraday
+module HappyEyeballs
+class ConnectionPool
+ def initialize(options = {})
+   @options = options
+   @connections = {}
+   @connection_mutex = Mutex.new end
+
+ def has_connection?(connection_key)
+   @connection_mutex.synchronize do
+     cached = @connections[connection_key]
+     return false unless cached
+     # Check if cached connection is still valid
+     if Time.now - cached[:timestamp] > @options.fetch(:cache_ttl, 300)
+       @connections.delete(connection_key)
+       return false end
+     # Optionally test if the connection is still alive
+     if @options.fetch(:test_cached_connections, false) then return test_connection_alive(cached[:address]) end
+     true end end
+
+ def cache_connection(connection_key, address)
+   @connection_mutex.synchronize do
+     @connections[connection_key] = {
+       address: address,
+       timestamp: Time.now } end end
+
+ def get_connection(connection_key)
+   @connection_mutex.synchronize do
+     cached = @connections[connection_key]
+     return nil unless cached
+     # Check TTL
+     if Time.now - cached[:timestamp] > @options.fetch(:cache_ttl, 300)
+       @connections.delete(connection_key)
+       return nil end
+     cached[:address] end end
+
+ def clear_connection(connection_key) @connection_mutex.synchronize do @connections.delete(connection_key) end end
+ def clear_all_connections() @connection_mutex.synchronize do @connections.clear end end
+ def connection_count() @connection_mutex.synchronize do @connections.size end end
+ def cleanup_expired_connections # Clean up expired connections
+   current_time = Time.now
+   ttl = @options.fetch(:cache_ttl, 300)
+   @connection_mutex.synchronize do
+     @connections.reject! do |_key, cached| current_time - cached[:timestamp] > ttl end end end
+
+ private
+ def test_connection_alive(address)
+   # This is a lightweight test to see if we can still connect
+   # to the cached address. In a real implementation, you might
+   # want to keep actual socket connections alive.
+   begin
+     socket = nil
+     if address[:family] == :ipv6 then socket = Socket.new(Socket::AF_INET6, Socket::SOCK_STREAM, 0)
+     else socket = Socket.new(Socket::AF_INET, Socket::SOCK_STREAM, 0) end
+     # Quick non-blocking connection test
+     sockaddr = Socket.sockaddr_in(80, address[:ip]) # Default to port 80 for test
+     begin
+       socket.connect_nonblock(sockaddr)
+     rescue IO::WaitWritable, Errno::EISCONN
+       # Connection in progress, or already connected - either is good enough for our test
+       socket.close
+       return true
+     rescue
+       # Connection failed
+       socket.close
+       return false end
+     socket.close
+     true
+   rescue
+     false end end end end end

data/lib/faraday/happy_eyeballs/dual_stack_resolver.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+require "resolv"
+require "timeout"
+require "socket"
+module Faraday
+module HappyEyeballs
+class DualStackResolver
+ def initialize(options = {})
+  @options = options
+  @resolution_cache = {}
+  @cache_mutex = Mutex.new end
+
+ def resolve_dual_stack(hostname)
+  if @options.fetch(:enable_cache, true)
+   cached = cached_addresses(hostname)
+   return cached if cached end
+  addresses = perform_dual_stack_resolution(hostname)
+  addresses = direct_resolution(hostname) if addresses.empty?
+  if @options.fetch(:enable_cache, true) && !addresses.empty?
+   cache_addresses(hostname, addresses) end
+  addresses end
+
+ private
+ def cached_addresses(hostname)
+  @cache_mutex.synchronize do
+   entry = @resolution_cache[hostname]
+   return nil unless entry
+   if Time.now - entry[:timestamp] > @options.fetch(:cache_ttl, 300)
+    @resolution_cache.delete(hostname)
+    return nil end
+   entry[:addresses] end end
+
+ def cache_addresses(hostname, addresses)
+  @cache_mutex.synchronize do
+   @resolution_cache[hostname] = { addresses: addresses, timestamp: Time.now } end end
+ def perform_dual_stack_resolution(hostname)
+  # Resolve both families concurrently (each bounded by its own :dns_timeout
+  # inside resolve_ipv6/resolve_ipv4). We must not discard a resolved family
+  # here: DNS answering for one family says nothing about whether that
+  # family is actually *routable* from this host (e.g. AAAA records exist
+  # but the host has no IPv6 route) - that determination belongs to the
+  # connection race in attempt_connections, not to DNS resolution.
+  ipv6_thread = Thread.new { resolve_ipv6(hostname) }  # Resolution threads
+  sleep(@options.fetch(:resolution_delay, 0.05))       # Small head start for the preferred family
+  ipv4_thread = Thread.new { resolve_ipv4(hostname) }
+  ipv6_addresses = begin ipv6_thread.value || [] rescue []; end
+  ipv4_addresses = begin ipv4_thread.value || [] rescue []; end
+  format_addresses(ipv6_addresses, ipv4_addresses, hostname) end
+
+ def direct_resolution(hostname)  # Last resort: try to resolve directly with Ruby's Socket
+  begin
+  addrs = Socket.getaddrinfo(hostname, nil)
+  results = []
+  addrs.each do |addr|
+   family = (addr[0] == "AF_INET6") ? :ipv6 : :ipv4
+   results << { ip: addr[3], family: family, hostname: hostname } end
+  results
+  rescue
+   [] end end # All resolution methods failed
+
+ def format_addresses(ipv6_addresses, ipv4_addresses, hostname)
+  all_addresses = [] # Format IPv6, IPv4 addresses
+  ipv6_addresses.each do |addr| all_addresses << { ip: addr.to_s, family: :ipv6, hostname: hostname } end
+  ipv4_addresses.each do |addr| all_addresses << { ip: addr.to_s, family: :ipv4, hostname: hostname } end
+  all_addresses end
+
+ def resolve_ipv6(hostname)
+  catch(:resolution_done) do
+   begin
+   Timeout::timeout(@options.fetch(:dns_timeout, 5)) do
+    dns = Resolv::DNS.new
+    results = dns.getresources(hostname, Resolv::DNS::Resource::IN::AAAA).map(&:address)
+    throw :resolution_done, results end
+   rescue Resolv::ResolvError, Timeout::Error
+    throw :resolution_done, [] end
+   [] end end  # Default empty result if we somehow get here
+
+ def resolve_ipv4(hostname)
+  catch(:resolution_done) do
+   begin
+   Timeout::timeout(@options.fetch(:dns_timeout, 5)) do
+    dns = Resolv::DNS.new
+    results = dns.getresources(hostname, Resolv::DNS::Resource::IN::A).map(&:address)
+    throw :resolution_done, results end
+   rescue Resolv::ResolvError, Timeout::Error
+    throw :resolution_done, [] end
+   [] end end end end end  # Default empty result if we somehow get here

data/lib/faraday/happy_eyeballs/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Faraday
+module HappyEyeballs
+VERSION = "0.3.0" end end

data/lib/faraday/happy_eyeballs.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+require "faraday"
+require "socket"
+require "timeout"
+require "resolv"
+require_relative "happy_eyeballs/version"
+require_relative "happy_eyeballs/adapter"
+require_relative "happy_eyeballs/connection_pool"
+require_relative "happy_eyeballs/dual_stack_resolver"
+module Faraday
+module HappyEyeballs
+class Error < StandardError; end
+class ConnectionTimeout < Error; end
+class AllConnectionsFailed < Error; end
+
+# Register the adapter with Faraday
+Faraday::Adapter.register_middleware( happy_eyeballs: -> { Faraday::HappyEyeballs::Adapter }) end end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: faraday-happy-eyeballs
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Claude + MarkT
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Implements Happy Eyeballs algorithm as a Faraday adapter, providing automatic
+  IPv4/IPv6 fallback and dual-stack connection racing
+email:
+- paradisaeidae@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- example_usage.rb
+- lib/faraday/happy_eyeballs.rb
+- lib/faraday/happy_eyeballs/adapter.rb
+- lib/faraday/happy_eyeballs/connection_pool.rb
+- lib/faraday/happy_eyeballs/dual_stack_resolver.rb
+- lib/faraday/happy_eyeballs/version.rb
+homepage: https://github.com/paradisaeidae/happy_eye_balls
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/paradisaeidae/happy_eye_balls
+  source_code_uri: https://github.com/paradisaeidae/happy_eye_balls
+  changelog_uri: https://github.com/paradisaeidae/happy_eye_balls/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Happy Eyeballs (RFC 6555) adapter for Faraday HTTP client
+test_files: []