add EvaluationDetail and EvaluationReason

Makefile

@@ -14,7 +14,7 @@ clean:
 
 test:
 	@# Note, we need to specify all these packages individually for go test in order to remain 1.8-compatible
-	go test -race -v ./ldvalue
+	go test -race -v ./ldvalue ./ldreason
 
 $(LINTER):
 	curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | bash -s $(GOLANGCI_LINT_VERSION)

ldreason/detail.go

@@ -0,0 +1,42 @@
+// Package ldreason provides types that describe the outcome of a LaunchDarkly flag evaluation.
+//
+// You do not need to use these types to evaluate feature flags with the LaunchDarkly SDK. They are
+// only required for the "detail" methods that allow you to determine whether the result of a flag
+// evaluation was due to, for instance, user key targeting or a specific flag rule.
+package ldreason
+
+import (
+	"gopkg.in/launchdarkly/go-server-sdk-core.v1/ldvalue"
+)
+
+// EvaluationDetail is an object returned by LDClient.VariationDetail, combining the result of a
+// flag evaluation with an explanation of how it was calculated.
+type EvaluationDetail struct {
+	// Value is the result of the flag evaluation. This will be either one of the flag's variations or
+	// the default value that was passed to the Variation method.
+	Value ldvalue.Value
+	// VariationIndex is the index of the returned value within the flag's list of variations, e.g.
+	// 0 for the first variation. A negative number indicates that the application default value was
+	// returned because the flag could not be evaluated.
+	VariationIndex int
+	// Reason is an EvaluationReason object describing the main factor that influenced the flag
+	// evaluation value.
+	Reason EvaluationReason
+}
+
+// IsDefaultValue returns true if the result of the evaluation was the application default value.
+// This means that an error prevented the flag from being evaluated; the Reason field should contain
+// an error value such as NewEvalReasonError(EvalErrorFlagNotFound).
+func (d EvaluationDetail) IsDefaultValue() bool {
+	return d.VariationIndex < 0
+}
+
+// NewEvaluationDetail constructs an EvaluationDeteail, specifying all fields.
+func NewEvaluationDetail(value ldvalue.Value, variationIndex int, reason EvaluationReason) EvaluationDetail {
+	return EvaluationDetail{Value: value, VariationIndex: variationIndex, Reason: reason}
+}
+
+// NewEvaluationDetailForError constructs an EvaluationDetail for an error condition.
+func NewEvaluationDetailForError(errorKind EvalErrorKind, defaultValue ldvalue.Value) EvaluationDetail {
+	return EvaluationDetail{Value: defaultValue, VariationIndex: -1, Reason: NewEvalReasonError(errorKind)}
+}

ldreason/detail_test.go

@@ -0,0 +1,24 @@
+package ldreason
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"gopkg.in/launchdarkly/go-server-sdk-core.v1/ldvalue"
+)
+
+func TestDetailConstructor(t *testing.T) {
+	detail := NewEvaluationDetail(ldvalue.Bool(true), 1, NewEvalReasonFallthrough())
+	assert.Equal(t, ldvalue.Bool(true), detail.Value)
+	assert.Equal(t, 1, detail.VariationIndex)
+	assert.Equal(t, NewEvalReasonFallthrough(), detail.Reason)
+	assert.False(t, detail.IsDefaultValue())
+}
+
+func TestDetailErrorConstructor(t *testing.T) {
+	detail := NewEvaluationDetailForError(EvalErrorFlagNotFound, ldvalue.Bool(false))
+	assert.Equal(t, ldvalue.Bool(false), detail.Value)
+	assert.Equal(t, -1, detail.VariationIndex)
+	assert.Equal(t, NewEvalReasonError(EvalErrorFlagNotFound), detail.Reason)
+	assert.True(t, detail.IsDefaultValue())
+}

ldreason/reason.go

