[FSSDK-11544] holdout parsing

Author: junaed-optimizely

OptimizelySDK.Net35/OptimizelySDK.Net35.csproj

@@ -224,6 +224,9 @@
     <Compile Include="..\OptimizelySDK\Utils\ExperimentUtils.cs">
       <Link>Bucketing\ExperimentUtils</Link>
     </Compile>
+    <Compile Include="..\OptimizelySDK\Utils\HoldoutConfig.cs">
+      <Link>Utils\HoldoutConfig.cs</Link>
+    </Compile>
     <Compile Include="..\OptimizelySDK\Bucketing\UserProfileUtil.cs">
       <Link>Bucketing\UserProfileUtil</Link>
     </Compile>

OptimizelySDK.Net40/OptimizelySDK.Net40.csproj

@@ -223,6 +223,9 @@
     <Compile Include="..\OptimizelySDK\Utils\ExperimentUtils.cs">
       <Link>Bucketing\ExperimentUtils</Link>
     </Compile>
+    <Compile Include="..\OptimizelySDK\Utils\HoldoutConfig.cs">
+      <Link>Utils\HoldoutConfig.cs</Link>
+    </Compile>
     <Compile Include="..\OptimizelySDK\Bucketing\UserProfileUtil.cs">
       <Link>Bucketing\UserProfileUtil</Link>
     </Compile>

OptimizelySDK.NetStandard16/OptimizelySDK.NetStandard16.csproj

@@ -67,6 +67,7 @@
 			<Compile Include="..\OptimizelySDK\Utils\ControlAttributes.cs" />
 			<Compile Include="..\OptimizelySDK\Utils\ExceptionExtensions.cs" />
 			<Compile Include="..\OptimizelySDK\Utils\ExperimentUtils.cs" />
+			<Compile Include="..\OptimizelySDK\Utils\HoldoutConfig.cs" />
 			<Compile Include="..\OptimizelySDK\Utils\ConditionParser.cs" />
 			<Compile Include="..\OptimizelySDK\Utils\AttributeMatchTypes.cs" />
 			<Compile Include="..\OptimizelySDK\Utils\DecisionInfoTypes.cs" />

OptimizelySDK.NetStandard20/OptimizelySDK.NetStandard20.csproj

@@ -340,6 +340,9 @@
     <Compile Include="..\OptimizelySDK\Utils\ExperimentUtils.cs">
       <Link>Utils\ExperimentUtils.cs</Link>
     </Compile>
+    <Compile Include="..\OptimizelySDK\Utils\HoldoutConfig.cs">
+      <Link>Utils\HoldoutConfig.cs</Link>
+    </Compile>
     <Compile Include="..\OptimizelySDK\Utils\Schema.cs">
       <Link>Utils\Schema.cs</Link>
     </Compile>

OptimizelySDK/Config/DatafileProjectConfig.cs

@@ -216,6 +216,13 @@ private Dictionary<string, Dictionary<string, Variation>> _VariationIdMap
 
         public Dictionary<string, Rollout> RolloutIdMap => _RolloutIdMap;
 
+        /// <summary>
+        /// Associative array of Holdout ID to Holdout(s) in the datafile
+        /// </summary>
+        private Dictionary<string, Holdout> _HoldoutIdMap;
+
+        public Dictionary<string, Holdout> HoldoutIdMap => _HoldoutIdMap;
+
         /// <summary>
         /// Associative array of experiment IDs that exist in any feature
         /// for checking that experiment is a feature experiment.
@@ -232,6 +239,11 @@ private Dictionary<string, Dictionary<string, Variation>> _VariationIdMap
         public Dictionary<string, Dictionary<string, Variation>> FlagVariationMap =>
             _FlagVariationMap;
 
+        /// <summary>
+        /// Holdout configuration manager for flag-to-holdout relationships.
+        /// </summary>
+        private HoldoutConfig _holdoutConfig;
+
         //========================= Interfaces ===========================
 
         /// <summary>
