From 40b0ac54d2c6743121f0048565403af19935ceac Mon Sep 17 00:00:00 2001 From: Tyler Potter Date: Mon, 5 Oct 2026 09:59:16 -0600 Subject: [PATCH 1/5] Prepare Java server SDK 6.0.0 with common 4.0.1 Use released common 4.0.1 and framework 0.1.1 test fixtures. Document the v6 API migration and strict-mode malformed-JSON behaviour. Validate Java 8, 11, 17 and 21 with 68 tests per runtime and migration probes; full relay passes 256 cases with two expected skips against published artifacts. --- README.md | 19 +++++++++++++++++++ build.gradle | 6 +++--- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9fd32ef..4cb8482 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,25 @@ dependencies { Refer to our [SDK documentation](https://docs.geteppo.com/sdks/server-sdks/java/) for how to install and use the SDK. +## Upgrading to 6.0.0 + +Version 6.0.0 adopts common SDK 4.0.1. The common SDK is exposed as an API +dependency, so applications that use its types must account for these breaking +changes: + +- Update imports from `cloud.eppo.ufc.dto` to `cloud.eppo.api.dto`. +- `cloud.eppo.EppoHttpClient` has been removed. Integrations that directly use it + must migrate to the v4 HTTP-client API; this is not a drop-in class rename. + +The client also exposes typed `get*AssignmentDetails()` methods and +`getBanditActionDetails()` for inspecting evaluation results. + +Starting in common 4.0.0, strict mode (graceful mode disabled) throws when a JSON +flag contains malformed JSON. Common 3.13.2 returned the supplied non-null default +for this case. Graceful mode continues to return the default. This applies to both +parsed JSON and JSON-string assignments. Common 4.0.1 fixes successful JSON-string +assignments while retaining this strict-mode behaviour. + ## Contributing Java 8 is required to locally compile the SDK. diff --git a/build.gradle b/build.gradle index 04fec14..1f78b13 100644 --- a/build.gradle +++ b/build.gradle @@ -11,7 +11,7 @@ java { } group = 'cloud.eppo' -version = '6.0.0-SNAPSHOT' +version = '6.0.0' ext.isReleaseVersion = !version.endsWith("SNAPSHOT") import org.apache.tools.ant.filters.ReplaceTokens @@ -30,7 +30,7 @@ repositories { } dependencies { - api 'cloud.eppo:sdk-common-jvm:4.0.0-SNAPSHOT' + api 'cloud.eppo:sdk-common-jvm:4.0.1' implementation 'com.github.zafarkhaja:java-semver:0.10.2' implementation 'com.fasterxml.jackson.core:jackson-databind:2.20.1' @@ -39,7 +39,7 @@ dependencies { implementation 'org.jetbrains:annotations:26.1.0' // Logback classic 1.3.x is compatible with java 8 - only needed for tests - testImplementation 'cloud.eppo:eppo-sdk-framework:0.1.0-SNAPSHOT:tests' + testImplementation 'cloud.eppo:eppo-sdk-framework:0.1.1:tests' testImplementation 'ch.qos.logback:logback-classic:1.3.16' testImplementation platform('org.junit:junit-bom:5.11.4') testImplementation 'org.junit.jupiter:junit-jupiter' From 23c484af3448d2edcebdc9694240edbd7db82456 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Wed, 28 Oct 2026 20:57:22 -0400 Subject: [PATCH 2/5] Adopt common 4.0.2 and framework 0.1.2 Common 4.0.2 keeps flags updating when a bandit fetch fails and returns the default value when bandit evaluation fails. Update the dependency pins and the 6.0.0 upgrade notes. Co-Authored-By: Claude Opus 5.5 --- README.md | 11 ++++++++++- build.gradle | 4 ++-- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4cb8482..120b395 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Refer to our [SDK documentation](https://docs.geteppo.com/sdks/server-sdks/java/ ## Upgrading to 6.0.0 -Version 6.0.0 adopts common SDK 4.0.1. The common SDK is exposed as an API +Version 6.0.0 adopts common SDK 4.0.2. The common SDK is exposed as an API dependency, so applications that use its types must account for these breaking changes: @@ -34,6 +34,15 @@ for this case. Graceful mode continues to return the default. This applies to bo parsed JSON and JSON-string assignments. Common 4.0.1 fixes successful JSON-string assignments while retaining this strict-mode behaviour. +Common 4.0.2 changes how the client handles bandit failures: + +- A failed bandit fetch no longer blocks flag updates. The client applies the new + flags, keeps its loaded bandit models, and retries the bandits on the next poll. +- When bandit evaluation fails, for example because the models are not loaded yet, + `getBanditAction` returns the default value with a null action. Common 3.13.2 + returned the bandit variation. `getBanditActionDetails` reports evaluation code + `BANDIT_ERROR`. + ## Contributing Java 8 is required to locally compile the SDK. diff --git a/build.gradle b/build.gradle index 1f78b13..6649bd0 100644 --- a/build.gradle +++ b/build.gradle @@ -30,7 +30,7 @@ repositories { } dependencies { - api 'cloud.eppo:sdk-common-jvm:4.0.1' + api 'cloud.eppo:sdk-common-jvm:4.0.2' implementation 'com.github.zafarkhaja:java-semver:0.10.2' implementation 'com.fasterxml.jackson.core:jackson-databind:2.20.1' @@ -39,7 +39,7 @@ dependencies { implementation 'org.jetbrains:annotations:26.1.0' // Logback classic 1.3.x is compatible with java 8 - only needed for tests - testImplementation 'cloud.eppo:eppo-sdk-framework:0.1.1:tests' + testImplementation 'cloud.eppo:eppo-sdk-framework:0.1.2:tests' testImplementation 'ch.qos.logback:logback-classic:1.3.16' testImplementation platform('org.junit:junit-bom:5.11.4') testImplementation 'org.junit.jupiter:junit-jupiter' From 94bb8570f36dc678326544bf3c521a31ad190482 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Wed, 28 Oct 2026 23:21:59 -0400 Subject: [PATCH 3/5] Document the 6.0.0 upgrade more completely - List the removed common APIs and the DTO package moves, including ShardRange and EppoModule, with a JacksonConfigurationParser example. - Say that the details APIs are new in 6.0.0, and that an unchanged configuration (HTTP 304) no longer calls onConfigurationChange. - Qualify the 4.0.2 bandit-failure note: graceful mode returns the default, strict mode throws, and the assignment logger has already recorded the bandit variation. - Say that snapshots publish only while the version ends in -SNAPSHOT. Co-Authored-By: Claude Opus 5.5 --- README.md | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 120b395..2448801 100644 --- a/README.md +++ b/README.md @@ -21,13 +21,32 @@ Version 6.0.0 adopts common SDK 4.0.2. The common SDK is exposed as an API dependency, so applications that use its types must account for these breaking changes: -- Update imports from `cloud.eppo.ufc.dto` to `cloud.eppo.api.dto`. +- Update imports of the flag and bandit DTOs, for example `VariationType`, + `FlagConfig` and `BanditParameters`, from `cloud.eppo.ufc.dto` to + `cloud.eppo.api.dto`. `cloud.eppo.model.ShardRange` moves to + `cloud.eppo.api.dto.ShardRange`. `cloud.eppo.ufc.dto.adapters.EppoModule` keeps + its package. +- `Configuration.builder(byte[])`, `Configuration.builder(byte[], boolean)`, + `Configuration.serializeFlagConfigToBytes()`, + `Configuration.serializeBanditParamsToBytes()`, + `Attributes.serializeNonNullAttributesToJSONString()` and + `cloud.eppo.exception.InvalidApiKeyException` have been removed. To build a + `Configuration` from flag JSON, use `JacksonConfigurationParser`: + + ```java + JacksonConfigurationParser parser = new JacksonConfigurationParser(); + Configuration config = parser.buildConfig(parser.parseFlagConfig(flagJson), null, null, null); + ``` - `cloud.eppo.EppoHttpClient` has been removed. Integrations that directly use it must migrate to the v4 HTTP-client API; this is not a drop-in class rename. -The client also exposes typed `get*AssignmentDetails()` methods and +Version 6.0.0 adds typed `get*AssignmentDetails()` methods and `getBanditActionDetails()` for inspecting evaluation results. +Polling now sends `If-None-Match`. When the configuration has not changed (HTTP +304), the client keeps its configuration and does not call `onConfigurationChange` +callbacks. 5.x called them after every successful poll. + Starting in common 4.0.0, strict mode (graceful mode disabled) throws when a JSON flag contains malformed JSON. Common 3.13.2 returned the supplied non-null default for this case. Graceful mode continues to return the default. This applies to both @@ -39,9 +58,12 @@ Common 4.0.2 changes how the client handles bandit failures: - A failed bandit fetch no longer blocks flag updates. The client applies the new flags, keeps its loaded bandit models, and retries the bandits on the next poll. - When bandit evaluation fails, for example because the models are not loaded yet, - `getBanditAction` returns the default value with a null action. Common 3.13.2 - returned the bandit variation. `getBanditActionDetails` reports evaluation code - `BANDIT_ERROR`. + graceful mode (the default) makes `getBanditAction` return the default value with + a null action, and `getBanditActionDetails` reports evaluation code `BANDIT_ERROR`. + Common 3.13.2 returned the bandit variation. The assignment logger has already + recorded the flag's bandit variation for that call, so the logged variation can + differ from the value your code receives. With graceful mode disabled, both + methods throw, as in 5.x. ## Contributing @@ -76,7 +98,8 @@ Once you have the prerequisites, follow the steps below to release a new version If you would like to live on the bleeding edge, you can try running against a snapshot build. Keep in mind that snapshots represent the most recent changes on master and may contain bugs. -Snapshots are published automatically after each push to `main` branch. +Snapshots are published automatically after each push to the `main` branch while `build.gradle` has a +`-SNAPSHOT` version. ### build.gradle: @@ -86,6 +109,6 @@ repositories { } dependencies { - implementation 'cloud.eppo:eppo-server-sdk:6.0.0-SNAPSHOT' + implementation 'cloud.eppo:eppo-server-sdk:X.Y.Z-SNAPSHOT' } ``` From 33c1255678799e3966ff72f7c9ea1116fb97c518 Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Wed, 28 Oct 2026 23:22:02 -0400 Subject: [PATCH 4/5] Test bandit fetch recovery and the details APIs Cover common 4.0.2's bandit handling: a failed bandit fetch still applies the flags, bandit flags return the default with BANDIT_ERROR, and the next poll retries the bandits. The test fails against common 4.0.1. Also run the shared assignment cases through the details APIs. Co-Authored-By: Claude Opus 5.5 --- src/test/java/cloud/eppo/EppoClientTest.java | 72 ++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/src/test/java/cloud/eppo/EppoClientTest.java b/src/test/java/cloud/eppo/EppoClientTest.java index 85e0d55..3c54b70 100644 --- a/src/test/java/cloud/eppo/EppoClientTest.java +++ b/src/test/java/cloud/eppo/EppoClientTest.java @@ -2,6 +2,7 @@ import static cloud.eppo.helpers.AssignmentTestCase.parseTestCaseFile; import static cloud.eppo.helpers.AssignmentTestCase.runTestCase; +import static cloud.eppo.helpers.AssignmentTestCase.runTestCaseWithDetails; import static cloud.eppo.helpers.BanditTestCase.parseBanditTestCaseFile; import static cloud.eppo.helpers.BanditTestCase.runBanditTestCase; import static org.junit.jupiter.api.Assertions.*; @@ -122,6 +123,14 @@ public void testUnobfuscatedAssignments(File testFile) { runTestCase(testCase, eppoClient); } + @ParameterizedTest + @MethodSource("getAssignmentTestData") + public void testUnobfuscatedAssignmentsWithDetails(File testFile) { + AssignmentTestCase testCase = parseTestCaseFile(testFile); + EppoClient eppoClient = initClient(DUMMY_FLAG_API_KEY); + runTestCaseWithDetails(testCase, eppoClient); + } + private static Stream getAssignmentTestData() { return AssignmentTestCase.getAssignmentTestData(); } @@ -306,6 +315,69 @@ public void testConfigurationChangeListener() { assertEquals(2, received.size()); } + // The first bandit fetch fails. The flags still apply, bandit flags return the default with + // BANDIT_ERROR, and the next poll sends no ETag, retries the bandits and serves the bandit. + @Test + public void testBanditFetchFailureAppliesFlagsAndRetriesOnNextPoll() { + String flags = readConfig("src/test/resources/shared/ufc/bandit-flags-v1.json"); + String models = readConfig("src/test/resources/shared/ufc/bandit-models-v1.json"); + mockServer.resetAll(); + mockServer.stubFor( + WireMock.get(WireMock.urlMatching(".*flag-config/v1/config.*")) + .withHeader("If-None-Match", WireMock.equalTo("\"v1\"")) + .willReturn(WireMock.aResponse().withStatus(304))); + mockServer.stubFor( + WireMock.get(WireMock.urlMatching(".*flag-config/v1/config.*")) + .withHeader("If-None-Match", WireMock.absent()) + .willReturn(WireMock.okJson(flags).withHeader("ETag", "\"v1\""))); + mockServer.stubFor( + WireMock.get(WireMock.urlMatching(".*flag-config/v1/bandits.*")) + .inScenario("bandits") + .whenScenarioStateIs(Scenario.STARTED) + .willReturn(WireMock.serverError()) + .willSetStateTo("up")); + mockServer.stubFor( + WireMock.get(WireMock.urlMatching(".*flag-config/v1/bandits.*")) + .inScenario("bandits") + .whenScenarioStateIs("up") + .willReturn(WireMock.okJson(models))); + mockAssignmentLogger = mock(AssignmentLogger.class); + mockBanditLogger = mock(BanditLogger.class); + EppoClient client = + EppoClient.builder(DUMMY_BANDIT_API_KEY) + .apiBaseUrl(TEST_HOST) + .assignmentLogger(mockAssignmentLogger) + .banditLogger(mockBanditLogger) + .pollingIntervalMs(0) + .forceReinitialize(true) + .buildAndInit(); + Attributes bob = new Attributes(); + bob.put("age", 25); + bob.put("country", "USA"); + BanditActions actions = new BanditActions(); + actions.put("nike", new Attributes()); + actions.put("adidas", new Attributes()); + + assertNotNull(client.getConfiguration().getFlag("banner_bandit_flag")); + BanditResult fallback = + client.getBanditAction("banner_bandit_flag", "bob", bob, actions, "control"); + assertEquals("control", fallback.getVariation()); + assertNull(fallback.getAction()); + assertEquals( + cloud.eppo.api.FlagEvaluationCode.BANDIT_ERROR, + client + .getBanditActionDetails("banner_bandit_flag", "bob", bob, actions, "control") + .getEvaluationDetails() + .getFlagEvaluationCode()); + verify(mockBanditLogger, never()).logBanditAssignment(any()); + + client.loadConfiguration(); + BanditResult recovered = + client.getBanditAction("banner_bandit_flag", "bob", bob, actions, "control"); + assertEquals("banner_bandit", recovered.getVariation()); + assertNotNull(recovered.getAction()); + } + public static void mockHttpError() { mockServer.stubFor( WireMock.get(WireMock.urlMatching(".*flag-config/v1/config.*")) From 4c386e0863e9cd2372d503257c3e4b1f89bf3b0e Mon Sep 17 00:00:00 2001 From: Aaron Silverman Date: Thu, 29 Oct 2026 00:22:00 -0400 Subject: [PATCH 5/5] Let applications supply their own HTTP client Common 4 takes the configuration client as a constructor dependency, but EppoClient always passed a new OkHttpEppoClient, so 6.0.0 offered no way to replace it. Add Builder.configurationClient, which defaults to OkHttpEppoClient, and document it in the upgrade notes. Co-Authored-By: Claude Opus 5.5 --- README.md | 7 +++++-- src/main/java/cloud/eppo/EppoClient.java | 21 +++++++++++++++++--- src/test/java/cloud/eppo/EppoClientTest.java | 19 ++++++++++++++++++ 3 files changed, 42 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2448801..013e1f8 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,11 @@ changes: JacksonConfigurationParser parser = new JacksonConfigurationParser(); Configuration config = parser.buildConfig(parser.parseFlagConfig(flagJson), null, null, null); ``` -- `cloud.eppo.EppoHttpClient` has been removed. Integrations that directly use it - must migrate to the v4 HTTP-client API; this is not a drop-in class rename. +- `cloud.eppo.EppoHttpClient` has been removed. To supply your own HTTP client, + implement `cloud.eppo.http.EppoConfigurationClient` and pass it to + `EppoClient.builder(sdkKey).configurationClient(...)`. The default is + `OkHttpEppoClient`; pass `new OkHttpEppoClient(okHttpClient)` to reuse your own + OkHttp settings. Version 6.0.0 adds typed `get*AssignmentDetails()` methods and `getBanditActionDetails()` for inspecting evaluation results. diff --git a/src/main/java/cloud/eppo/EppoClient.java b/src/main/java/cloud/eppo/EppoClient.java index b99c473..e366039 100644 --- a/src/main/java/cloud/eppo/EppoClient.java +++ b/src/main/java/cloud/eppo/EppoClient.java @@ -4,6 +4,7 @@ import cloud.eppo.api.IAssignmentCache; import cloud.eppo.cache.ExpiringInMemoryAssignmentCache; import cloud.eppo.cache.LRUInMemoryAssignmentCache; +import cloud.eppo.http.EppoConfigurationClient; import cloud.eppo.logging.AssignmentLogger; import cloud.eppo.logging.BanditLogger; import com.fasterxml.jackson.databind.JsonNode; @@ -46,7 +47,8 @@ private EppoClient( @Nullable BanditLogger banditLogger, boolean isGracefulMode, @Nullable IAssignmentCache assignmentCache, - @Nullable IAssignmentCache banditAssignmentCache) { + @Nullable IAssignmentCache banditAssignmentCache, + @Nullable EppoConfigurationClient configurationClient) { super( sdkKey, sdkName, @@ -62,7 +64,7 @@ private EppoClient( assignmentCache, banditAssignmentCache, new JacksonConfigurationParser(), - new OkHttpEppoClient()); + configurationClient != null ? configurationClient : new OkHttpEppoClient()); } /** @@ -84,6 +86,7 @@ public static class Builder { private long pollingIntervalMs = DEFAULT_POLLING_INTERVAL_MS; private String apiBaseUrl = null; @Nullable private Consumer configChangeCallback; + @Nullable private EppoConfigurationClient configurationClient; // Assignment and bandit caching on by default. To disable, call // `builder.assignmentCache(null).banditAssignmentCache(null);` @@ -169,6 +172,17 @@ public Builder onConfigurationChange(Consumer configChangeCallbac return this; } + /** + * Supplies the HTTP client that fetches configurations, for example to add custom networking, + * authentication or logging. The default is an {@link OkHttpEppoClient}; to reuse your own + * OkHttp settings, pass {@code new OkHttpEppoClient(okHttpClient)}. See {@link + * EppoConfigurationClient} for the contract. + */ + public Builder configurationClient(@NotNull EppoConfigurationClient configurationClient) { + this.configurationClient = configurationClient; + return this; + } + public EppoClient buildAndInit() { AppDetails appDetails = AppDetails.getInstance(); String sdkName = appDetails.getName(); @@ -197,7 +211,8 @@ public EppoClient buildAndInit() { banditLogger, isGracefulMode, assignmentCache, - banditAssignmentCache); + banditAssignmentCache, + configurationClient); if (configChangeCallback != null) { instance.onConfigurationChange(configChangeCallback); diff --git a/src/test/java/cloud/eppo/EppoClientTest.java b/src/test/java/cloud/eppo/EppoClientTest.java index 3c54b70..1e18bc8 100644 --- a/src/test/java/cloud/eppo/EppoClientTest.java +++ b/src/test/java/cloud/eppo/EppoClientTest.java @@ -378,6 +378,25 @@ public void testBanditFetchFailureAppliesFlagsAndRetriesOnNextPoll() { assertNotNull(recovered.getAction()); } + @Test + public void testCustomConfigurationClientIsUsed() { + OkHttpEppoClient delegate = new OkHttpEppoClient(); + List requestedPaths = new ArrayList<>(); + EppoClient eppoClient = + EppoClient.builder(DUMMY_FLAG_API_KEY) + .apiBaseUrl(TEST_HOST) + .configurationClient( + request -> { + requestedPaths.add(request.getResourcePath()); + return delegate.execute(request); + }) + .forceReinitialize(true) + .buildAndInit(); + + assertFalse(requestedPaths.isEmpty()); + assertNotNull(eppoClient.getConfiguration().getFlag("numeric_flag")); + } + public static void mockHttpError() { mockServer.stubFor( WireMock.get(WireMock.urlMatching(".*flag-config/v1/config.*"))