@@ -0,0 +1,183 @@
+package ldreason
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// EvalReasonKind defines the possible values of the Kind property of EvaluationReason.
+type EvalReasonKind string
+
+const (
+	// EvalReasonOff indicates that the flag was off and therefore returned its configured off value.
+	EvalReasonOff EvalReasonKind = "OFF"
+	// EvalReasonTargetMatch indicates that the user key was specifically targeted for this flag.
+	EvalReasonTargetMatch EvalReasonKind = "TARGET_MATCH"
+	// EvalReasonRuleMatch indicates that the user matched one of the flag's rules.
+	EvalReasonRuleMatch EvalReasonKind = "RULE_MATCH"
+	// EvalReasonPrerequisiteFailed indicates that the flag was considered off because it had at
+	// least one prerequisite flag that either was off or did not return the desired variation.
+	EvalReasonPrerequisiteFailed EvalReasonKind = "PREREQUISITE_FAILED"
+	// EvalReasonFallthrough indicates that the flag was on but the user did not match any targets
+	// or rules.
+	EvalReasonFallthrough EvalReasonKind = "FALLTHROUGH"
+	// EvalReasonError indicates that the flag could not be evaluated, e.g. because it does not
+	// exist or due to an unexpected error. In this case the result value will be the default value
+	// that the caller passed to the client.
+	EvalReasonError EvalReasonKind = "ERROR"
+)
+
+// EvalErrorKind defines the possible values of the ErrorKind property of EvaluationReason.
+type EvalErrorKind string
+
+const (
+	// EvalErrorClientNotReady indicates that the caller tried to evaluate a flag before the client
+	// had successfully initialized.
+	EvalErrorClientNotReady EvalErrorKind = "CLIENT_NOT_READY"
+	// EvalErrorFlagNotFound indicates that the caller provided a flag key that did not match any
+	// known flag.
+	EvalErrorFlagNotFound EvalErrorKind = "FLAG_NOT_FOUND"
+	// EvalErrorMalformedFlag indicates that there was an internal inconsistency in the flag data,
+	// e.g. a rule specified a nonexistent variation.
+	EvalErrorMalformedFlag EvalErrorKind = "MALFORMED_FLAG"
+	// EvalErrorUserNotSpecified indicates that the caller passed a user without a key for the user
+	// parameter.
+	EvalErrorUserNotSpecified EvalErrorKind = "USER_NOT_SPECIFIED"
+	// EvalErrorWrongType indicates that the result value was not of the requested type, e.g. you
+	// called BoolVariationDetail but the value was an integer.
+	EvalErrorWrongType EvalErrorKind = "WRONG_TYPE"
+	// EvalErrorException indicates that an unexpected error stopped flag evaluation; check the
+	// log for details.
+	EvalErrorException EvalErrorKind = "EXCEPTION"
+)
+
+// EvaluationReason describes the reason that a flag evaluation producted a particular value.
+//
+// This struct is immutable; its properties can be accessed only via getter methods.
+type EvaluationReason struct {
+	kind            EvalReasonKind
+	ruleIndex       int
+	ruleID          string
+	prerequisiteKey string
+	errorKind       EvalErrorKind
+}
+
+// String returns a concise string representation of the reason. Examples: "OFF", "ERROR(WRONG_TYPE)".
+func (r EvaluationReason) String() string {
+	switch r.kind {
+	case EvalReasonRuleMatch:
+		return fmt.Sprintf("%s(%d,%s)", r.kind, r.ruleIndex, r.ruleID)
+	case EvalReasonPrerequisiteFailed:
+		return fmt.Sprintf("%s(%s)", r.kind, r.prerequisiteKey)
+	case EvalReasonError:
+		return fmt.Sprintf("%s(%s)", r.kind, r.errorKind)
+	default:
+		return string(r.GetKind())
+	}
+}
+
+// GetKind describes the general category of the reason.
+func (r EvaluationReason) GetKind() EvalReasonKind {
+	return r.kind
+}
+
+// GetRuleIndex provides the index of the rule that was matched (0 being the first), if
+// the Kind is EvalReasonRuleMatch. Otherwise it returns -1.
+func (r EvaluationReason) GetRuleIndex() int {
+	if r.kind == EvalReasonRuleMatch {
+		return r.ruleIndex
+	}
+	return -1
+}
+
+// GetRuleID provides the unique identifier of the rule that was matched, if the Kind is
+// EvalReasonRuleMatch. Otherwise it returns an empty string. Unlike the rule index, this
+// identifier will not change if other rules are added or deleted.
+func (r EvaluationReason) GetRuleID() string {
+	return r.ruleID
+}
+
+// GetPrerequisiteKey provides the flag key of the prerequisite that failed, if the Kind
+// is EvalReasonPrerequisiteFailed. Otherwise it returns an empty string.
+func (r EvaluationReason) GetPrerequisiteKey() string {
+	return r.prerequisiteKey
+}
+
+// GetErrorKind describes the general category of the error, if the Kind is EvalReasonError.
+// Otherwise it returns an empty string.
+func (r EvaluationReason) GetErrorKind() EvalErrorKind {
+	return r.errorKind
+}
+
+// NewEvalReasonOff returns an EvaluationReason whose Kind is EvalReasonOff.
+func NewEvalReasonOff() EvaluationReason {
+	return EvaluationReason{kind: EvalReasonOff}
+}
+
+// NewEvalReasonFallthrough returns an EvaluationReason whose Kind is EvalReasonFallthrough.
+func NewEvalReasonFallthrough() EvaluationReason {
+	return EvaluationReason{kind: EvalReasonFallthrough}
+}
+
+// NewEvalReasonTargetMatch returns an EvaluationReason whose Kind is EvalReasonTargetMatch.
+func NewEvalReasonTargetMatch() EvaluationReason {
+	return EvaluationReason{kind: EvalReasonTargetMatch}
+}
+
+// NewEvalReasonRuleMatch returns an EvaluationReason whose Kind is EvalReasonRuleMatch.
+func NewEvalReasonRuleMatch(ruleIndex int, ruleID string) EvaluationReason {
+	return EvaluationReason{kind: EvalReasonRuleMatch, ruleIndex: ruleIndex, ruleID: ruleID}
+}
+
+// NewEvalReasonPrerequisiteFailed returns an EvaluationReason whose Kind is EvalReasonPrerequisiteFailed.
+func NewEvalReasonPrerequisiteFailed(prereqKey string) EvaluationReason {
+	return EvaluationReason{kind: EvalReasonPrerequisiteFailed, prerequisiteKey: prereqKey}
+}
+
+// NewEvalReasonError returns an EvaluationReason whose Kind is EvalReasonError.
+func NewEvalReasonError(errorKind EvalErrorKind) EvaluationReason {
+	return EvaluationReason{kind: EvalReasonError, errorKind: errorKind}
+}
+
+type evaluationReasonForMarshaling struct {
+	Kind            EvalReasonKind `json:"kind"`
+	RuleIndex       *int           `json:"ruleIndex,omitempty"`
+	RuleID          string         `json:"ruleId,omitempty"`
+	PrerequisiteKey string         `json:"prerequisiteKey,omitempty"`
+	ErrorKind       EvalErrorKind  `json:"errorKind,omitempty"`
+}
+
+// MarshalJSON implements custom JSON serialization for EvaluationReason.
+func (r EvaluationReason) MarshalJSON() ([]byte, error) {
+	if r.kind == "" {
+		return []byte("null"), nil
+	}
+	erm := evaluationReasonForMarshaling{
+		Kind:            r.kind,
+		RuleID:          r.ruleID,
+		PrerequisiteKey: r.prerequisiteKey,
+		ErrorKind:       r.errorKind,
+	}
+	if r.kind == EvalReasonRuleMatch {
+		erm.RuleIndex = &r.ruleIndex
+	}
+	return json.Marshal(erm)
+}
+
+// UnmarshalJSON implements custom JSON deserialization for EvaluationReason.
+func (r *EvaluationReason) UnmarshalJSON(data []byte) error {
+	var erm evaluationReasonForMarshaling
+	if err := json.Unmarshal(data, &erm); err != nil {
+		return nil
+	}
+	*r = EvaluationReason{
+		kind:            erm.Kind,
+		ruleID:          erm.RuleID,
+		prerequisiteKey: erm.PrerequisiteKey,
+		errorKind:       erm.ErrorKind,
+	}
+	if erm.RuleIndex != nil {
+		r.ruleIndex = *erm.RuleIndex
+	}
+	return nil
+}

