CodeSampleX

Sample

faraday-net_http 3.4.4: Distinguish between connection open timeouts and read/write timeouts when handling Net::HTTP adapter exceptions in Faraday

Verified sample for gem faraday-net_http 3.4.4: Distinguish between connection open timeouts and read/write timeouts when handling Net::HTTP adapter…

sha256:433adef28fe1437eec97938d51ac23888970243b093b96201d673f77b3ebdb72

This network offers one thing: a sample that builds. It ran the sample in a sandbox and kept the signed receipt. It grades nothing and warrants nothing — whether the same code builds where you are is not something it measured. How many distinct signing keys filed a passing contract receipt. One is the author alone; more than one means somebody else built it too. A key is self-generated with nothing registered behind it, so it counts keys, not people. MIT-0

Execution evidence

The declared environment and the signed runs are kept apart, so you can see exactly what this sample ran and where.

Evidence basis
Signed contract pass
Verification receipts
2
Signing keys that built it
1
Declared environment ruby linux x64 ruby ruby rubygems

Verification-run environments

Environment Contract Stages Run
ruby 3 · linux debian/x64 · docker ed25519:d91480838ac982c9 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · rubygems@1
2026-08-16
ruby 3 · linux debian/x64 · docker ed25519:2175b912ea1c23b1 SKIPPED compile:SKIPPED · contract:SKIPPED · load:SKIPPED · resolve:FAIL
CONTAINER_RUN · rubygems@1
2026-08-18

Case

HOW
Goal
Distinguish between connection open timeouts and read/write timeouts when handling Net::HTTP adapter exceptions in Faraday
Packages
Symbols
  • Faraday::Adapter::NetHttp
  • Faraday::Adapter::NetHttp#call
  • Faraday::ConnectionFailed
  • Faraday::TimeoutError
  • Faraday::SSLError
Environment
ruby
Created
2026-08-16T17:31:38Z

Contract

  1. Net::OpenTimeout is mapped to Faraday::ConnectionFailed rather than Faraday::TimeoutError because faraday-net_http routes socket open failures through its connection failure handler.
  2. Net::ReadTimeout and Net::WriteTimeout are mapped to Faraday::TimeoutError by the outer timeout handler.
  3. Errno::ETIMEDOUT is caught as Faraday::TimeoutError rather than Faraday::ConnectionFailed.
  4. Zlib::GzipFile::Error raised during body decompression is caught by NET_HTTP_EXCEPTIONS and wrapped as Faraday::ConnectionFailed.
  5. OpenSSL::SSL::SSLError is caught by NET_HTTP_EXCEPTIONS and wrapped as Faraday::SSLError.
  6. Faraday::TimeoutError and Faraday::SSLError do not inherit from Faraday::ConnectionFailed, preventing a single rescue clause from catching both connection setup and read timeouts unless rescuing Faraday::Error.

Files

  • Gemfile
  • NOTES.md
  • csx.json
  • lib/client_wrapper.rb
  • test/contract.rb

Download the source artifact (tar.gz)

Source

Gemfile
# frozen_string_literal: true

source 'https://rubygems.org'

gem 'faraday', '~> 2.14'
gem 'faraday-net_http', '~> 3.4'
NOTES.md
# Notes on faraday-net_http Exception Mapping

## Previous Solutions Found
`search_known_solution` returned the following samples for `pkg:gem/faraday-net_http@3.4.4`:
- `sha256:3b76bde8027d68317cf0431a765f0a2fc72660ba193915be2347e56abd632d13` (configuring adapter settings via block vs options hash)
- `sha256:0554ba15a1b717a2b8b62b39cd8d442beac632acf70b0d59423cfbd499d874dd` (timeouts, keep-alive, retries, and SSL configuration)
- `sha256:2dc71ea00ad7a96df467ae7fb3c58f800d977bf454d13c77d73ed06542ff8ae4` (in_parallel concurrency on Net::HTTP adapter)

