feat(decision): Add rollout service. (#43)

Author: Michael Ng

optimizely/decision/bucketer/experiment_bucketer.go

@@ -1,9 +1,9 @@
 package bucketer
 
 import (
-	"fmt"
 	"math"
 
+	"github.com/optimizely/go-sdk/optimizely/decision/reasons"
 	"github.com/optimizely/go-sdk/optimizely/entities"
 	"github.com/optimizely/go-sdk/optimizely/logging"
 	"github.com/twmb/murmur3"
@@ -18,7 +18,7 @@ const maxTrafficValue = 10000
 
 // ExperimentBucketer is used to bucket the user into a particular entity in the experiment's traffic alloc range
 type ExperimentBucketer interface {
-	Bucket(bucketingID string, experiment entities.Experiment, group entities.Group) entities.Variation
+	Bucket(bucketingID string, experiment entities.Experiment, group entities.Group) (entities.Variation, reasons.Reason, error)
 }
 
 // MurmurhashBucketer buckets the user using the mmh3 algorightm
@@ -34,30 +34,28 @@ func NewMurmurhashBucketer(hashSeed uint32) *MurmurhashBucketer {
 }
 
 // Bucket buckets the user into the given experiment
-func (b MurmurhashBucketer) Bucket(bucketingID string, experiment entities.Experiment, group entities.Group) entities.Variation {
+func (b MurmurhashBucketer) Bucket(bucketingID string, experiment entities.Experiment, group entities.Group) (entities.Variation, reasons.Reason, error) {
 	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
-			logger.Info(fmt.Sprintf(`User "%s" is not in any experiment of group "%s"`, bucketingID, group.ID))
-			return entities.Variation{}
+			return entities.Variation{}, reasons.NotInGroup, nil
 		}
 	}
 
 	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
-		logger.Info(fmt.Sprintf(`User "%s" is not in any variation of experiment "%s"`, bucketingID, experiment.ID))
-		return entities.Variation{}
+		return entities.Variation{}, reasons.NotBucketedIntoVariation, nil
 	}
 
 	if variation, ok := experiment.Variations[bucketedVariationID]; ok {
-		return variation
+		return variation, reasons.BucketedIntoVariation, nil
 	}
 
-	return entities.Variation{}
+	return entities.Variation{}, reasons.BucketedVariationNotFound, nil
 }
 
 func (b MurmurhashBucketer) bucketToEntity(bucketKey string, trafficAllocations []entities.Range) (entityID string) {

optimizely/decision/bucketer/experiment_bucketer_test.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"testing"
 
+	"github.com/optimizely/go-sdk/optimizely/decision/reasons"
+
 	"github.com/optimizely/go-sdk/optimizely/entities"
 	"github.com/stretchr/testify/assert"
 )
