fix(analytics): allow capability to offload reportExposure to async thread (#85)

Author: tylerjroach

src/main/java/com/mixpanel/mixpanelapi/MixpanelAPI.java

@@ -10,6 +10,7 @@
 import java.net.URLConnection;
 import java.net.URLEncoder;
 import java.util.List;
+import java.util.concurrent.Executor;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import java.util.zip.GZIPOutputStream;
@@ -663,16 +664,42 @@ public RemoteFlagsProvider getRemoteFlags() {
     /**
      * Creates an EventSender that uses the provided MixpanelAPI instance for sending events.
      * This is shared by both local and remote flag evaluation modes.
+     * <p>
+     * If the config provides a non-null exposure executor, the HTTP send is dispatched on
+     * the executor so flag evaluation does not block on network I/O. JSON construction
+     * always runs on the calling thread because {@link MessageBuilder} is not thread-safe.
+     * </p>
      */
     private static EventSender createEventSender(BaseFlagsConfig config, MixpanelAPI api) {
         final MessageBuilder builder = new MessageBuilder(config.getProjectToken());
+        final Executor exposureExecutor = config.getExposureExecutor();
 
         return (distinctId, eventName, properties) -> {
+            final JSONObject event;
             try {
-                JSONObject event = builder.event(distinctId, eventName, properties);
-                api.sendMessage(event);
-            } catch (IOException e) {
-                // Silently fail - exposure tracking should not break flag evaluation
+                event = builder.event(distinctId, eventName, properties);
+            } catch (RuntimeException e) {
+                logger.log(Level.WARNING, "Failed to build exposure event " + eventName, e);
+                return;
+            }
+
+            Runnable send = () -> {
+                try {
+                    api.sendMessage(event);
+                } catch (IOException e) {
+                    logger.log(Level.WARNING, "Failed to send exposure event " + eventName, e);
+                }
+            };
+
+            if (exposureExecutor == null) {
+                send.run();
+                return;
+            }
+
+            try {
+                exposureExecutor.execute(send);
+            } catch (Exception e) {
+                logger.log(Level.WARNING, "Exposure event dropped — executor failed to accept task for " + eventName, e);
             }
         };
     }

src/main/java/com/mixpanel/mixpanelapi/featureflags/config/BaseFlagsConfig.java

@@ -1,5 +1,7 @@
 package com.mixpanel.mixpanelapi.featureflags.config;
 
+import java.util.concurrent.Executor;
+
 /**
  * Base configuration for feature flags providers.
  * <p>
@@ -10,18 +12,21 @@ public class BaseFlagsConfig {
     private final String projectToken;
     private final String apiHost;
     private final int requestTimeoutSeconds;
+    private final Executor exposureExecutor;
 
     /**
      * Creates a new BaseFlagsConfig with specified settings.
      *
      * @param projectToken the Mixpanel project token
      * @param apiHost the API endpoint host
      * @param requestTimeoutSeconds HTTP request timeout in seconds
+     * @param exposureExecutor executor used to dispatch exposure event HTTP sends; may be null
      */
-    protected BaseFlagsConfig(String projectToken, String apiHost, int requestTimeoutSeconds) {
+    protected BaseFlagsConfig(String projectToken, String apiHost, int requestTimeoutSeconds, Executor exposureExecutor) {
         this.projectToken = projectToken;
         this.apiHost = apiHost;
         this.requestTimeoutSeconds = requestTimeoutSeconds;
+        this.exposureExecutor = exposureExecutor;
     }
 
     /**
@@ -45,6 +50,13 @@ public int getRequestTimeoutSeconds() {
         return requestTimeoutSeconds;
     }
 
+    /**
+     * @return the Executor used to dispatch exposure event HTTP sends, or null for synchronous dispatch
+     */
+    public Executor getExposureExecutor() {
+        return exposureExecutor;
+    }
+
     /**
      * Builder for BaseFlagsConfig.
      *
@@ -55,6 +67,7 @@ public static class Builder<T extends Builder<T>> {
         protected String projectToken;
         protected String apiHost = "api.mixpanel.com";
         protected int requestTimeoutSeconds = 10;
+        protected Executor exposureExecutor;
 
         /**
          * Sets the project token.
@@ -89,13 +102,34 @@ public T requestTimeoutSeconds(int requestTimeoutSeconds) {
             return (T) this;
         }
 
+        /**
+         * Sets the executor used to dispatch exposure event HTTP sends.
+         * <p>
+         * When null (the default), exposure events are sent synchronously on the
+         * calling thread — this adds HTTP latency to every flag evaluation when {@code reportExposure} is
+         * enabled.
+         * </p>
+         * <p>
+         * When set, the executor receives one {@link Runnable} per exposure event;
+         * each {@code Runnable} performs a single HTTP POST. If the
+         * executor fails to accept the task, the exposure event is dropped and a warning is logged.
+         * </p>
+         *
+         * @param exposureExecutor executor for exposure event dispatch, or null for synchronous
+         * @return this builder
+         */
+        public T exposureExecutor(Executor exposureExecutor) {
+            this.exposureExecutor = exposureExecutor;
+            return (T) this;
+        }
+
         /**
          * Builds the BaseFlagsConfig instance.
          *
          * @return a new BaseFlagsConfig
          */
         public BaseFlagsConfig build() {
-            return new BaseFlagsConfig(projectToken, apiHost, requestTimeoutSeconds);
+            return new BaseFlagsConfig(projectToken, apiHost, requestTimeoutSeconds, exposureExecutor);
         }
     }
 

src/main/java/com/mixpanel/mixpanelapi/featureflags/config/LocalFlagsConfig.java

@@ -1,5 +1,7 @@
 package com.mixpanel.mixpanelapi.featureflags.config;
 
+import java.util.concurrent.Executor;
+
 /**
  * Configuration for local feature flags evaluation.
  * <p>
@@ -17,11 +19,12 @@ public final class LocalFlagsConfig extends BaseFlagsConfig {
      * @param projectToken the Mixpanel project token
      * @param apiHost the API endpoint host
      * @param requestTimeoutSeconds HTTP request timeout in seconds
+     * @param exposureExecutor executor used to dispatch exposure event HTTP sends; may be null
      * @param enablePolling whether to periodically refresh flag definitions
      * @param pollingIntervalSeconds time between refresh cycles in seconds
      */
-    private LocalFlagsConfig(String projectToken, String apiHost, int requestTimeoutSeconds, boolean enablePolling, int pollingIntervalSeconds) {
-        super(projectToken, apiHost, requestTimeoutSeconds);
+    private LocalFlagsConfig(String projectToken, String apiHost, int requestTimeoutSeconds, Executor exposureExecutor, boolean enablePolling, int pollingIntervalSeconds) {
+        super(projectToken, apiHost, requestTimeoutSeconds, exposureExecutor);
         this.enablePolling = enablePolling;
         this.pollingIntervalSeconds = pollingIntervalSeconds;
     }
@@ -76,7 +79,7 @@ public Builder pollingIntervalSeconds(int pollingIntervalSeconds) {
          */
         @Override
         public LocalFlagsConfig build() {
-            return new LocalFlagsConfig(projectToken, apiHost, requestTimeoutSeconds, enablePolling, pollingIntervalSeconds);
+            return new LocalFlagsConfig(projectToken, apiHost, requestTimeoutSeconds, exposureExecutor, enablePolling, pollingIntervalSeconds);
         }
     }
 

src/main/java/com/mixpanel/mixpanelapi/featureflags/config/RemoteFlagsConfig.java

@@ -1,5 +1,7 @@
 package com.mixpanel.mixpanelapi.featureflags.config;
 
+import java.util.concurrent.Executor;
+
 /**
  * Configuration for remote feature flags evaluation.
  * <p>
@@ -15,9 +17,10 @@ public final class RemoteFlagsConfig extends BaseFlagsConfig {
      * @param projectToken the Mixpanel project token
      * @param apiHost the API endpoint host
      * @param requestTimeoutSeconds HTTP request timeout in seconds
+     * @param exposureExecutor executor used to dispatch exposure event HTTP sends; may be null
      */
-    private RemoteFlagsConfig(String projectToken, String apiHost, int requestTimeoutSeconds) {
-        super(projectToken, apiHost, requestTimeoutSeconds);
+    private RemoteFlagsConfig(String projectToken, String apiHost, int requestTimeoutSeconds, Executor exposureExecutor) {
+        super(projectToken, apiHost, requestTimeoutSeconds, exposureExecutor);
     }
 
     /**
@@ -32,7 +35,7 @@ public static final class Builder extends BaseFlagsConfig.Builder<Builder> {
          */
         @Override
         public RemoteFlagsConfig build() {
-            return new RemoteFlagsConfig(projectToken, apiHost, requestTimeoutSeconds);
+            return new RemoteFlagsConfig(projectToken, apiHost, requestTimeoutSeconds, exposureExecutor);
         }
     }