Convert ConnectionOptions to BaseOptions

[iMacTia]

Convert ConnectionOptions to BaseOptions

Phase: 3 - ConnectionOptions
Release Target: v2.x.2
Tracking Issue: #1647
RFC: docs/options-detach-plan.md

Overview

Convert ConnectionOptions to inherit from BaseOptions instead of Options. This class has nested options (request, ssl) and integrates deeply with Faraday::Connection and Faraday.new.

Current Structure

File: lib/faraday/options/connection_options.rb (23 lines)

• Inherits from Options
• Members: :request, :proxy, :ssl, :builder, :url, :parallel_manager, :params, :headers, :builder_class
• Nested coercion: request → RequestOptions, ssl → SSLOptions
• Has new_builder method that returns builder_class.new
• Default builder_class is RackBuilder

New Structure

# frozen_string_literal: true

module Faraday
  class ConnectionOptions < BaseOptions
    MEMBERS = %i[
      request proxy ssl builder url parallel_manager params headers builder_class
    ].freeze
    
    COERCIONS = {
      request: RequestOptions,
      ssl: SSLOptions
    }.freeze

    attr_accessor :request, :proxy, :ssl, :builder, :url, :parallel_manager,
                  :params, :headers, :builder_class

    def initialize(options = {})
      super(options)
      @builder_class ||= RackBuilder
    end

    def new_builder(block)
      builder_class.new(&block)
    end
  end
end

Implementation Tasks

Core Conversion

• Update class to inherit from BaseOptions
• Define MEMBERS and COERCIONS constants
• Add explicit attr_accessor for all members
• Preserve builder_class default (RackBuilder)
• Preserve new_builder method
• Ensure nested coercion works for request and ssl

Integration Points

• Review lib/faraday/connection.rb usage of ConnectionOptions
• Review lib/faraday.rb (Faraday.new) usage
• Ensure Faraday.default_connection_options integration works
• Test builder instantiation via new_builder

Testing

• Update tests in spec/faraday/options/connection_options_spec.rb
• Test nested options coercion:
  • request hash → RequestOptions
  • ssl hash → SSLOptions
• Test builder_class default
• Test new_builder method
• Test integration with Faraday.new:

  conn = Faraday.new('http://example.com') do |f|
    f.request :url_encoded
    f.adapter :net_http
  end

• Test Faraday.default_connection_options merging
• Run full integration test suite

Critical Integration Areas

1. Faraday.new

# lib/faraday.rb
def self.new(url = nil, options = {}, &block)
  options = ConnectionOptions.from(options)
  # ... uses options.url, options.params, etc.
end

Verify that ConnectionOptions.from works correctly with:

• Hash input
• Existing ConnectionOptions instance
• nil input

2. Connection#initialize

# lib/faraday/connection.rb
def initialize(url = nil, options = {})
  options = ConnectionOptions.from(options)
  # ... uses options for configuration
end

3. Nested Options Usage

# Common pattern in Connection
@options = ConnectionOptions.new(options)
@request_options = @options.request
@ssl = @options.ssl

Ensure that:

• @options.request returns a RequestOptions instance
• @options.ssl returns an SSLOptions instance
• Deep merging preserves nested structure

Files to Modify

• lib/faraday/options/connection_options.rb
• spec/faraday/options/connection_options_spec.rb

Files to Review (Integration Testing)

• lib/faraday/connection.rb
• lib/faraday.rb
• spec/faraday/connection_spec.rb
• spec/faraday_spec.rb

Acceptance Criteria

• ConnectionOptions inherits from BaseOptions
• All existing APIs preserved
• Nested options coercion works correctly
• builder_class default maintained
• new_builder method works
• Faraday.new integration verified
• Faraday.default_connection_options works
• All tests pass (unit + integration)
• No breaking changes detected

Dependencies

• Depends on: Convert ProxyOptions, RequestOptions, SSLOptions to BaseOptions #1651 (RequestOptions and SSLOptions must be converted first)
• Blocks: Convert ConnectionOptions to BaseOptions #1652 (Env conversion can proceed after this)

Backward Compatibility

All existing APIs preserved:

• new_builder method
• builder_class default
• Nested request/ssl coercion
• Integration with Connection and Faraday.new

No breaking changes expected.

Risk Assessment

Risk Level: Medium

Risks:

1. Deep integration with Connection initialization
2. Nested options coercion must work flawlessly
3. Default builder_class behavior must be preserved

Mitigation:

• Comprehensive integration tests
• Review all Connection usage patterns
• Test with real Faraday.new calls
• Validate default_connection_options merging

[iMacTia]

Dependencies: This issue depends on #1651 (RequestOptions and SSLOptions must be converted first for nested coercion).

Blocks: #1653 (Env conversion can proceed after ConnectionOptions is done)