サンプル
faraday-net_http 3.4.4: Distinguish between connection open timeouts and read/write timeouts when handling Net::HTTP adapter exceptions in Faraday
検証済みサンプル — gem faraday-net_http 3.4.4: Distinguish between connection open timeouts and read/write timeouts when handling Net::HTTP adapter exceptions in…
sha256:433adef28fe1437eec97938d51ac23888970243b093b96201d673f77b3ebdb72
このネットワークが提供するのは一つだけです。ビルドされるサンプル。サンドボックスで実行し、署名済みの受領証を保管します。等級はつけず、何も保証しません — 同じコードがあなたの環境でビルドされるかは測定していません。
合格した契約受領証を提出した異なる署名鍵の数です。1 なら作者だけ、2 以上なら他の誰かもビルドしています。鍵は自己生成で背後に登録された身元がないため、数えているのは人ではなく鍵です。
MIT-0
実行証拠
宣言された環境と署名済みの実行を分けてあります。このサンプルが何をどこで実行したかをそのまま確認できます。
- 証拠の基準
- 署名済みコントラクト合格
- 検証レシート
- 2
- ビルドした署名鍵
- 1
宣言された環境
ruby linux x64 ruby ruby rubygems
検証実行環境
| 環境 | コントラクト | ステージ | 実行日 |
|---|---|---|---|
| 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 |
ケース
HOW- ゴール
- Distinguish between connection open timeouts and read/write timeouts when handling Net::HTTP adapter exceptions in Faraday
- パッケージ
- シンボル
-
- Faraday::Adapter::NetHttp
- Faraday::Adapter::NetHttp#call
- Faraday::ConnectionFailed
- Faraday::TimeoutError
- Faraday::SSLError
- 環境
- ruby
- 作成日
- 2026-08-16T17:31:38Z
コントラクト
- 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.
ファイル
- Gemfile
- NOTES.md
- csx.json
- lib/client_wrapper.rb
- test/contract.rb
ソース
# frozen_string_literal: true
source 'https://rubygems.org'
gem 'faraday', '~> 2.14'
gem 'faraday-net_http', '~> 3.4'
# 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.
{"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"}
# 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
# 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."