feat: Complete holdout implementation with parsing, mapping, and tests

- Implemented holdout parsing from datafile with global/specific/exclusion logic
- Added MapHoldouts() to process holdout relationships with feature flags
- Implemented GetHoldoutsForFlag() to retrieve applicable holdouts per flag
- Fixed bucketer initialization to use pointer (interface value)
- Created comprehensive unit tests for HoldoutService (11 test cases)
- Added integration test with real bucketer and evaluator
- Added GetHoldoutsForFlag() mock method to helpers_test.go

All tests passing (decision and config packages)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Mat001

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
@@ -282,9 +285,10 @@ func (c DatafileProjectConfig) GetRegion() string {
 }
 
 // GetHoldoutsForFlag returns all holdouts applicable to the given feature flag
-// TODO: Implementation will be added in holdout parsing PR
 func (c DatafileProjectConfig) GetHoldoutsForFlag(featureKey string) []entities.Holdout {
-	// Stub implementation - will be replaced with actual holdout logic
+	if holdouts, exists := c.flagHoldoutsMap[featureKey]; exists {
+		return holdouts
+	}
 	return []entities.Holdout{}
 }
 
@@ -330,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)
@@ -372,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/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,147 @@
+/****************************************************************************
+ * 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
+	for _, feature := range featureMap {
+		flagKey := feature.Key
+		flagID := feature.ID
+		applicableHoldouts := []entities.Holdout{}
+
+		// Add specifically included holdouts
+		if included, exists := includedHoldouts[flagID]; exists {
+			applicableHoldouts = append(applicableHoldouts, included...)
+		}
+
+		// Add global holdouts (if not excluded)
+		isExcluded := false
+		if _, exists := excludedHoldouts[flagID]; exists {
+			isExcluded = true
+		}
+
+		if !isExcluded {
+			applicableHoldouts = append(applicableHoldouts, globalHoldouts...)
+		}
+
+		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,
+	}
+}

pkg/decision/helpers_test.go

@@ -59,6 +59,11 @@ func (c *mockProjectConfig) GetFlagVariationsMap() map[string][]entities.Variati
 	return args.Get(0).(map[string][]entities.Variation)
 }
 
+func (c *mockProjectConfig) GetHoldoutsForFlag(featureKey string) []entities.Holdout {
+	args := c.Called(featureKey)
+	return args.Get(0).([]entities.Holdout)
+}
+
 type MockExperimentDecisionService struct {
 	mock.Mock
 }

pkg/decision/holdout_service.go

@@ -40,7 +40,7 @@ func NewHoldoutService(sdkKey string) *HoldoutService {
 	logger := logging.GetLogger(sdkKey, "HoldoutService")
 	return &HoldoutService{
 		audienceTreeEvaluator: evaluator.NewMixedTreeEvaluator(logger),
-		bucketer:              *bucketer.NewMurmurhashExperimentBucketer(logger, bucketer.DefaultHashSeed),
+		bucketer:              bucketer.NewMurmurhashExperimentBucketer(logger, bucketer.DefaultHashSeed),
 		logger:                logger,
 	}
 }