@@ -286,6 +298,11 @@ private Dictionary<string, Dictionary<string, Variation>> _VariationIdMap
         /// </summary>
         public Rollout[] Rollouts { get; set; }
 
+        /// <summary>
+        /// Associative list of Holdouts.
+        /// </summary>
+        public Holdout[] Holdouts { get; set; }
+
         /// <summary>
         /// Associative list of Integrations.
         /// </summary>
@@ -309,6 +326,7 @@ private void Initialize()
             TypedAudiences = TypedAudiences ?? new Audience[0];
             FeatureFlags = FeatureFlags ?? new FeatureFlag[0];
             Rollouts = Rollouts ?? new Rollout[0];
+            Holdouts = Holdouts ?? new Holdout[0];
             Integrations = Integrations ?? new Integration[0];
             _ExperimentKeyMap = new Dictionary<string, Experiment>();
 
@@ -327,6 +345,8 @@ private void Initialize()
                 f => f.Key, true);
             _RolloutIdMap = ConfigParser<Rollout>.GenerateMap(Rollouts,
                 r => r.Id.ToString(), true);
+            _HoldoutIdMap = ConfigParser<Holdout>.GenerateMap(Holdouts,
+                h => h.Id, true);
 
             // Overwrite similar items in audience id map with typed audience id map.
             var typedAudienceIdMap = ConfigParser<Audience>.GenerateMap(TypedAudiences,
@@ -450,6 +470,9 @@ private void Initialize()
             }
 
             _FlagVariationMap = flagToVariationsMap;
+
+            // Initialize HoldoutConfig for managing flag-to-holdout relationships
+            _holdoutConfig = new HoldoutConfig(Holdouts ?? new Holdout[0]);
         }
 
         /// <summary>
@@ -773,6 +796,34 @@ public Rollout GetRolloutFromId(string rolloutId)
             return new Rollout();
         }
 
+        /// <summary>
+        /// Get the holdout from the ID
+        /// </summary>
+        /// <param name="holdoutId">ID for holdout</param>
+        /// <returns>Holdout Entity corresponding to the holdout ID or a dummy entity if ID is invalid</returns>
+        public Holdout GetHoldout(string holdoutId)
+        {
+#if NET35 || NET40
+            if (string.IsNullOrEmpty(holdoutId) || string.IsNullOrEmpty(holdoutId.Trim()))
+#else
+            if (string.IsNullOrWhiteSpace(holdoutId))
+#endif
+            {
+                return new Holdout();
+            }
+
+            if (_HoldoutIdMap.ContainsKey(holdoutId))
+            {
+                return _HoldoutIdMap[holdoutId];
+            }
+
+            var message = $@"Holdout ID ""{holdoutId}"" is not in datafile.";
+            Logger.Log(LogLevel.ERROR, message);
+            ErrorHandler.HandleError(
+                new InvalidExperimentException("Provided holdout is not in datafile."));
+            return new Holdout();
+        }
+
         /// <summary>
         /// Get attribute ID for the provided attribute key
         /// </summary>
@@ -832,5 +883,16 @@ public string ToDatafile()
         {
             return _datafile;
         }
+
+        /// <summary>
+        /// Get holdout instances associated with the given feature flag key.
+        /// </summary>
+        /// <param name="flagKey">Feature flag key</param>
+        /// <returns>Array of holdouts associated with the flag, empty array if none</returns>
+        public Holdout[] GetHoldoutsForFlag(string flagKey)
+        {
+            var holdouts = _holdoutConfig?.GetHoldoutsForFlag(flagKey);
+            return holdouts?.ToArray() ?? new Holdout[0];
+        }
     }
 }

OptimizelySDK/OptimizelySDK.csproj

@@ -174,6 +174,7 @@
     <Compile Include="Utils\EventTagUtils.cs"/>
     <Compile Include="Bucketing\UserProfileUtil.cs"/>
     <Compile Include="Utils\ExperimentUtils.cs"/>
