Configuration Source Extraction part 4/4

[typotter]

📚 Downstream SDK Extensibility Stacked Pull Requests 📚

☑️ Extract DTO interfaces for downstream SDK extensibility (#197)
☑️ Add HTTP ETag-based caching for configuration fetches (#202)
☑️ Extract IConfigurationSource interface for pluggable configuration loading (#203)
👉 Make OkHttp a peer dependency for version flexibility (this PR)

Eppo Internal

🎟️ Enables host applications to control OkHttp version, avoiding dependency conflicts
📜 Design Doc: N/A - Dependency management improvement

Motivation and Context

Currently, OkHttp is bundled with the SDK as an implementation dependency. This causes problems for host applications:

1. Version conflicts: If the app uses a different OkHttp version, both versions end up on the classpath
2. Dependency bloat: SDK bundles OkHttp + Okio + Kotlin stdlib (~2MB overhead)
3. Version lock-in: Apps can't use OkHttp 5.x if SDK bundles 4.x
4. Transitive dependency issues: Okio and Kotlin stdlib version conflicts

By making OkHttp a peer dependency (compileOnly), host applications gain full control over which OkHttp version to use (4.12+, 5.x, or any compatible version).

Description

Change OkHttp from bundled dependency to peer dependency.

build.gradle Changes

// Before
implementation "com.squareup.okhttp3:okhttp:4.12.0"

// After
compileOnly "com.squareup.okhttp3:okhttp:4.12.0"

// For tests - support version override
def okhttpVersion = project.findProperty('okhttpVersion') ?: '4.12.0'
testImplementation "com.squareup.okhttp3:okhttp:${okhttpVersion}"
testImplementation "com.squareup.okhttp3:mockwebserver:${okhttpVersion}"

Impact:

• ✅ Host apps control OkHttp version
• ✅ No version conflicts
• ✅ ~2MB smaller SDK (no bundled OkHttp + transitive deps)
• ⚠️ BREAKING CHANGE: Apps must provide OkHttp dependency

Multi-Version Testing

Added testWithOkHttp5 task:

./gradlew test                                    # Default (4.12.0)
./gradlew test -PokhttpVersion=5.0.0-alpha.14     # Test with 5.x
./gradlew testWithOkHttp5 -PokhttpVersion=5.0.0-alpha.14

Added CI workflow (.github/workflows/okhttp-compatibility.yml):

• Matrix testing with OkHttp 4.12.0 and 5.0.0-alpha.14
• Automatic validation on every PR
• Parallel execution for faster feedback

Migration Guide (MIGRATION_V3_TO_V4.md)

Created comprehensive migration guide with:

• Step-by-step migration instructions for Gradle and Maven
• Explanation of why this change was made
• Troubleshooting common issues
• OkHttp version compatibility information
• Rollback instructions if needed

Updated README

Added dependencies section documenting:

• OkHttp is now a peer dependency
• Supported versions: 4.12+ and 5.x
• Installation examples for both Gradle and Maven
• Link to migration guide

How has this been documented?

• MIGRATION_V3_TO_V4.md: Complete migration guide with examples
• README.md: Updated with dependency requirements
• CI workflow: Documents testing strategy
• Clear error messages when OkHttp is missing

How has this been tested?

Multi-Version Testing

# Test with OkHttp 4.12.0
./gradlew test

✅ All 249 tests passing

# Test with OkHttp 5.x
./gradlew test -PokhttpVersion=5.0.0-alpha.14

✅ All 249 tests passing

Verified Scenarios

1. Default behavior: Tests pass with OkHttp on test classpath
2. OkHttp 4.12.0: Full compatibility verified
3. OkHttp 5.x: Full compatibility verified (uses only stable APIs)
4. Both versions work: No code changes needed between 4.x and 5.x

OkHttp Compatibility

The SDK uses only basic OkHttp APIs that are stable across versions:

• OkHttpClient, OkHttpClient.Builder - Same in both
• Request, Response, Call, Callback - Same in both
• HttpUrl - Same in both
• connectTimeout(), readTimeout() - Available in both

Result: Works with both OkHttp 4.12+ and 5.x without modifications.

Migration Example

Before (v3.x):

dependencies {
  implementation 'cloud.eppo:sdk-common-jvm:3.13.2'
  // OkHttp bundled automatically
}

After (v4.0):

dependencies {
  implementation 'cloud.eppo:sdk-common-jvm:4.0.0'
  implementation 'com.squareup.okhttp3:okhttp:4.12.0'  // ADD THIS
}

Code: No changes needed!

Stack Context

BREAKING CHANGE: This is the only breaking change in the stack.

This PR builds on:

• PR Configuration Source Extraction part 1/4 #197: Uses DTO interfaces
• PR Configuration Source Extraction part 2/4 #202: Preserves eTag caching
• PR Configuration Source Extraction part 3/4 #203: Works with IConfigurationSource (OkHttpConfigurationSource uses OkHttp from classpath)

Combined stack enables:

1. ✅ Custom DTO implementations (PR Configuration Source Extraction part 1/4 #197)
2. ✅ HTTP caching optimization (PR Configuration Source Extraction part 2/4 #202)
3. ✅ Custom configuration sources (PR Configuration Source Extraction part 3/4 #203)
4. ✅ Flexible OkHttp version management (PR Configuration Source Extraction part 4/4 #204 - this PR)

Result: Downstream SDKs have complete control over DTOs, configuration loading, AND HTTP client version.

[Copilot]

Pull request overview

This PR makes OkHttp a peer dependency instead of bundling it with the SDK, allowing host applications to control the OkHttp version they use. This is the final PR in a stack focused on downstream SDK extensibility.

Changes:

• Changed OkHttp from implementation to compileOnly dependency in build.gradle
• Added CI workflow for testing compatibility with OkHttp 4.12.0 and 5.0.0-alpha.14
• Created comprehensive migration guide (MIGRATION_V3_TO_V4.md) with step-by-step instructions
• Updated README with dependency requirements and usage examples

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File	Description
README.md	Added dependencies section documenting OkHttp as a peer dependency with version requirements and usage examples
MIGRATION_V3_TO_V4.md	New migration guide explaining the breaking change and providing detailed migration steps for Gradle and Maven
.github/workflows/okhttp-compatibility.yml	New CI workflow to test compatibility with both OkHttp 4.12.0 and 5.0.0-alpha.14

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The condition syntax is incorrect for GitHub Actions. The job.status context should be accessed without dollar signs and braces inside the bracket expression. Change to if [ "${{ job.status }}" == "success" ]; then with proper quoting.

Suggested change

	if [ ${{ job.status }} == 'success' ]; then
	if [ "${{ job.status }}" == "success" ]; then

[Copilot]

The comment suggests this version should be updated as 5.x stabilizes, but there's no mechanism to ensure this happens. Consider adding a comment about checking for newer versions periodically or linking to OkHttp's release page for tracking updates.

Suggested change

	- '5.0.0-alpha.14' # Latest 5.x alpha (update as 5.x stabilizes)
	- '5.0.0-alpha.14' # Latest 5.x alpha as of 2024-01; periodically check https://github.com/square/okhttp/releases for newer 5.x versions