evaluation

type BigSegmentMembership interface {
	// CheckMembership tests whether the user is explicitly included or explicitly excluded in the
	// specified segment, or neither. The segment is identified by a segmentRef which is not the
	// same as the segment key-- it includes the key but also versioning information that the SDK
	// will provide. The store implementation should not be concerned with the format of this.
	//
	// If the user is explicitly included (regardless of whether the user is also explicitly
	// excluded or not-- that is, inclusion takes priority over exclusion), the method returns an
	// OptionalBool with a true value.
	//
	// If the user is explicitly excluded, and is not explicitly included, the method returns an
	// OptionalBool with a false value.
	//
	// If the user's status in the segment is undefined, the method returns OptionalBool{} with no
	// value (so calling IsDefined() on it will return false).
	CheckMembership(segmentRef string) ldvalue.OptionalBool
}

type BigSegmentProvider interface {
	// GetMembership queries a snapshot of the current segment state for a specific context
	// key.
	//
	// The underlying big segment store implementation will use a hash of the context key, rather
	// than the raw key. But computing the hash is the responsibility of the BigSegmentProvider
	// implementation rather than the evaluator, because there may already have a cached result for
	// that user, and we don't want to have to compute a hash repeatedly just to query a cache.
	//
	// Any given big segment is specific to one context kind, so we do not specify a context kind
	// here; it is OK for the membership results to include different context kinds for the same
	// key. That is, if for instance the context {kind: "user", key: "x"} is included in big segment
	// S1, and the context {kind: "org", key: "x"} is included in big segment S2, then the query
	// result for key "x" will show that it is included in both S1 and S2; even though those "x"
	// keys are really for two unrelated context kinds, we will always know which kind we mean if
	// we are specifically checking either S1 or S2, because S1 is defined as only applying to the
	// "user" kind and S2 is defined as only applying to the "org" kind.
	//
	// If the returned BigSegmentMembership is nil, it is treated the same as an implementation
	// whose CheckMembership method always returns an empty value.
	GetMembership(
		contextKey string,
	) (BigSegmentMembership, ldreason.BigSegmentsStatus)
}

type DataProvider interface {
	// GetFeatureFlag attempts to retrieve a feature flag from the data store by key.
	//
	// The evaluator calls this method if a flag contains a prerequisite condition referencing
	// another flag.
	//
	// The method returns nil if the flag was not found. The DataProvider should treat any deleted
	// flag as "not found" even if the data store contains a deleted flag placeholder for it.
	GetFeatureFlag(key string) *ldmodel.FeatureFlag
	// GetSegment attempts to retrieve a user segment from the data store by key.
	//
	// The evaluator calls this method if a clause in a flag rule uses the OperatorSegmentMatch
	// test.
	//
	// The method returns nil if the segment was not found. The DataProvider should treat any deleted
	// segment as "not found" even if the data store contains a deleted segment placeholder for it.
	GetSegment(key string) *ldmodel.Segment
}

type Evaluator interface {
	// Evaluate evaluates a feature flag for the specified context.
	//
	// The flag is passed by reference only for efficiency; the evaluator will never modify any flag
	// properties. Passing a nil flag will result in a panic.
	//
	// The evaluator does not know anything about analytics events; generating any appropriate analytics
	// events is the responsibility of the caller, who can also provide a callback in prerequisiteFlagEventRecorder
	// to be notified if any additional evaluations were done due to prerequisites. The prerequisiteFlagEventRecorder
	// parameter can be nil if you do not need to track prerequisite evaluations.
	Evaluate(
		flag *ldmodel.FeatureFlag,
		context ldcontext.Context,
		prerequisiteFlagEventRecorder PrerequisiteFlagEventRecorder,
	) Result
}

type EvaluatorOption interface {
	// contains filtered or unexported methods
}

type PrerequisiteFlagEvent struct {
	// TargetFlagKey is the key of the feature flag that had a prerequisite.
	TargetFlagKey string
	// Context is the context that the flag was evaluated for. We pass this back to the caller, even though the caller
	// already passed it to us in the Evaluate parameters, so that the caller can provide a stateless function for
	// PrerequisiteFlagEventRecorder rather than a closure (since closures are less efficient).
	Context ldcontext.Context
	// PrerequisiteFlag is the full configuration of the prerequisite flag. We need to pass the full flag here rather
	// than just the key because the flag's properties (such as TrackEvents) can affect how events are generated.
	// This is passed by reference for efficiency only, and will never be nil; the PrerequisiteFlagEventRecorder
	// must not modify the flag's properties.
	PrerequisiteFlag *ldmodel.FeatureFlag
	// PrerequisiteResult is the result of evaluating the prerequisite flag.
	PrerequisiteResult Result
}

type PrerequisiteFlagEventRecorder func(PrerequisiteFlagEvent)

type Result struct {
	// Detail contains the evaluation detail fields.
	Detail ldreason.EvaluationDetail

	// IsExperiment is true if this evaluation result was determined by an experiment. Normally if
	// this is true, then Detail.Reason will also communicate that fact, but there are some cases
	// related to the older experimentation model where this field may be true even if Detail.Reason
	// does not say anything special. When the SDK submits evaluation information to the event
	// processor, it should set the RequireReason field in ldevents.FlagEventProperties to this value.
	IsExperiment bool
}