[FSSDK-11552] Add holdout support and refactor decision logic

pkg/cmab/service_test.go

@@ -230,6 +230,11 @@ func (m *MockProjectConfig) GetRegion() string {
 	return args.String(0)
 }
 
+func (m *MockProjectConfig) GetHoldoutsForFlag(featureKey string) []entities.Holdout {
+	args := m.Called(featureKey)
+	return args.Get(0).([]entities.Holdout)
+}
+
 type CmabServiceTestSuite struct {
 	suite.Suite
 	mockClient     *MockCmabClient

pkg/config/datafileprojectconfig/config.go

@@ -60,6 +60,9 @@ type DatafileProjectConfig struct {
 	region               string
 
 	flagVariationsMap map[string][]entities.Variation
+	holdouts          []entities.Holdout
+	holdoutIDMap      map[string]entities.Holdout
+	flagHoldoutsMap   map[string][]entities.Holdout
 }
 
 // GetDatafile returns a string representation of the environment's datafile
@@ -281,6 +284,14 @@ func (c DatafileProjectConfig) GetRegion() string {
 	return c.region
 }
 
+// GetHoldoutsForFlag returns all holdouts applicable to the given feature flag
+func (c DatafileProjectConfig) GetHoldoutsForFlag(featureKey string) []entities.Holdout {
+	if holdouts, exists := c.flagHoldoutsMap[featureKey]; exists {
+		return holdouts
+	}
+	return []entities.Holdout{}
+}
+
 // NewDatafileProjectConfig initializes a new datafile from a json byte array using the default JSON datafile parser
 func NewDatafileProjectConfig(jsonDatafile []byte, logger logging.OptimizelyLogProducer) (*DatafileProjectConfig, error) {
 	datafile, err := Parse(jsonDatafile)
@@ -323,6 +334,7 @@ func NewDatafileProjectConfig(jsonDatafile []byte, logger logging.OptimizelyLogP
 	featureMap := mappers.MapFeatures(datafile.FeatureFlags, rolloutMap, experimentIDMap)
 	audienceMap, audienceSegmentList := mappers.MapAudiences(append(datafile.TypedAudiences, datafile.Audiences...))
 	flagVariationsMap := mappers.MapFlagVariations(featureMap)
+	holdouts, holdoutIDMap, flagHoldoutsMap := mappers.MapHoldouts(datafile.Holdouts, featureMap)
 
 	attributeKeyMap := make(map[string]entities.Attribute)
 	attributeIDToKeyMap := make(map[string]string)
@@ -365,6 +377,9 @@ func NewDatafileProjectConfig(jsonDatafile []byte, logger logging.OptimizelyLogP
 		attributeKeyMap:      attributeKeyMap,
 		attributeIDToKeyMap:  attributeIDToKeyMap,
 		region:               region,
+		holdouts:             holdouts,
+		holdoutIDMap:         holdoutIDMap,
+		flagHoldoutsMap:      flagHoldoutsMap,
 	}
 
 	logger.Info("Datafile is valid.")

pkg/config/datafileprojectconfig/config_test.go

@@ -728,3 +728,64 @@ func TestGetAttributeByKeyWithDirectMapping(t *testing.T) {
 	assert.Nil(t, err)
 	assert.Equal(t, attribute, actual)
 }
+
+func TestGetHoldoutsForFlagWithHoldouts(t *testing.T) {
+	flagKey := "test_flag"
+	holdout1 := entities.Holdout{
+		ID:     "holdout_1",
+		Key:    "test_holdout_1",
+		Status: entities.HoldoutStatusRunning,
+	}
+	holdout2 := entities.Holdout{
+		ID:     "holdout_2",
+		Key:    "test_holdout_2",
+		Status: entities.HoldoutStatusRunning,
+	}
+
+	flagHoldoutsMap := make(map[string][]entities.Holdout)
+	flagHoldoutsMap[flagKey] = []entities.Holdout{holdout1, holdout2}
+
+	config := &DatafileProjectConfig{
+		flagHoldoutsMap: flagHoldoutsMap,
+	}
+
+	actual := config.GetHoldoutsForFlag(flagKey)
+	assert.Len(t, actual, 2)
+	assert.Equal(t, holdout1, actual[0])
+	assert.Equal(t, holdout2, actual[1])
+}
+
+func TestGetHoldoutsForFlagWithNoHoldouts(t *testing.T) {
+	flagKey := "test_flag"
+	flagHoldoutsMap := make(map[string][]entities.Holdout)
+
+	config := &DatafileProjectConfig{
+		flagHoldoutsMap: flagHoldoutsMap,
+	}
+
+	actual := config.GetHoldoutsForFlag(flagKey)
+	assert.Len(t, actual, 0)
+	assert.Equal(t, []entities.Holdout{}, actual)
+}
+
+func TestGetHoldoutsForFlagWithDifferentFlag(t *testing.T) {
+	flagKey := "test_flag"
+	otherFlagKey := "other_flag"
+	holdout := entities.Holdout{
+		ID:     "holdout_1",
+		Key:    "test_holdout_1",
+		Status: entities.HoldoutStatusRunning,
+	}
+
+	flagHoldoutsMap := make(map[string][]entities.Holdout)
+	flagHoldoutsMap[otherFlagKey] = []entities.Holdout{holdout}
+
+	config := &DatafileProjectConfig{
+		flagHoldoutsMap: flagHoldoutsMap,
+	}
+
+	// Request different flag - should return empty
+	actual := config.GetHoldoutsForFlag(flagKey)
+	assert.Len(t, actual, 0)
+	assert.Equal(t, []entities.Holdout{}, actual)
+}

pkg/config/datafileprojectconfig/entities/entities.go

@@ -113,6 +113,19 @@ type Rollout struct {
 	Experiments []Experiment `json:"experiments"`
 }
 
+// Holdout represents a holdout from the Optimizely datafile
+type Holdout struct {
+	ID                 string              `json:"id"`
+	Key                string              `json:"key"`
+	Status             string              `json:"status"`
+	AudienceIds        []string            `json:"audienceIds"`
+	AudienceConditions interface{}         `json:"audienceConditions"`
+	Variations         []Variation         `json:"variations"`
+	TrafficAllocation  []TrafficAllocation `json:"trafficAllocation"`
+	IncludedFlags      []string            `json:"includedFlags,omitempty"`
+	ExcludedFlags      []string            `json:"excludedFlags,omitempty"`
+}
+
 // Integration represents a integration from the Optimizely datafile
 type Integration struct {
 	Key       *string `json:"key"`
@@ -129,6 +142,7 @@ type Datafile struct {
 	FeatureFlags      []FeatureFlag `json:"featureFlags"`
 	Events            []Event       `json:"events"`
 	Rollouts          []Rollout     `json:"rollouts"`
+	Holdouts          []Holdout     `json:"holdouts,omitempty"`
 	Integrations      []Integration `json:"integrations"`
 	TypedAudiences    []Audience    `json:"typedAudiences"`
 	Variables         []string      `json:"variables"`

pkg/config/datafileprojectconfig/mappers/holdout.go

@@ -0,0 +1,143 @@
+/****************************************************************************
+ * Copyright 2025, Optimizely, Inc. and contributors                        *
+ *                                                                          *
+ * 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                                  *
+ *                                                                          *
+ *    http://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.                                           *
+ ***************************************************************************/
+
+// Package mappers ...
+package mappers
+
+import (
+	datafileEntities "github.com/optimizely/go-sdk/v2/pkg/config/datafileprojectconfig/entities"
+	"github.com/optimizely/go-sdk/v2/pkg/entities"
+)
+
+// MapHoldouts maps the raw datafile holdout entities to SDK Holdout entities
+// and organizes them by flag relationships
+func MapHoldouts(holdouts []datafileEntities.Holdout, featureMap map[string]entities.Feature) (
+	holdoutList []entities.Holdout,
+	holdoutIDMap map[string]entities.Holdout,
+	flagHoldoutsMap map[string][]entities.Holdout,
+) {
+	holdoutList = []entities.Holdout{}
+	holdoutIDMap = make(map[string]entities.Holdout)
+	flagHoldoutsMap = make(map[string][]entities.Holdout)
+
+	globalHoldouts := []entities.Holdout{}
+	includedHoldouts := make(map[string][]entities.Holdout)
+	excludedHoldouts := make(map[string][]entities.Holdout)
+
+	for _, holdout := range holdouts {
+		// Only process running holdouts
+		if holdout.Status != string(entities.HoldoutStatusRunning) {
+			continue
+		}
+
+		mappedHoldout := mapHoldout(holdout)
+		holdoutList = append(holdoutList, mappedHoldout)
+		holdoutIDMap[holdout.ID] = mappedHoldout
+
+		// Classify holdout by flag relationships
+		if len(holdout.IncludedFlags) == 0 {
+			// Global holdout - applies to all flags except excluded
+			globalHoldouts = append(globalHoldouts, mappedHoldout)
+
+			// Track exclusions
+			for _, flagID := range holdout.ExcludedFlags {
+				excludedHoldouts[flagID] = append(excludedHoldouts[flagID], mappedHoldout)
+			}
+		} else {
+			// Specific holdout - applies only to included flags
+			for _, flagID := range holdout.IncludedFlags {
+				includedHoldouts[flagID] = append(includedHoldouts[flagID], mappedHoldout)
+			}
+		}
+	}
+
+	// Build flagHoldoutsMap by combining global and specific holdouts
+	// Global holdouts take precedence (evaluated first), then specific holdouts
+	for _, feature := range featureMap {
+		flagKey := feature.Key
+		flagID := feature.ID
+		applicableHoldouts := []entities.Holdout{}
+
+		// Add global holdouts first (if not excluded) - they take precedence
+		if _, exists := excludedHoldouts[flagID]; !exists {
+			applicableHoldouts = append(applicableHoldouts, globalHoldouts...)
+		}
+
+		// Add specifically included holdouts second
+		if included, exists := includedHoldouts[flagID]; exists {
+			applicableHoldouts = append(applicableHoldouts, included...)
+		}
+
+		if len(applicableHoldouts) > 0 {
+			flagHoldoutsMap[flagKey] = applicableHoldouts
+		}
+	}
+
+	return holdoutList, holdoutIDMap, flagHoldoutsMap
+}
+
+func mapHoldout(datafileHoldout datafileEntities.Holdout) entities.Holdout {
+	var audienceConditionTree *entities.TreeNode
+	var err error
+
+	// Build audience condition tree similar to experiments
+	if datafileHoldout.AudienceConditions == nil && len(datafileHoldout.AudienceIds) > 0 {
+		audienceConditionTree, err = buildAudienceConditionTree(datafileHoldout.AudienceIds)
+	} else {
+		switch audienceConditions := datafileHoldout.AudienceConditions.(type) {
+		case []interface{}:
+			if len(audienceConditions) > 0 {
+				audienceConditionTree, err = buildAudienceConditionTree(audienceConditions)
+			}
+		case string:
+			if audienceConditions != "" {
+				audienceConditionTree, err = buildAudienceConditionTree([]string{audienceConditions})
+			}
+		default:
+		}
+	}
+	if err != nil {
+		// @TODO: handle error
+		func() {}() // cheat the linters
+	}
+
+	// Map variations
+	variations := make(map[string]entities.Variation)
+	for _, datafileVariation := range datafileHoldout.Variations {
+		variation := mapVariation(datafileVariation)
+		variations[variation.ID] = variation
+	}
+
+	// Map traffic allocations
+	trafficAllocation := make([]entities.Range, len(datafileHoldout.TrafficAllocation))
+	for i, allocation := range datafileHoldout.TrafficAllocation {
+		trafficAllocation[i] = entities.Range{
+			EntityID:   allocation.EntityID,
+			EndOfRange: allocation.EndOfRange,
+		}
+	}
+
+	return entities.Holdout{
+		ID:                    datafileHoldout.ID,
+		Key:                   datafileHoldout.Key,
+		Status:                entities.HoldoutStatus(datafileHoldout.Status),
+		AudienceIds:           datafileHoldout.AudienceIds,
+		AudienceConditions:    datafileHoldout.AudienceConditions,
+		Variations:            variations,
+		TrafficAllocation:     trafficAllocation,
+		AudienceConditionTree: audienceConditionTree,
+	}
+}