ldreason/reason_test.go

@@ -0,0 +1,36 @@
+package ldreason
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestReasonSerializationAndDeserialization(t *testing.T) {
+	params := []struct {
+		reason       EvaluationReason
+		stringRep    string
+		expectedJSON string
+	}{
+		{EvaluationReason{}, "", "null"},
+		{NewEvalReasonOff(), "OFF", `{"kind":"OFF"}`},
+		{NewEvalReasonFallthrough(), "FALLTHROUGH", `{"kind":"FALLTHROUGH"}`},
+		{NewEvalReasonTargetMatch(), "TARGET_MATCH", `{"kind":"TARGET_MATCH"}`},
+		{NewEvalReasonRuleMatch(1, "x"), "RULE_MATCH(1,x)", `{"kind":"RULE_MATCH","ruleIndex":1,"ruleId":"x"}`},
+		{NewEvalReasonPrerequisiteFailed("x"), "PREREQUISITE_FAILED(x)", `{"kind":"PREREQUISITE_FAILED","prerequisiteKey":"x"} `},
+		{NewEvalReasonError(EvalErrorWrongType), "ERROR(WRONG_TYPE)", `{"kind":"ERROR","errorKind":"WRONG_TYPE"}`},
+	}
+	for _, param := range params {
+		actual, err := json.Marshal(param.reason)
+		assert.NoError(t, err)
+		assert.JSONEq(t, param.expectedJSON, string(actual))
+
+		var r1 EvaluationReason
+		err = json.Unmarshal(actual, &r1)
+		assert.NoError(t, err)
+		assert.Equal(t, param.reason, r1)
+
+		assert.Equal(t, param.stringRep, param.reason.String())
+	}
+}