feat(decision): Add experiment bucketer implementation. (#32)

Author: Michael Ng

optimizely/client/client.go

@@ -35,7 +35,8 @@ type OptimizelyClient struct {
 // IsFeatureEnabled returns true if the feature is enabled for the given user
 func (optly *OptimizelyClient) IsFeatureEnabled(featureKey string, userID string, attributes map[string]interface{}) bool {
 	if !optly.isValid {
-		logger.Error("Optimizely instance is not valid. Failing IsFeatureEnabled.", nil)
+		errorMessage := "Optimizely instance is not valid. Failing IsFeatureEnabled."
+		logger.Error(errorMessage, nil)
 		return false
 	}
 

optimizely/decision/bucketer/experiment_bucketer.go

@@ -0,0 +1,73 @@
+package bucketer
+
+import (
+	"math"
+
+	"github.com/optimizely/go-sdk/optimizely/entities"
+	"github.com/twmb/murmur3"
+)
+
+var maxHashValue = float32(math.Pow(2, 32))
+
+// DefaultHashSeed is the hash seed to use for murmurhash
+const DefaultHashSeed = 1
+const maxTrafficValue = 10000
+
+// ExperimentBucketer buckets the user
+type ExperimentBucketer struct {
+	hashSeed uint32
+}
+
+// NewExperimentBucketer returns a new instance of the experiment bucketer
+func NewExperimentBucketer(hashSeed uint32) *ExperimentBucketer {
+	return &ExperimentBucketer{
+		hashSeed: hashSeed,
+	}
+}
+
+// Bucket buckets the user into the given experiment
+func (b *ExperimentBucketer) Bucket(bucketingID string, experiment entities.Experiment, group entities.Group) entities.Variation {
+	if experiment.GroupID != "" && group.Policy == "random" {
+		bucketKey := bucketingID + group.ID
+		bucketedExperimentID := b.bucketToEntity(bucketKey, group.TrafficAllocation)
+		if bucketedExperimentID == "" || bucketedExperimentID != experiment.ID {
+			// User is not bucketed into an experiment in the exclusion group, return an empty variation
+			return entities.Variation{}
+		}
+	}
+
+	bucketKey := bucketingID + experiment.ID
+	bucketedVariationID := b.bucketToEntity(bucketKey, experiment.TrafficAllocation)
+	if bucketedVariationID == "" {
+		// User is not bucketed into a variation in the experiment, return an empty variation
+		return entities.Variation{}
+	}
+
+	if variation, ok := experiment.Variations[bucketedVariationID]; ok {
+		return variation
+	}
+
+	return entities.Variation{}
+}
+
+func (b *ExperimentBucketer) bucketToEntity(bucketKey string, trafficAllocations []entities.Range) (entityID string) {
+	// TODO(mng): return log message re: bucket value
+	bucketValue := b.generateBucketValue(bucketKey)
+	var currentEndOfRange int
+	for _, trafficAllocationRange := range trafficAllocations {
+		currentEndOfRange = trafficAllocationRange.EndOfRange
+		if bucketValue < currentEndOfRange {
+			return trafficAllocationRange.EntityID
+		}
+	}
+
+	return ""
+}
+
+func (b *ExperimentBucketer) generateBucketValue(bucketingKey string) int {
+	hasher := murmur3.SeedNew32(b.hashSeed)
+	hasher.Write([]byte(bucketingKey))
+	hashCode := hasher.Sum32()
+	ratio := float32(hashCode) / maxHashValue
+	return int(ratio * maxTrafficValue)
+}

optimizely/decision/bucketer/experiment_bucketer_test.go

@@ -0,0 +1,110 @@
+package bucketer
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/optimizely/go-sdk/optimizely/entities"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestGenerateBucketValue(t *testing.T) {
+	bucketer := NewExperimentBucketer(DefaultHashSeed)
+
+	// copied from unit tests in the other SDKs
+	experimentID := "1886780721"
+	experimentID2 := "1886780722"
+	bucketingKey1 := fmt.Sprintf("%s%s", "ppid1", experimentID)
+	bucketingKey2 := fmt.Sprintf("%s%s", "ppid2", experimentID)
+	bucketingKey3 := fmt.Sprintf("%s%s", "ppid2", experimentID2)
+	bucketingKey4 := fmt.Sprintf("%s%s", "ppid3", experimentID)
+
+	assert.Equal(t, 5254, bucketer.generateBucketValue(bucketingKey1))
+	assert.Equal(t, 4299, bucketer.generateBucketValue(bucketingKey2))
+	assert.Equal(t, 2434, bucketer.generateBucketValue(bucketingKey3))
+	assert.Equal(t, 5439, bucketer.generateBucketValue(bucketingKey4))
+}
+
+func TestBucketToEntity(t *testing.T) {
+	bucketer := NewExperimentBucketer(DefaultHashSeed)
+
+	experimentID := "1886780721"
+	experimentID2 := "1886780722"
+
+	// bucket value 5254
+	bucketingKey1 := fmt.Sprintf("%s%s", "ppid1", experimentID)
+	// bucket value 4299
+	bucketingKey2 := fmt.Sprintf("%s%s", "ppid2", experimentID)
+	// bucket value 2434
+	bucketingKey3 := fmt.Sprintf("%s%s", "ppid2", experimentID2)
+	// bucket value 5439
+	bucketingKey4 := fmt.Sprintf("%s%s", "ppid3", experimentID)
+
+	variation1 := "1234567123"
+	variation2 := "5949300123"
+	trafficAlloc := []entities.Range{
+		entities.Range{
+			EntityID:   "",
+			EndOfRange: 2500,
+		},
+		entities.Range{
+			EntityID:   variation1,
+			EndOfRange: 4999,
+		},
+		entities.Range{
+			EntityID:   variation2,
+			EndOfRange: 5399,
+		},
+	}
+
+	assert.Equal(t, variation2, bucketer.bucketToEntity(bucketingKey1, trafficAlloc))
+	assert.Equal(t, variation1, bucketer.bucketToEntity(bucketingKey2, trafficAlloc))
+
+	// bucket to empty variation range
+	assert.Equal(t, "", bucketer.bucketToEntity(bucketingKey3, trafficAlloc))
+
+	// bucket outside of range (not in experiment)
+	assert.Equal(t, "", bucketer.bucketToEntity(bucketingKey4, trafficAlloc))
+}
+
+func TestBucketExclusionGroups(t *testing.T) {
+	experiment1 := entities.Experiment{
+		ID: "1886780721",
+		Variations: map[string]entities.Variation{
+			"22222": entities.Variation{ID: "22222", Key: "exp_1_var_1"},
+			"22223": entities.Variation{ID: "22223", Key: "exp_1_var_2"},
+		},
+		TrafficAllocation: []entities.Range{
+			entities.Range{EntityID: "22222", EndOfRange: 4999},
+			entities.Range{EntityID: "22223", EndOfRange: 10000},
+		},
+		GroupID: "1886780722",
+	}
+	experiment2 := entities.Experiment{
+		ID: "1886780723",
+		Variations: map[string]entities.Variation{
+			"22224": entities.Variation{ID: "22224", Key: "exp_2_var_1"},
+			"22225": entities.Variation{ID: "22225", Key: "exp_2_var_2"},
+		},
+		TrafficAllocation: []entities.Range{
+			entities.Range{EntityID: "22224", EndOfRange: 4999},
+			entities.Range{EntityID: "22225", EndOfRange: 10000},
+		},
+		GroupID: "1886780722",
+	}
+
+	exclusionGroup := entities.Group{
+		ID:     "1886780722",
+		Policy: "random",
+		TrafficAllocation: []entities.Range{
+			entities.Range{EntityID: "1886780721", EndOfRange: 2500},
+			entities.Range{EntityID: "1886780723", EndOfRange: 5000},
+		},
+	}
+
+	bucketer := NewExperimentBucketer(DefaultHashSeed)
+	// ppid2 + 1886780722 (groupId) will generate bucket value of 2434 which maps to experiment 1
+	assert.Equal(t, experiment1.Variations["22222"], bucketer.Bucket("ppid2", experiment1, exclusionGroup))
+	// since the bucket value maps to experiment 1, the user will not be bucketed for experiment 2
+	assert.Equal(t, entities.Variation{}, bucketer.Bucket("ppid2", experiment2, exclusionGroup))
+}

optimizely/entities/group.go

@@ -20,4 +20,5 @@ package entities
 type Group struct {
 	ID                string
 	TrafficAllocation []Range
+	Policy            string
 }