[Draft] Android api 21 support

build.gradle

@@ -20,6 +20,8 @@ dependencies {
   implementation 'com.fasterxml.jackson.core:jackson-databind:2.18.3'
   implementation 'com.github.zafarkhaja:java-semver:0.10.2'
   implementation "com.squareup.okhttp3:okhttp:4.12.0"
+  // For base64 that works on on Android API 21
+  implementation "net.iharder:base64:2.3.8"
   // For LRU and expiring maps
   implementation 'org.apache.commons:commons-collections4:4.4'
   implementation 'org.slf4j:slf4j-api:2.0.17'

src/main/java/cloud/eppo/BaseEppoClient.java

@@ -6,6 +6,12 @@
 
 import cloud.eppo.api.*;
 import cloud.eppo.cache.AssignmentCacheEntry;
+import cloud.eppo.json.JacksonMapper;
+import cloud.eppo.json.JacksonMapperNode;
+import cloud.eppo.json.Mapper;
+import cloud.eppo.json.MapperException;
+import cloud.eppo.json.MapperJsonProcessingException;
+import cloud.eppo.json.MapperNode;
 import cloud.eppo.logging.Assignment;
 import cloud.eppo.logging.AssignmentLogger;
 import cloud.eppo.logging.BanditAssignment;
@@ -27,9 +33,7 @@
 
 public class BaseEppoClient {
   private static final Logger log = LoggerFactory.getLogger(BaseEppoClient.class);
-  private final ObjectMapper mapper =
-      new ObjectMapper()
-          .registerModule(EppoModule.eppoModule()); // TODO: is this the best place for this?
+  private final Mapper mapper;
 
   protected final ConfigurationRequestor requestor;
 
@@ -73,6 +77,46 @@ protected BaseEppoClient(
       @Nullable CompletableFuture<Configuration> initialConfiguration,
       @Nullable IAssignmentCache assignmentCache,
       @Nullable IAssignmentCache banditAssignmentCache) {
+    this(
+        new JacksonMapper(),
+        apiKey,
+        sdkName,
+        sdkVersion,
+        host,
+        apiBaseUrl,
+        assignmentLogger,
+        banditLogger,
+        configurationStore,
+        isGracefulMode,
+        expectObfuscatedConfig,
+        supportBandits,
+        initialConfiguration,
+        assignmentCache,
+        banditAssignmentCache
+    );
+  }
+
+  // It is important that the bandit assignment cache expire with a short-enough TTL to last about
+  // one user session.
+  // The recommended is 10 minutes (per @Sven)
+  /** @param host To be removed in v4. use `apiBaseUrl` instead. */
+  protected BaseEppoClient(
+      @NotNull Mapper mapper,
+      @NotNull String apiKey,
+      @NotNull String sdkName,
+      @NotNull String sdkVersion,
+      @Deprecated @Nullable String host,
+      @Nullable String apiBaseUrl,
+      @Nullable AssignmentLogger assignmentLogger,
+      @Nullable BanditLogger banditLogger,
+      @Nullable IConfigurationStore configurationStore,
+      boolean isGracefulMode,
+      boolean expectObfuscatedConfig,
+      boolean supportBandits,
+      @Nullable CompletableFuture<Configuration> initialConfiguration,
+      @Nullable IAssignmentCache assignmentCache,
+      @Nullable IAssignmentCache banditAssignmentCache) {
+    this.mapper = mapper;
 
     if (apiKey == null) {
       throw new IllegalArgumentException("Unable to initialize Eppo SDK due to missing API key");
@@ -436,7 +480,12 @@ public JsonNode getJSONAssignment(
               subjectAttributes,
               EppoValue.valueOf(defaultValue.toString()),
               VariationType.JSON);
-      return parseJsonString(value.stringValue());
+      MapperNode mapperNode = parseJsonString(value.stringValue());
+      if (mapperNode != null) {
+        return ((JacksonMapperNode) mapperNode).getJsonNode();
+      } else {
+        return null;
+      }
     } catch (Exception e) {
       return throwIfNotGraceful(e, defaultValue);
     }
@@ -482,10 +531,10 @@ public String getJSONStringAssignment(String flagKey, String subjectKey, String
     return this.getJSONStringAssignment(flagKey, subjectKey, new Attributes(), defaultValue);
   }
 
-  private JsonNode parseJsonString(String jsonString) {
+  private MapperNode parseJsonString(String jsonString) {
     try {
       return mapper.readTree(jsonString);
-    } catch (JsonProcessingException e) {
+    } catch (MapperJsonProcessingException e) {
       return null;
     }
   }

src/main/java/cloud/eppo/ConfigurationRequestorJava6.java

@@ -0,0 +1,99 @@
+package cloud.eppo;
+
+import org.jetbrains.annotations.NotNull;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
+
+import cloud.eppo.api.Configuration;
+import cloud.eppo.callback.CallbackManager;
+
+public class ConfigurationRequestorJava6 {
+  private static final Logger log = LoggerFactory.getLogger(ConfigurationRequestorJava6.class);
+  private enum ConfigState {
+    UNSET,
+    INITIAL_SET,
+    REMOTE_SET,
+    ;
+  }
+
+  private final EppoHttpClient client;
+  private final IConfigurationStoreJava6 configurationStoreJava6;
+  private final boolean expectObfuscatedConfig;
+  private final boolean supportBandits;
+
+  private final Object configStateLock = new Object();
+  private ConfigState configState;
+
+  private final CallbackManager<Configuration> configChangeManager = new CallbackManager<>();
+
+  public ConfigurationRequestorJava6(
+      @NotNull IConfigurationStoreJava6 configurationStoreJava6,
+      @NotNull EppoHttpClient client,
+      boolean expectObfuscatedConfig,
+      boolean supportBandits) {
+    this.configurationStoreJava6 = configurationStoreJava6;
+    this.client = client;
+    this.expectObfuscatedConfig = expectObfuscatedConfig;
+    this.supportBandits = supportBandits;
+
+    synchronized (configStateLock) {
+      configState = ConfigState.UNSET;
+    }
+  }
+
+  // Synchronously set the initial configuration.
+  public boolean setInitialConfigurationJava6(@NotNull Configuration configuration) {
+    synchronized (configStateLock) {
+      switch(configState) {
+        case UNSET:
+          configState = ConfigState.INITIAL_SET;
+          break;
+        case INITIAL_SET:
+          throw new IllegalStateException("Initial configuration has already been set");
+        case REMOTE_SET:
+          return false;
+      }
+    }
+
+    saveConfigurationAndNotifyJava6(configuration);
+    return true;
+  }
+
+  /** Loads configuration synchronously from the API server. */
+  void fetchAndSaveFromRemoteJava6() {
+    log.debug("Fetching configuration");
+
+    // Reuse the `lastConfig` as its bandits may be useful
+    Configuration lastConfig = configurationStoreJava6.getConfiguration();
+
+    byte[] flagConfigurationJsonBytes = client.getJava6(Constants.FLAG_CONFIG_ENDPOINT);
+    Configuration.Builder configBuilder =
+        Configuration.builder(flagConfigurationJsonBytes, expectObfuscatedConfig)
+            .banditParametersFromConfig(lastConfig);
+
+    if (supportBandits && configBuilder.requiresUpdatedBanditModels()) {
+      byte[] banditParametersJsonBytes = client.getJava6(Constants.BANDIT_ENDPOINT);
+      configBuilder.banditParameters(banditParametersJsonBytes);
+    }
+
+    synchronized (configStateLock) {
+      configState = ConfigState.REMOTE_SET;
+    }
+    saveConfigurationAndNotifyJava6(configBuilder.build());
+  }
+
+  private void saveConfigurationAndNotifyJava6(Configuration configuration) {
+    configurationStoreJava6.saveConfigurationJava6(configuration);
+    synchronized (configChangeManager) {
+      configChangeManager.notifyCallbacks(configuration);
+    }
+  }
+
+  public Runnable onConfigurationChange(Consumer<Configuration> callback) {
+    return configChangeManager.subscribe(callback);
+  }
+}

src/main/java/cloud/eppo/ConfigurationStoreJava6.java

@@ -0,0 +1,24 @@
+package cloud.eppo;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.util.concurrent.CompletableFuture;
+
+import cloud.eppo.api.Configuration;
+
+/** Memory-only configuration store. */
+public class ConfigurationStoreJava6 implements IConfigurationStoreJava6 {
+
+  // this is the fallback value if no configuration is provided (i.e. by fetch or initial config).
+  @NotNull private volatile Configuration configuration = Configuration.emptyConfig();
+
+  public ConfigurationStoreJava6() {}
+
+  public void saveConfigurationJava6(@NotNull final Configuration configuration) {
+    this.configuration = configuration;
+  }
+
+  @NotNull public Configuration getConfiguration() {
+    return configuration;
+  }
+}

src/main/java/cloud/eppo/EppoHttpClient.java

@@ -6,6 +6,8 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
+import java.util.function.Consumer;
+
 import okhttp3.Call;
 import okhttp3.Callback;
 import okhttp3.HttpUrl;
@@ -54,6 +56,43 @@ public byte[] get(String path) {
     }
   }
 
+  public byte[] getJava6(String path) {
+    Request request = buildRequest(path);
+    Call call = client.newCall(request);
+    Response response = null;
+    try {
+      response = call.execute();
+      try {
+        if (response.isSuccessful() && response.body() != null) {
+          log.debug("Fetch successful");
+          return response.body().bytes();
+        } else {
+          if (response.code() == HttpURLConnection.HTTP_FORBIDDEN) {
+            new RuntimeException("Invalid API key");
+          } else {
+            log.debug("Fetch failed with status code: {}", response.code());
+            new RuntimeException("Bad response from URL " + request.url());
+          }
+        }
+      } catch (IOException ex) {
+        new RuntimeException(
+                "Failed to read response from URL {}" + request.url(), ex);
+      } finally {
+        if (response != null) {
+          response.close();
+        }
+      }
+    } catch (IOException e) {
+      log.error(
+          "Http request failure: {} {}",
+          e.getMessage(),
+          Arrays.toString(e.getStackTrace()),
+          e);
+      new RuntimeException("Unable to fetch from URL " + request.url());
+    }
+    throw new RuntimeException("Java compiler not smart enough to know all paths are covered");
+  }
+
   public CompletableFuture<byte[]> getAsync(String path) {
     CompletableFuture<byte[]> future = new CompletableFuture<>();
     Request request = buildRequest(path);

src/main/java/cloud/eppo/IConfigurationStoreJava6.java

@@ -0,0 +1,18 @@
+package cloud.eppo;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Consumer;
+
+import cloud.eppo.api.Configuration;
+
+/**
+ * Common interface for extensions of this SDK to support caching and other strategies for
+ * persisting configuration data across sessions.
+ */
+public interface IConfigurationStoreJava6 {
+  @NotNull Configuration getConfiguration();
+
+  void saveConfigurationJava6(Configuration configuration);
+}

src/main/java/cloud/eppo/Utils.java

@@ -1,12 +1,15 @@
 package cloud.eppo;
 
 import com.fasterxml.jackson.databind.JsonNode;
+
+import net.iharder.Base64;
+
+import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
-import java.util.Base64;
 import java.util.Date;
 import java.util.Locale;
 import org.slf4j.Logger;
@@ -105,14 +108,21 @@ public static String base64Encode(String input) {
     if (input == null) {
       return null;
     }
-    return new String(Base64.getEncoder().encode(input.getBytes(StandardCharsets.UTF_8)));
+    return Base64.encodeBytes(input.getBytes(StandardCharsets.UTF_8));
   }
 
   public static String base64Decode(String input) {
     if (input == null) {
       return null;
     }
-    byte[] decodedBytes = Base64.getDecoder().decode(input);
+    byte[] decodedBytes;
+    try {
+      decodedBytes = Base64.decode(input);
+    } catch (IOException rethrow) {
+      // java.util.Base64 throws IllegalArgumentException
+      // on base64 format errors
+      throw new IllegalArgumentException(rethrow);
+    }
     if (decodedBytes.length == 0 && !input.isEmpty()) {
       throw new RuntimeException(
           "zero byte output from Base64; if not running on Android hardware be sure to use RobolectricTestRunner");