Options Architecture Refactoring - Tracking Issue

[iMacTia]

Options Architecture Refactoring - Tracking Issue

This is the central tracking issue for the Options architecture refactoring work. This epic modernizes Faraday's Options system while maintaining 100% backward compatibility.

📋 Overview

Goal: Detach Options subclasses from Ruby Struct inheritance and introduce a cleaner OOP architecture with BaseOptions and OptionsLike.

Why: Reduce code duplication, improve maintainability, centralize correctness-sensitive logic (nested coercion, deep merging, deep duplication).

Safety: No breaking changes. All existing APIs preserved. This is safe for a minor version release.

📚 Documentation

• Full Technical Plan: docs/options-detach-plan.md
• Original PR: Add RFC document for Options architecture refactoring plan #1644
• Milestone: Options Architecture Refactoring (v2.x)

🗺️ Release Plan

We will release incrementally across 4 minor versions:

• v2.x.0: Foundation (OptionsLike, BaseOptions, Utils.deep_merge! update)
• v2.x.1: Convert ProxyOptions, RequestOptions, SSLOptions
• v2.x.2: Convert ConnectionOptions
• v2.x.3: Convert Env + Documentation (most critical validation)

✅ Task Progress

Prerequisite

• Add comprehensive integration tests using faraday-live approach #1648 - Add comprehensive integration tests using faraday-live approach

Phase 1: Foundation (v2.x.0)

• Foundation: Create OptionsLike module and BaseOptions class #1649 - Create OptionsLike module and BaseOptions class
• Update Utils.deep_merge! to support OptionsLike #1650 - Update Utils.deep_merge! to support OptionsLike

Phase 2: Small Options (v2.x.1)

• Convert ProxyOptions, RequestOptions, SSLOptions to BaseOptions #1651 - Convert ProxyOptions, RequestOptions, SSLOptions to BaseOptions

Phase 3: ConnectionOptions (v2.x.2)

• Convert ConnectionOptions to BaseOptions #1652 - Convert ConnectionOptions to BaseOptions

Phase 4: Env + Docs (v2.x.3)

• Convert Env to BaseOptions (preserve middleware API) #1653 - Convert Env to BaseOptions (preserve middleware API) ⚠️ CRITICAL
• Documentation and deprecation notices for Options refactoring #1654 - Documentation and deprecation notices

🔒 Backward Compatibility Guarantees

1. Existing Faraday::Options class remains untouched
2. All public APIs preserved (merge!, update, to_hash, etc.)
3. Env explicitly preserves [] and []= for middleware compatibility
4. No API removals - everything that works today will continue working

💬 Discussion

Use this issue for questions, progress updates, and coordination. Each sub-issue contains detailed implementation steps.