@@ -69,7 +71,8 @@ func TestBucketToEntity(t *testing.T) {
 
 func TestBucketExclusionGroups(t *testing.T) {
 	experiment1 := entities.Experiment{
-		ID: "1886780721",
+		ID:  "1886780721",
+		Key: "experiment_1",
 		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"},
@@ -81,7 +84,8 @@ func TestBucketExclusionGroups(t *testing.T) {
 		GroupID: "1886780722",
 	}
 	experiment2 := entities.Experiment{
-		ID: "1886780723",
+		ID:  "1886780723",
+		Key: "experiment_2",
 		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"},
@@ -104,7 +108,11 @@ func TestBucketExclusionGroups(t *testing.T) {
 
 	bucketer := NewMurmurhashBucketer(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))
+	bucketedVariation, reason, _ := bucketer.Bucket("ppid2", experiment1, exclusionGroup)
+	assert.Equal(t, experiment1.Variations["22222"], bucketedVariation)
+	assert.Equal(t, reasons.BucketedIntoVariation, reason)
 	// 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))
+	bucketedVariation, reason, _ = bucketer.Bucket("ppid2", experiment2, exclusionGroup)
+	assert.Equal(t, entities.Variation{}, bucketedVariation)
+	assert.Equal(t, reasons.NotInGroup, reason)
 }

optimizely/decision/composite_service_test.go

@@ -26,7 +26,6 @@ import (
 
 func TestGetFeatureDecision(t *testing.T) {
 	mockProjectConfig := new(mockProjectConfig)
-	mockProjectConfig.On("GetFeatureByKey", testFeat3333Key).Return(testFeat3333, nil)
 	decisionContext := FeatureDecisionContext{
 		Feature:       &testFeat3333,
 		ProjectConfig: mockProjectConfig,

optimizely/decision/entities.go

@@ -18,6 +18,7 @@ package decision
 
 import (
 	"github.com/optimizely/go-sdk/optimizely"
+	"github.com/optimizely/go-sdk/optimizely/decision/reasons"
 	"github.com/optimizely/go-sdk/optimizely/entities"
 )
 
@@ -36,6 +37,7 @@ type FeatureDecisionContext struct {
 // Decision contains base information about a decision
 type Decision struct {
 	DecisionMade bool
+	Reason       reasons.Reason
 }
 
 // FeatureDecision contains the decision information about a feature

optimizely/decision/experiment_bucketer_service.go

@@ -52,12 +52,14 @@ func (s ExperimentBucketerService) GetDecision(decisionContext ExperimentDecisio
 	// bucket user into a variation
 	bucketingID, err := userContext.GetBucketingID()
 	if err != nil {
-		bLogger.Warning(err.Error())
-	} else {
-		bLogger.Debug(fmt.Sprintf(`Using bucketing ID: "%s"`, bucketingID))
+		return experimentDecision, fmt.Errorf(`Error computing bucketing ID for experiment "%s": "%s"`, experiment.Key, err.Error())
 	}
-	variation := s.bucketer.Bucket(bucketingID, *experiment, group)
+
+	bLogger.Debug(fmt.Sprintf(`Using bucketing ID: "%s"`, bucketingID))
+	// @TODO: handle error from bucketer
+	variation, reason, _ := s.bucketer.Bucket(bucketingID, *experiment, group)
 	experimentDecision.DecisionMade = true
+	experimentDecision.Reason = reason
 	experimentDecision.Variation = variation
 	return experimentDecision, nil
 }

optimizely/decision/experiment_bucketer_service_test.go

@@ -19,6 +19,8 @@ package decision
 import (
 	"testing"
 
+	"github.com/optimizely/go-sdk/optimizely/decision/reasons"
+
 	"github.com/optimizely/go-sdk/optimizely/entities"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
@@ -28,9 +30,9 @@ type MockBucketer struct {
 	mock.Mock
 }
 
-func (m *MockBucketer) Bucket(bucketingID string, experiment entities.Experiment, group entities.Group) entities.Variation {
+func (m *MockBucketer) Bucket(bucketingID string, experiment entities.Experiment, group entities.Group) (entities.Variation, reasons.Reason, error) {
 	args := m.Called(bucketingID, experiment, group)
-	return args.Get(0).(entities.Variation)
+	return args.Get(0).(entities.Variation), args.Get(1).(reasons.Reason), args.Error(2)
 }
 
 func TestExperimentBucketerGetDecision(t *testing.T) {
@@ -48,10 +50,11 @@ func TestExperimentBucketerGetDecision(t *testing.T) {
 		Variation: testExp1111Var2222,
 		Decision: Decision{
 			DecisionMade: true,
+			Reason:       reasons.BucketedIntoVariation,
 		},
 	}
 	mockBucketer := new(MockBucketer)
-	mockBucketer.On("Bucket", testUserContext.ID, testExp1111, entities.Group{}).Return(testExp1111Var2222, nil)
+	mockBucketer.On("Bucket", testUserContext.ID, testExp1111, entities.Group{}).Return(testExp1111Var2222, reasons.BucketedIntoVariation, nil)
 
 	experimentBucketerService := ExperimentBucketerService{
 		bucketer: mockBucketer,

optimizely/decision/experiment_targeting_service.go

@@ -17,6 +17,8 @@
 package decision
 
 import (
+	"github.com/optimizely/go-sdk/optimizely/decision/reasons"
+
 	"github.com/optimizely/go-sdk/optimizely/decision/evaluator"
 	"github.com/optimizely/go-sdk/optimizely/entities"
 )
@@ -46,6 +48,7 @@ func (s ExperimentTargetingService) GetDecision(decisionContext ExperimentDecisi
 		if !evalResult {
 			// user not targeted for experiment, return an empty variation
 			experimentDecision.DecisionMade = true
+			experimentDecision.Reason = reasons.DoesNotQualify
 		}
 		return experimentDecision, nil
 	}
@@ -58,6 +61,7 @@ func (s ExperimentTargetingService) GetDecision(decisionContext ExperimentDecisi
 		if evalResult == false {
 			// user not targeted for experiment, return an empty variation
 			experimentDecision.DecisionMade = true
+			experimentDecision.Reason = reasons.DoesNotQualify
 			return experimentDecision, nil
 		}
 	}

optimizely/decision/experiment_targeting_service_test.go

@@ -19,6 +19,8 @@ package decision
 import (
 	"testing"
 
+	"github.com/optimizely/go-sdk/optimizely/decision/reasons"
+
 	"github.com/optimizely/go-sdk/optimizely/decision/evaluator"
 	"github.com/optimizely/go-sdk/optimizely/entities"
 	"github.com/stretchr/testify/assert"
@@ -74,6 +76,7 @@ func TestExperimentTargetingGetDecisionNoAudienceCondTree(t *testing.T) {
 	expectedExperimentDecision := ExperimentDecision{
 		Decision: Decision{
 			DecisionMade: true,
+			Reason:       reasons.DoesNotQualify,
 		},
 	}
 
@@ -155,8 +158,8 @@ func TestExperimentTargetingGetDecisionWithAudienceCondTree(t *testing.T) {
 	expectedExperimentDecision := ExperimentDecision{
 		Decision: Decision{
 			DecisionMade: true,
+			Reason:       reasons.DoesNotQualify,
 		},
-		Variation: entities.Variation{},
 	}
 
 	audienceEvaluator := evaluator.NewTypedAudienceEvaluator()

optimizely/decision/helpers_test.go

@@ -64,30 +64,50 @@ func (m *MockFeatureDecisionService) GetDecision(decisionContext FeatureDecision
 	return args.Get(0).(FeatureDecision), args.Error(1)
 }
 
+// Single variation experiment
 const testExp1111Key = "test_experiment_1111"
-const testFeat3333Key = "my_test_feature_3333"
-
-var testExp1111Var2222 = entities.Variation{
-	ID:  "2222",
-	Key: "2222",
-}
 
+var testExp1111Var2222 = entities.Variation{ID: "2222", Key: "2222"}
 var testExp1111 = entities.Experiment{
 	ID:  "1111",
 	Key: testExp1111Key,
 	Variations: map[string]entities.Variation{
 		"2222": testExp1111Var2222,
 	},
 	TrafficAllocation: []entities.Range{
-		entities.Range{
-			EntityID:   "2222",
-			EndOfRange: 10000,
-		},
+		entities.Range{EntityID: "2222", EndOfRange: 10000},
 	},
 }
 
+// Simple feature test
+const testFeat3333Key = "my_test_feature_3333"
+
 var testFeat3333 = entities.Feature{
 	ID:                 "3333",
 	Key:                testFeat3333Key,
 	FeatureExperiments: []entities.Experiment{testExp1111},
 }
+
+// Feature rollout
+var testExp1112Var2222 = entities.Variation{ID: "2222", Key: "2222"}
+var testExp1112 = entities.Experiment{
+	ID:  "1112",
+	Key: testExp1111Key,
+	Variations: map[string]entities.Variation{
+		"2222": testExp1111Var2222,
+	},
+	TrafficAllocation: []entities.Range{
+		entities.Range{EntityID: "2222", EndOfRange: 10000},
+	},
+}
+
+const testFeatRollout3334Key = "test_feature_rollout_3334_key"
+
+var testFeatRollout3334 = entities.Feature{
+	ID:  "3334",
+	Key: testFeatRollout3334Key,
+	Rollout: entities.Rollout{
+		ID:          "4444",
+		Experiments: []entities.Experiment{testExp1112},
+	},
+}

optimizely/decision/reasons/reason.go

@@ -0,0 +1,40 @@
+/****************************************************************************
+ * Copyright 2019, 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 reasons
+
+// Reason is the reason for which a decision was made
+type Reason int
+
+const (
+	_ Reason = iota
+	// BucketedVariationNotFound - the bucketed variation ID is not in the config
+	BucketedVariationNotFound
+	// BucketedIntoVariation - the user is bucketed into a variation for the given experiment
+	BucketedIntoVariation
+	// DoesNotMeetRolloutTargeting - the user does not meet the rollout targeting rules
+	DoesNotMeetRolloutTargeting
+	// DoesNotQualify - the user did not qualify for the experiment
+	DoesNotQualify
+	// NoRolloutForFeature - there is no rollout for the given feature
+	NoRolloutForFeature
+	// RolloutHasNoExperiments - the rollout has no assigned experiments
+	RolloutHasNoExperiments
+	// NotBucketedIntoVariation - the user is not bucketed into a variation for the given experiment
+	NotBucketedIntoVariation
+	// NotInGroup - the user is not bucketed into the mutex group
+	NotInGroup
+)