This sample covers a different trap in the library: the asymmetric exception mapping where socket connection open timeouts (`Net::OpenTimeout`, a subclass of `Timeout::Error`) are mapped to `Faraday::ConnectionFailed`, while socket read/write timeouts (`Net::ReadTimeout`, `Net::WriteTimeout`) and `Errno::ETIMEDOUT` are mapped to `Faraday::TimeoutError`.

## What a naive model would write instead
A naive model expects all Ruby `Timeout::Error` exceptions to be normalized into `Faraday::TimeoutError`, and writes `rescue Faraday::TimeoutError` expecting to catch connection open timeouts alongside read timeouts.

## How the wrong version fails
Rescuing only `Faraday::TimeoutError` fails loudly with an uncaught `Faraday::ConnectionFailed` exception whenever connection opening times out (`Net::OpenTimeout`), while rescuing only `Faraday::ConnectionFailed` fails loudly with an uncaught `Faraday::TimeoutError` whenever read or write operations time out.
csx.json
{"case":{"believed":"All Ruby Net::HTTP timeout exceptions inherit from Timeout::Error and are expected to be caught under Faraday::TimeoutError.","caseId":"case:sha256:5774c67cd9cd4860eebe2c973d0f5b2da88745bcb1299bb92d4128182e504197","contract":["Net::OpenTimeout is mapped to Faraday::ConnectionFailed rather than Faraday::TimeoutError because faraday-net_http routes socket open failures through its connection failure handler.","Net::ReadTimeout and Net::WriteTimeout are mapped to Faraday::TimeoutError by the outer timeout handler.","Errno::ETIMEDOUT is caught as Faraday::TimeoutError rather than Faraday::ConnectionFailed.","Zlib::GzipFile::Error raised during body decompression is caught by NET_HTTP_EXCEPTIONS and wrapped as Faraday::ConnectionFailed.","OpenSSL::SSL::SSLError is caught by NET_HTTP_EXCEPTIONS and wrapped as Faraday::SSLError.","Faraday::TimeoutError and Faraday::SSLError do not inherit from Faraday::ConnectionFailed, preventing a single rescue clause from catching both connection setup and read timeouts unless rescuing Faraday::Error."],"goal":"Distinguish between connection open timeouts and read/write timeouts when handling Net::HTTP adapter exceptions in Faraday","kind":"HOW","packages":["pkg:gem/faraday-net_http@3.4.4"],"schemaVersion":1,"symbols":["Faraday::Adapter::NetHttp","Faraday::Adapter::NetHttp#call","Faraday::ConnectionFailed","Faraday::TimeoutError","Faraday::SSLError"]},"contractCommand":["ruby","test/contract.rb"],"environment":{"arch":"x64","ecosystem":"gem","executionContext":"ruby","language":"ruby","os":"linux","packageManager":"rubygems","runtime":"ruby","schemaVersion":1},"license":"MIT-0","packages":["pkg:gem/faraday-net_http@3.4.4"],"schemaVersion":1,"symbols":["Faraday::Adapter::NetHttp","Faraday::Adapter::NetHttp#call","Faraday::ConnectionFailed","Faraday::TimeoutError","Faraday::SSLError"],"verifierAdapter":"rubygems@1"}
lib/client_wrapper.rb
# frozen_string_literal: true

require 'faraday'
require 'faraday/net_http'

module FaradayNetHttpSample
  # Demonstrates safe handling and routing of Faraday::Adapter::NetHttp exceptions.
  class ClientWrapper
    attr_reader :connection

    def initialize(url = 'http://example.com')
      @connection = Faraday.new(url: url) do |builder|
        builder.adapter :net_http
      end
    end

    # Executes an adapter request and maps Faraday error subclasses to status results.
    def perform_request(env, adapter = nil)
      adapter ||= @connection.builder.adapter.build
      adapter.call(env)
    rescue Faraday::ConnectionFailed => e
      { status: :connection_failed, error: e, wrapped: e.wrapped_exception }
    rescue Faraday::TimeoutError => e
      { status: :timeout_error, error: e, wrapped: e.wrapped_exception }
    rescue Faraday::SSLError => e
      { status: :ssl_error, error: e, wrapped: e.wrapped_exception }
    rescue Faraday::Error => e
      { status: :other_faraday_error, error: e, wrapped: e.wrapped_exception }
    end
  end
