Update Utils.deep_merge! to support OptionsLike

[iMacTia]

Update Utils.deep_merge! to Support OptionsLike

Phase: 1 - Foundation
Release Target: v2.x.0
Tracking Issue: #1647
RFC: docs/options-detach-plan.md

Overview

Update Faraday::Utils.deep_merge! to recognize OptionsLike objects instead of hardcoding checks for Faraday::Options. This enables both legacy Options and new BaseOptions subclasses to work with deep merging.

Current Code

File: lib/faraday/utils.rb (line 103)

if value.is_a?(Hash) && (target[key].is_a?(Hash) || target[key].is_a?(Options))

Proposed Change

if value.is_a?(Hash) && (target_value.is_a?(Hash) || target_value.is_a?(Faraday::OptionsLike))

Why: This allows deep_merge! to work uniformly with:

• Legacy Faraday::Options (which will include OptionsLike)
• New BaseOptions subclasses (which include OptionsLike)
• Any future Options-like classes

Implementation Tasks

• Review current Utils.deep_merge! implementation
• Update the conditional check to use OptionsLike instead of Options
• Update Faraday::Options to include OptionsLike module (for backward compatibility)
• Add tests in spec/faraday/utils_spec.rb covering:
  • Deep merge with legacy Options objects
  • Deep merge with BaseOptions objects (using test subclass)
  • Deep merge with nested Options-like objects
  • Ensure existing behavior unchanged
• Run full test suite
• Integration tests pass (Add comprehensive integration tests using faraday-live approach #1648)

Files to Modify

• lib/faraday/utils.rb (line ~103)
• lib/faraday/options.rb (add include OptionsLike)
• spec/faraday/utils_spec.rb (add/update tests)

Acceptance Criteria

• deep_merge! works with both Options and BaseOptions subclasses
• All existing tests pass
• New tests cover OptionsLike behavior
• No breaking changes to existing code

Dependencies

• Depends on: Foundation: Create OptionsLike module and BaseOptions class #1649 (OptionsLike must exist first)
• Blocks: Update Utils.deep_merge! to support OptionsLike #1650, Convert ProxyOptions, RequestOptions, SSLOptions to BaseOptions #1651, Convert ConnectionOptions to BaseOptions #1652, Convert Env to BaseOptions (preserve middleware API) #1653 (all conversion issues)

Backward Compatibility

This is backward compatible because:

1. Legacy Options will include OptionsLike, so is_a?(OptionsLike) checks will pass
2. The change broadens support rather than restricting it
3. All existing deep_merge! behavior preserved

Testing Strategy

Create a test BaseOptions subclass in the spec to validate:

class TestOptions < Faraday::BaseOptions
  MEMBERS = [:foo, :bar].freeze
  COERCIONS = {}.freeze
  
  attr_accessor :foo, :bar
end

# Test that deep_merge! works with this class

[iMacTia]

Dependencies: This issue depends on #1649 (OptionsLike module must exist first).

Blocks: #1651, #1652, #1653 (all conversion issues require deep_merge! to support OptionsLike)