Add support for OkHttp 5.x compatibility

[castonagentsync]

Summary

Flagsmith Java client 8.0.0 has binary compatibility issues with OkHttp 5.x due to breaking changes introduced in OkHttp 5.0. Projects attempting to upgrade to OkHttp 5.x while using Flagsmith encounter runtime NoClassDefFoundError exceptions.

Current Situation

• Flagsmith 8.0.0 depends on OkHttp 4.12.0
• OkHttp 5.0+ introduced breaking API changes that make it binary incompatible with code compiled against OkHttp 4.x
• Even with dependency exclusions, the runtime fails because Flagsmith's bytecode expects OkHttp 4.x method signatures

Error Details

When using OkHttp 5.3.2 with Flagsmith 8.0.0:

java.lang.NoClassDefFoundError: okhttp3/HttpUrl
    at com.flagsmith.config.FlagsmithConfig.<clinit>(FlagsmithConfig.java:31)

This occurs because:

1. Flagsmith was compiled against OkHttp 4.12.0 APIs
2. OkHttp 5.x has different method signatures/class structures
3. Runtime bytecode incompatibility prevents loading

Impact

This blocks projects from upgrading to:

• OkHttp 5.x (latest is 5.3.2)
• Spring Boot 4.x projects that want latest HTTP client versions
• Modern Java projects seeking to use latest dependencies

Requested Solution

Option A: Dual Compatibility (Preferred)

• Update Flagsmith to support both OkHttp 4.x and 5.x ranges
• Use version ranges in pom.xml: [4.12.0,6.0.0)
• Test against both major versions

Option B: OkHttp 5.x Migration

• Migrate Flagsmith to OkHttp 5.x as minimum version
• Release as major version (9.0.0) due to breaking change
• Update all OkHttp API usage for 5.x compatibility

References

• OkHttp 5.0 Release Notes: Breaking changes documented
• Current Flagsmith pom.xml: Shows explicit OkHttp 4.12.0 dependency
• Spring Boot 4.0: Uses OkHttp 5.x by default

Workaround

Currently, projects must pin OkHttp to 4.12.0 to maintain compatibility:

<!-- Workaround: Pin OkHttp to 4.x for Flagsmith compatibility -->
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>

Priority

Medium-High - This affects modernization efforts for Spring Boot 4.x and Java ecosystem upgrades.