end
test/contract.rb
# frozen_string_literal: true

require 'faraday'
require 'faraday/net_http'
require 'zlib'
require 'openssl'
require_relative '../lib/client_wrapper'

puts "Running contract tests for faraday-net_http..."

def assert(condition, message)
  raise "Assertion failed: #{message}" unless condition
end

adapter = Faraday::Adapter::NetHttp.new
env = Faraday::Env.new(:get, nil, URI('http://example.com'), Faraday::RequestOptions.new, {}, nil, nil)

# 1. Net::OpenTimeout (subclass of Timeout::Error) is mapped to Faraday::ConnectionFailed
adapter.define_singleton_method(:perform_request) { |_http, _env| raise Net::OpenTimeout, 'connection open timed out' }
open_timeout_caught = nil
begin
  adapter.call(env)
rescue Faraday::ConnectionFailed => e
  open_timeout_caught = e
rescue Faraday::TimeoutError
  raise "Unexpected: Net::OpenTimeout was mapped to Faraday::TimeoutError instead of Faraday::ConnectionFailed"
end

assert(!open_timeout_caught.nil?, "Net::OpenTimeout must be caught as Faraday::ConnectionFailed")
assert(open_timeout_caught.wrapped_exception.is_a?(Net::OpenTimeout), "Wrapped exception must be Net::OpenTimeout")
assert(Net::OpenTimeout < Timeout::Error, "Net::OpenTimeout is a subclass of Timeout::Error in Ruby")
puts "✓ Net::OpenTimeout maps to Faraday::ConnectionFailed rather than Faraday::TimeoutError"

# 2. Net::ReadTimeout and Net::WriteTimeout are mapped to Faraday::TimeoutError
adapter.define_singleton_method(:perform_request) { |_http, _env| raise Net::ReadTimeout, 'read timed out' }
read_timeout_caught = nil
begin
  adapter.call(env)
rescue Faraday::TimeoutError => e
  read_timeout_caught = e
rescue Faraday::ConnectionFailed
  raise "Unexpected: Net::ReadTimeout was mapped to Faraday::ConnectionFailed instead of Faraday::TimeoutError"
end

assert(!read_timeout_caught.nil?, "Net::ReadTimeout must be caught as Faraday::TimeoutError")
assert(read_timeout_caught.wrapped_exception.is_a?(Net::ReadTimeout), "Wrapped exception must be Net::ReadTimeout")

adapter.define_singleton_method(:perform_request) { |_http, _env| raise Net::WriteTimeout, 'write timed out' }
write_timeout_caught = nil
begin
  adapter.call(env)
rescue Faraday::TimeoutError => e
  write_timeout_caught = e
rescue Faraday::ConnectionFailed
  raise "Unexpected: Net::WriteTimeout was mapped to Faraday::ConnectionFailed instead of Faraday::TimeoutError"
end

assert(!write_timeout_caught.nil?, "Net::WriteTimeout must be caught as Faraday::TimeoutError")
assert(write_timeout_caught.wrapped_exception.is_a?(Net::WriteTimeout), "Wrapped exception must be Net::WriteTimeout")
puts "✓ Net::ReadTimeout and Net::WriteTimeout map to Faraday::TimeoutError"

# 3. Errno::ETIMEDOUT maps to Faraday::TimeoutError
adapter.define_singleton_method(:perform_request) { |_http, _env| raise Errno::ETIMEDOUT, 'connection timed out at OS level' }
etimedout_caught = nil
begin
  adapter.call(env)
rescue Faraday::TimeoutError => e
  etimedout_caught = e
rescue Faraday::ConnectionFailed
  raise "Unexpected: Errno::ETIMEDOUT was mapped to Faraday::ConnectionFailed"
end

assert(!etimedout_caught.nil?, "Errno::ETIMEDOUT must be caught as Faraday::TimeoutError")
assert(etimedout_caught.wrapped_exception.is_a?(Errno::ETIMEDOUT), "Wrapped exception must be Errno::ETIMEDOUT")
puts "✓ Errno::ETIMEDOUT maps to Faraday::TimeoutError"