+    <Compile Include="Utils\HoldoutConfig.cs"/>
     <Compile Include="Utils\ControlAttributes.cs"/>
     <Compile Include="Utils\ExceptionExtensions.cs"/>
     <Compile Include="Utils\DateTimeUtils.cs"/>

OptimizelySDK/ProjectConfig.cs

@@ -128,6 +128,11 @@ public interface ProjectConfig
         /// </summary>
         Dictionary<string, Rollout> RolloutIdMap { get; }
 
+        /// <summary>
+        /// Associative array of Holdout ID to Holdout(s) in the datafile
+        /// </summary>
+        Dictionary<string, Holdout> HoldoutIdMap { get; }
+
         /// <summary>
         /// Associative dictionary of Flag to Variation key and Variation in the datafile
         /// </summary>
@@ -175,6 +180,11 @@ public interface ProjectConfig
         /// </summary>
         Rollout[] Rollouts { get; set; }
 
+        /// <summary>
+        /// Associative list of Holdouts.
+        /// </summary>
+        Holdout[] Holdouts { get; set; }
+
         /// <summary>
         /// Associative list of Integrations.
         /// </summary>
@@ -308,6 +318,20 @@ public interface ProjectConfig
         /// <returns>List| Feature flag ids list, null otherwise</returns>
         List<string> GetExperimentFeatureList(string experimentId);
 
+        /// <summary>
+        /// Get the holdout from the ID
+        /// </summary>
+        /// <param name="holdoutId">ID for holdout</param>
+        /// <returns>Holdout Entity corresponding to the holdout ID or a dummy entity if ID is invalid</returns>
+        Holdout GetHoldout(string holdoutId);
+
+        /// <summary>
+        /// Get holdout instances associated with the given feature flag key.
+        /// </summary>
+        /// <param name="flagKey">Feature flag key</param>
+        /// <returns>Array of holdouts associated with the flag, empty array if none</returns>
+        Holdout[] GetHoldoutsForFlag(string flagKey);
+
         /// <summary>
         /// Returns the datafile corresponding to ProjectConfig
         /// </summary>

OptimizelySDK/Utils/HoldoutConfig.cs

