add support for hash salts in feature flag definitions and evaluation

Author: msiebert

src/main/java/com/mixpanel/mixpanelapi/featureflags/model/ExperimentationFlag.java

@@ -22,6 +22,7 @@ public final class ExperimentationFlag {
     private final String context;
     private final UUID experimentId;
     private final Boolean isExperimentActive;
+    private final String hashSalt;
 
     /**
      * Creates a new ExperimentationFlag.
@@ -35,8 +36,9 @@ public final class ExperimentationFlag {
      * @param context the property name used for rollout hashing (e.g., "distinct_id")
      * @param experimentId the experiment ID (may be null)
      * @param isExperimentActive whether the experiment is active (may be null)
+     * @param hashSalt the hash salt for this flag (may be null for legacy flags)
      */
-    public ExperimentationFlag(String id, String name, String key, String status, int projectId, RuleSet ruleset, String context, UUID experimentId, Boolean isExperimentActive) {
+    public ExperimentationFlag(String id, String name, String key, String status, int projectId, RuleSet ruleset, String context, UUID experimentId, Boolean isExperimentActive, String hashSalt) {
         this.id = id;
         this.name = name;
         this.key = key;
@@ -46,6 +48,7 @@ public ExperimentationFlag(String id, String name, String key, String status, in
         this.context = context;
         this.experimentId = experimentId;
         this.isExperimentActive = isExperimentActive;
+        this.hashSalt = hashSalt;
     }
 
     /**
@@ -111,6 +114,13 @@ public Boolean getIsExperimentActive() {
         return isExperimentActive;
     }
 
+    /**
+     * @return the hash salt for this flag, or null for legacy flags
+     */
+    public String getHashSalt() {
+        return hashSalt;
+    }
+
     @Override
     public String toString() {
         return "ExperimentationFlag{" +
@@ -123,6 +133,7 @@ public String toString() {
                 ", context='" + context + '\'' +
                 ", experimentId=" + experimentId +
                 ", isExperimentActive=" + isExperimentActive +
+                ", hashSalt='" + hashSalt + '\'' +
                 '}';
     }
 }

src/main/java/com/mixpanel/mixpanelapi/featureflags/provider/LocalFlagsProvider.java

@@ -206,9 +206,12 @@ private ExperimentationFlag parseFlag(JSONObject json) {
             isExperimentActive = json.optBoolean("is_experiment_active", false);
         }
 
+        // Parse hash_salt (may be null for legacy flags)
+        String hashSalt = json.optString("hash_salt", null);
+
         RuleSet ruleset = parseRuleSet(json.optJSONObject("ruleset"));
 
-        return new ExperimentationFlag(id, name, key, status, projectId, ruleset, context, experimentId, isExperimentActive);
+        return new ExperimentationFlag(id, name, key, status, projectId, ruleset, context, experimentId, isExperimentActive, hashSalt);
     }
 
     /**
@@ -371,9 +374,13 @@ public <T> SelectedVariant<T> getVariant(String flagKey, SelectedVariant<T> fall
             }
 
             // Evaluate rollouts
-            float rolloutHash = HashUtils.normalizedHash(contextValue + flagKey, "rollout");
+            List<Rollout> rollouts = ruleset.getRollouts();
+            for (int rolloutIndex = 0; rolloutIndex < rollouts.size(); rolloutIndex++) {
+                Rollout rollout = rollouts.get(rolloutIndex);
+
+                // Calculate rollout hash
+                float rolloutHash = calculateRolloutHash(contextValue, flagKey, flag.getHashSalt(), rolloutIndex);
 
-            for (Rollout rollout : ruleset.getRollouts()) {
                 if (rolloutHash >= rollout.getRolloutPercentage()) {
                     continue;
                 }
@@ -391,8 +398,8 @@ public <T> SelectedVariant<T> getVariant(String flagKey, SelectedVariant<T> fall
                 if (rollout.hasVariantOverride()) {
                     selectedVariant = findVariantByKey(ruleset.getVariants(), rollout.getVariantOverride().getKey());
                 } else {
-                    // Use variant hash to select from split
-                    float variantHash = HashUtils.normalizedHash(contextValue + flagKey, "variant");
+                    // Calculate variant hash
+                    float variantHash = calculateVariantHash(contextValue, flagKey, flag.getHashSalt());
                     selectedVariant = selectVariantBySplit(ruleset.getVariants(), variantHash, rollout);
                 }
 
@@ -558,6 +565,46 @@ private Variant selectVariantBySplit(List<Variant> variants, float hash, Rollout
         return variantsToUse.isEmpty() ? null : variantsToUse.get(variantsToUse.size() - 1);
     }
 
+    /**
+     * Calculates the rollout hash for a given context and rollout index.
+     * <p>
+     * This method can be overridden in tests to verify hash parameters.
+     * </p>
+     *
+     * @param contextValue the context value (e.g., user ID)
+     * @param flagKey the flag key
+     * @param hashSalt the hash salt (null or empty for legacy behavior)
+     * @param rolloutIndex the index of the rollout being evaluated
+     * @return the normalized hash value (0.0 to 1.0)
+     */
+    protected float calculateRolloutHash(String contextValue, String flagKey,
+                                        String hashSalt, int rolloutIndex) {
+        if (hashSalt != null && !hashSalt.isEmpty()) {
+            return HashUtils.normalizedHash(contextValue + flagKey, hashSalt + rolloutIndex);
+        } else {
+            return HashUtils.normalizedHash(contextValue + flagKey, "rollout");
+        }
+    }
+
+    /**
+     * Calculates the variant hash for a given context.
+     * <p>
+     * This method can be overridden in tests to verify hash parameters.
+     * </p>
+     *
+     * @param contextValue the context value (e.g., user ID)
+     * @param flagKey the flag key
+     * @param hashSalt the hash salt (null or empty for legacy behavior)
+     * @return the normalized hash value (0.0 to 1.0)
+     */
+    protected float calculateVariantHash(String contextValue, String flagKey, String hashSalt) {
+        if (hashSalt != null && !hashSalt.isEmpty()) {
+            return HashUtils.normalizedHash(contextValue + flagKey, hashSalt + "variant");
+        } else {
+            return HashUtils.normalizedHash(contextValue + flagKey, "variant");
+        }
+    }
+
     /**
      * Evaluates all flags and returns their selected variants.
      * <p>