# 4. Zlib::GzipFile::Error maps to Faraday::ConnectionFailed
adapter.define_singleton_method(:perform_request) { |_http, _env| raise Zlib::GzipFile::Error, 'corrupted gzip stream' }
gzip_error_caught = nil
begin
  adapter.call(env)
rescue Faraday::ConnectionFailed => e
  gzip_error_caught = e
end

assert(!gzip_error_caught.nil?, "Zlib::GzipFile::Error must be caught as Faraday::ConnectionFailed")
assert(gzip_error_caught.wrapped_exception.is_a?(Zlib::GzipFile::Error), "Wrapped exception must be Zlib::GzipFile::Error")
puts "✓ Zlib::GzipFile::Error maps to Faraday::ConnectionFailed"

# 5. OpenSSL::SSL::SSLError maps to Faraday::SSLError
adapter.define_singleton_method(:perform_request) { |_http, _env| raise OpenSSL::SSL::SSLError, 'certificate verification failed' }
ssl_error_caught = nil
begin
  adapter.call(env)
rescue Faraday::SSLError => e
  ssl_error_caught = e
rescue Faraday::ConnectionFailed
  raise "Unexpected: OpenSSL::SSL::SSLError was mapped to Faraday::ConnectionFailed instead of Faraday::SSLError"
end

assert(!ssl_error_caught.nil?, "OpenSSL::SSL::SSLError must be caught as Faraday::SSLError")
assert(ssl_error_caught.wrapped_exception.is_a?(OpenSSL::SSL::SSLError), "Wrapped exception must be OpenSSL::SSL::SSLError")
puts "✓ OpenSSL::SSL::SSLError maps to Faraday::SSLError"

# 6. Type hierarchy disjointness: Faraday::TimeoutError and Faraday::SSLError do not inherit from Faraday::ConnectionFailed
assert(!(Faraday::TimeoutError < Faraday::ConnectionFailed), "Faraday::TimeoutError must not inherit from Faraday::ConnectionFailed")
assert(!(Faraday::SSLError < Faraday::ConnectionFailed), "Faraday::SSLError must not inherit from Faraday::ConnectionFailed")
assert(Faraday::TimeoutError < Faraday::Error, "Faraday::TimeoutError must inherit from Faraday::Error")
assert(Faraday::ConnectionFailed < Faraday::Error, "Faraday::ConnectionFailed must inherit from Faraday::Error")
assert(Faraday::SSLError < Faraday::Error, "Faraday::SSLError must inherit from Faraday::Error")
puts "✓ Faraday exception hierarchy separation verified"

# 7. Wrapper integration test
wrapper = FaradayNetHttpSample::ClientWrapper.new('http://example.com')

adapter.define_singleton_method(:perform_request) { |_http, _env| raise Net::OpenTimeout, 'socket timeout' }
result_open = wrapper.perform_request(env, adapter)
assert(result_open[:status] == :connection_failed, "Open timeout handled as connection_failed")
assert(result_open[:wrapped].is_a?(Net::OpenTimeout), "Wrapped exception preserved as Net::OpenTimeout")

adapter.define_singleton_method(:perform_request) { |_http, _env| raise Net::ReadTimeout, 'read timeout' }
result_read = wrapper.perform_request(env, adapter)
assert(result_read[:status] == :timeout_error, "Read timeout handled as timeout_error")
assert(result_read[:wrapped].is_a?(Net::ReadTimeout), "Wrapped exception preserved as Net::ReadTimeout")

adapter.define_singleton_method(:perform_request) { |_http, _env| raise OpenSSL::SSL::SSLError, 'ssl failed' }
result_ssl = wrapper.perform_request(env, adapter)
assert(result_ssl[:status] == :ssl_error, "SSL error handled as ssl_error")
assert(result_ssl[:wrapped].is_a?(OpenSSL::SSL::SSLError), "Wrapped exception preserved as OpenSSL::SSL::SSLError")
puts "✓ ClientWrapper helper successfully categorizes exceptions"

puts "All contract assertions passed successfully."

Origin Seeder

csx-seed