1 package interfaces 2 3 import ( 4 "github.com/launchdarkly/go-sdk-common/v3/ldcontext" 5 "github.com/launchdarkly/go-sdk-common/v3/ldvalue" 6 ) 7 8 // FlagTracker is an interface for tracking changes in feature flag configurations. 9 // 10 // An implementation of this interface is returned by 11 // [github.com/launchdarkly/go-server-sdk/v6.LDClient.GetFlagTracker]. Application code should not 12 // implement this interface. 13 type FlagTracker interface { 14 // AddFlagChangeListener subscribes for notifications of feature flag changes in general. 15 // 16 // The returned channel will receive a new FlagChangeEvent value whenever the SDK receives any change to 17 // any feature flag's configuration, or to a user segment that is referenced by a feature flag. If the 18 // updated flag is used as a prerequisite for other flags, the SDK assumes that those flags may now 19 // behave differently and sends flag change events for them as well. 20 // 21 // Note that this does not necessarily mean the flag's value has changed for any particular evaluation 22 // context, only that some part of the flag configuration was changed so that it may return a different 23 // value than it previously returned for some context. If you want to track flag value changes, use 24 // AddFlagValueChangeListener instead. 25 // 26 // Change events only work if the SDK is actually connecting to LaunchDarkly (or using the file data source). 27 // If the SDK is only reading flags from a database (ldcomponents.ExternalUpdatesOnly) then it cannot 28 // know when there is a change, because flags are read on an as-needed basis. 29 // 30 // It is the caller's responsibility to consume values from the channel. Allowing values to accumulate in 31 // the channel can cause an SDK goroutine to be blocked. 32 AddFlagChangeListener() <-chan FlagChangeEvent 33 34 // RemoveFlagChangeListener unsubscribes from notifications of feature flag changes. The specified channel 35 // must be one that was previously returned by AddFlagChangeListener(); otherwise, the method has no effect. 36 RemoveFlagChangeListener(listener <-chan FlagChangeEvent) 37 38 // AddFlagValueChangeListener subscribes for notifications of changes in a specific feature flag's value 39 // for a specific set of context properties. 40 // 41 // When you call this method, it first immediately evaluates the feature flag. It then starts listening 42 // for feature flag configuration changes (using the same mechanism as AddFlagChangeListener), and whenever 43 // the specified feature flag changes, it re-evaluates the flag for the same evaluation context. It then 44 // pushes a new FlagValueChangeEvent to the channel if and only if the resulting value has changed. 45 // 46 // All feature flag evaluations require an instance of ldcontext.Context. If the feature flag you are tracking 47 // tracking does not have any targeting rules, you must still pass a dummy context such as 48 // ldcontext.New("for-global-flags"). If you do not want the context to appear on your dashboard, use 49 // the Anonymous property: ldcontext.NewBuilder("for-global-flags").Anonymous(true).Build(). 50 // 51 // The defaultValue parameter is used if the flag cannot be evaluated; it is the same as the corresponding 52 // parameter in LDClient.JSONVariation(). 53 AddFlagValueChangeListener( 54 flagKey string, 55 context ldcontext.Context, 56 defaultValue ldvalue.Value, 57 ) <-chan FlagValueChangeEvent 58 59 // RemoveFlagValueChangeListener unsubscribes from notifications of feature flag value changes. The 60 // specified channel must be one that was previously returned by AddFlagValueChangeListener(); otherwise, 61 // the method has no effect. 62 RemoveFlagValueChangeListener(listener <-chan FlagValueChangeEvent) 63 } 64 65 // FlagChangeEvent is a parameter type used with FlagTracker.AddFlagChangeListener(). 66 // 67 // This is not an analytics event to be sent to LaunchDarkly; it is a notification to the application. 68 type FlagChangeEvent struct { 69 // Key is the key of the feature flag whose configuration has changed. 70 // 71 // The specified flag may have been modified directly, or this may be an indirect change due to a change 72 // in some other flag that is a prerequisite for this flag, or a user segment that is referenced in the 73 // flag's rules. 74 Key string 75 } 76 77 // FlagValueChangeEvent is a parameter type used with FlagTracker.AddFlagValueChangeListener(). 78 // 79 // This is not an analytics event to be sent to LaunchDarkly; it is a notification to the application. 80 type FlagValueChangeEvent struct { 81 // Key is the key of the feature flag whose configuration has changed. 82 // 83 // The specified flag may have been modified directly, or this may be an indirect change due to a change 84 // in some other flag that is a prerequisite for this flag, or a user segment that is referenced in the 85 // flag's rules. 86 Key string 87 88 // OldValue is the last known value of the flag for the specified evaluation context prior to the update. 89 // 90 // Since flag values can be of any JSON data type, this is represented as ldvalue.Value. That type has 91 // methods for converting to a primitive Java type such as Value.BoolValue(). 92 // 93 // If the flag did not exist before or could not be evaluated, this will be whatever value was 94 // specified as the default with AddFlagValueChangeListener(). 95 OldValue ldvalue.Value 96 97 // NewValue is the new value of the flag for the specified evaluation context. 98 // 99 // Since flag values can be of any JSON data type, this is represented as ldvalue.Value. That type has 100 // methods for converting to a primitive Java type such Value.BoolValue(). 101 // 102 // If the flag could not be evaluated or was deleted, this will be whatever value was specified as 103 // the default with AddFlagValueChangeListener(). 104 NewValue ldvalue.Value 105 } 106