@@ -0,0 +1,163 @@
+/*
+ * Copyright 2025, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+using System.Collections.Generic;
+using System.Linq;
+using OptimizelySDK.Entity;
+
+namespace OptimizelySDK.Utils
+{
+    /// <summary>
+    /// Configuration manager for holdouts, providing flag-to-holdout relationship mapping and optimization logic.
+    /// </summary>
+    public class HoldoutConfig
+    {
+        private readonly List<Holdout> _allHoldouts;
+        private readonly List<Holdout> _globalHoldouts;
+        private readonly Dictionary<string, Holdout> _holdoutIdMap;
+        private readonly Dictionary<string, List<Holdout>> _includedHoldouts;
+        private readonly Dictionary<string, List<Holdout>> _excludedHoldouts;
+        private readonly Dictionary<string, List<Holdout>> _flagHoldoutCache;
+
+        /// <summary>
+        /// Initializes a new instance of the HoldoutConfig class.
+        /// </summary>
+        /// <param name="allHoldouts">Array of all holdouts from the datafile</param>
+        public HoldoutConfig(Holdout[] allHoldouts = null)
+        {
+            _allHoldouts = allHoldouts?.ToList() ?? new List<Holdout>();
+            _globalHoldouts = new List<Holdout>();
+            _holdoutIdMap = new Dictionary<string, Holdout>();
+            _includedHoldouts = new Dictionary<string, List<Holdout>>();
+            _excludedHoldouts = new Dictionary<string, List<Holdout>>();
+            _flagHoldoutCache = new Dictionary<string, List<Holdout>>();
+
+            UpdateHoldoutMapping();
+        }
+
+        /// <summary>
+        /// Updates internal mappings of holdouts including the id map, global list, and per-flag inclusion/exclusion maps.
+        /// </summary>
+        private void UpdateHoldoutMapping()
+        {
+            // Clear existing mappings
+            _holdoutIdMap.Clear();
+            _globalHoldouts.Clear();
+            _includedHoldouts.Clear();
+            _excludedHoldouts.Clear();
+            _flagHoldoutCache.Clear();
+
+            foreach (var holdout in _allHoldouts)
+            {
+                // Build ID mapping
+                _holdoutIdMap[holdout.Id] = holdout;
+
+                var hasIncludedFlags = holdout.IncludedFlags != null && holdout.IncludedFlags.Length > 0;
+                var hasExcludedFlags = holdout.ExcludedFlags != null && holdout.ExcludedFlags.Length > 0;
+
+                if (!hasIncludedFlags && !hasExcludedFlags)
+                {
+                    // Global holdout (no included or excluded flags)
+                    _globalHoldouts.Add(holdout);
+                }
+                else if (hasIncludedFlags)
+                {
+                    // Holdout with specific included flags
+                    foreach (var flagId in holdout.IncludedFlags)
+                    {
+                        if (!_includedHoldouts.ContainsKey(flagId))
+                            _includedHoldouts[flagId] = new List<Holdout>();
+                        
+                        _includedHoldouts[flagId].Add(holdout);
+                    }
+                }
+                else if (hasExcludedFlags)
+                {
+                    // Global holdout with excluded flags
+                    _globalHoldouts.Add(holdout);
+                    
+                    foreach (var flagId in holdout.ExcludedFlags)
+                    {
+                        if (!_excludedHoldouts.ContainsKey(flagId))
+                            _excludedHoldouts[flagId] = new List<Holdout>();
+                        
+                        _excludedHoldouts[flagId].Add(holdout);
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        /// Returns the applicable holdouts for the given flag ID by combining global holdouts (excluding any specified) and included holdouts, in that order.
+        /// Caches the result for future calls.
+        /// </summary>
+        /// <param name="flagId">The flag identifier</param>
+        /// <returns>A list of Holdout objects relevant to the given flag</returns>
+        public List<Holdout> GetHoldoutsForFlag(string flagId)
+        {
+            if (_allHoldouts.Count == 0)
+                return new List<Holdout>();
+
+            // Check cache first
+            if (_flagHoldoutCache.ContainsKey(flagId))
+                return _flagHoldoutCache[flagId];
+
+            var activeHoldouts = new List<Holdout>();
+
+            // Start with global holdouts, excluding any that are specifically excluded for this flag
+            var excludedForFlag = _excludedHoldouts.ContainsKey(flagId) ? _excludedHoldouts[flagId] : new List<Holdout>();
+            
+            foreach (var globalHoldout in _globalHoldouts)
+            {
+                if (!excludedForFlag.Contains(globalHoldout))
+                {
+                    activeHoldouts.Add(globalHoldout);
+                }
+            }
+
+            // Add included holdouts for this flag
+            if (_includedHoldouts.ContainsKey(flagId))
+            {
+                activeHoldouts.AddRange(_includedHoldouts[flagId]);
+            }
+
+            // Cache the result
+            _flagHoldoutCache[flagId] = activeHoldouts;
+
+            return activeHoldouts;
+        }
+
+        /// <summary>
+        /// Get a Holdout object for an ID.
+        /// </summary>
+        /// <param name="holdoutId">The holdout identifier</param>
+        /// <returns>The Holdout object if found, null otherwise</returns>
+        public Holdout GetHoldout(string holdoutId)
+        {
+            return _holdoutIdMap.ContainsKey(holdoutId) ? _holdoutIdMap[holdoutId] : null;
+        }
+
+        /// <summary>
+        /// Gets the total number of holdouts.
+        /// </summary>
+        public int HoldoutCount => _allHoldouts.Count;
+
+        /// <summary>
+        /// Gets the number of global holdouts.
+        /// </summary>
+        public int GlobalHoldoutCount => _globalHoldouts.Count;
+    }
+}