prepare 6.2.0 release (#143)

Author: LaunchDarklyReleaseBot

.ldrelease/config.yml

@@ -16,7 +16,7 @@ template:
     # See Releaser docs - this causes the generated documentation to include all public APIs from CommonSdk
     LD_RELEASE_DOCS_ASSEMBLIES: LaunchDarkly.ServerSdk LaunchDarkly.CommonSdk
     LD_RELEASE_DOCS_TARGET_FRAMEWORK: net452
-    LD_RELEASE_TEST_TARGET_FRAMEWORK: net46
+    LD_RELEASE_TEST_TARGET_FRAMEWORK: net452
 
 releasableBranches:
   - name: master

src/LaunchDarkly.ServerSdk/Components.cs

@@ -22,6 +22,39 @@ namespace LaunchDarkly.Sdk.Server
     /// </remarks>
     public static class Components
     {
+        /// <summary>
+        /// Returns a configuration builder for the SDK's big segments feature.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// "Big segments" are a specific type of user segments. For more information, read the LaunchDarkly
+        /// documentation about user segments: https://docs.launchdarkly.com/home/users
+        /// </para>
+        /// <para>
+        /// After configuring this object, use <see cref="ConfigurationBuilder.BigSegments(IBigSegmentsConfigurationFactory)"/>
+        /// to store it in your SDK configuration. For example, using the Redis integration:
+        /// </para>
+        /// <code>
+        ///     var config = Configuration.Builder(sdkKey)
+        ///         .BigSegments(Components.BigSegments(Redis.DataStore().Prefix("app1"))
+        ///             .UserCacheSize(2000))
+        ///         .Build();
+        /// </code>
+        /// <para>
+        /// You must always specify the <paramref name="storeFactory"/> parameter, to tell the SDK what database
+        /// you are using. Several database integrations exist for the LaunchDarkly SDK, each with its own
+        /// behavior and options specific to that database; this is described via some implementation of
+        /// <see cref="IBigSegmentStoreFactory"/>. The <see cref="BigSegmentsConfigurationBuilder"/> adds
+        /// configuration options for aspects of SDK behavior that are independent of the database. In the
+        /// example above, <code>Prefix</code> is an option specifically for the Redis integration, whereas
+        /// <code>UserCacheSize</code> is an option that can be used for any data store type.
+        /// </para>
+        /// </remarks>
+        /// <param name="storeFactory">the factory for the underlying data store</param>
+        /// <returns>a <see cref="BigSegmentsConfigurationBuilder"/></returns>
+        public static BigSegmentsConfigurationBuilder BigSegments(IBigSegmentStoreFactory storeFactory) =>
+            new BigSegmentsConfigurationBuilder(storeFactory);
+
         /// <summary>
         /// Returns a configuration object that disables direct connection with LaunchDarkly for feature
         /// flag updates.

src/LaunchDarkly.ServerSdk/Configuration.cs

@@ -16,6 +16,11 @@ public class Configuration
     {
         #region Public properties
 
+        /// <summary>
+        /// A factory object that creates an implementation of <see cref="IBigSegmentsConfigurationFactory"/>.
+        /// </summary>
+        public IBigSegmentsConfigurationFactory BigSegmentsConfigurationFactory { get; }
+
         /// <summary>
         /// A factory object that creates an implementation of <see cref="IDataSource"/>, which will
         /// receive feature flag data.
@@ -98,7 +103,7 @@ public static Configuration Default(string sdkKey)
         }
 
         /// <summary>
-        /// Creates an <see cref="ConfigurationBuilder"/> for constructing a configuration object using a fluent syntax.
+        /// Creates a <see cref="ConfigurationBuilder"/> for constructing a configuration object using a fluent syntax.
         /// </summary>
         /// <remarks>
         /// This is the only method for building a <see cref="Configuration"/> if you are setting properties
@@ -146,6 +151,7 @@ public static ConfigurationBuilder Builder(Configuration fromConfiguration)
 
         internal Configuration(ConfigurationBuilder builder)
         {
+            BigSegmentsConfigurationFactory = builder._bigSegmentsConfigurationFactory;
             DataSourceFactory = builder._dataSourceFactory;
             DataStoreFactory = builder._dataStoreFactory;
             DiagnosticOptOut = builder._diagnosticOptOut;

src/LaunchDarkly.ServerSdk/ConfigurationBuilder.cs

@@ -26,10 +26,11 @@ public sealed class ConfigurationBuilder
     {
         #region Internal properties
 
-        internal static readonly TimeSpan DefaultStartWaitTime = TimeSpan.FromSeconds(5);
+        internal static readonly TimeSpan DefaultStartWaitTime = TimeSpan.FromSeconds(10);
 
         // Let's try to keep these properties and methods alphabetical so they're easy to find. Note that they
         // are internal rather than private so that they can be read by the Configuration constructor.
+        internal IBigSegmentsConfigurationFactory _bigSegmentsConfigurationFactory = null;
         internal IDataSourceFactory _dataSourceFactory = null;
         internal IDataStoreFactory _dataStoreFactory = null;
         internal bool _diagnosticOptOut = false;
@@ -51,6 +52,7 @@ internal ConfigurationBuilder(string sdkKey)
 
         internal ConfigurationBuilder(Configuration copyFrom)
         {
+            _bigSegmentsConfigurationFactory = copyFrom.BigSegmentsConfigurationFactory;
             _dataSourceFactory = copyFrom.DataSourceFactory;
             _dataStoreFactory = copyFrom.DataStoreFactory;
             _diagnosticOptOut = copyFrom.DiagnosticOptOut;
@@ -62,7 +64,6 @@ internal ConfigurationBuilder(Configuration copyFrom)
             _startWaitTime = copyFrom.StartWaitTime;
         }
 
-
         #endregion
 
         #region Public methods
@@ -77,6 +78,43 @@ public Configuration Build()
             return new Configuration(this);
         }
 
+        /// <summary>
+        /// Sets the configuration of the SDK's big segments feature.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// "Big segments" are a specific type of user segments. For more information, read the LaunchDarkly
+        /// documentation about user segments: https://docs.launchdarkly.com/home/users
+        /// </para>
+        /// <para>
+        /// If you are using this feature, you will normally specify a database implementation that matches how
+        /// the LaunchDarkly Relay Proxy is configured, since the Relay Proxy manages the big segment data.
+        /// </para>
+        /// <para>
+        /// By default, there is no implementation and big segments cannot be evaluated. In this case, any flag
+        /// evaluation that references a big segment will behave as if no users are included in any big
+        /// segments, and the <see cref="EvaluationReason"/> associated with any such flag evaluation will have
+        /// a <see cref="EvaluationReason.BigSegmentsStatus"/> of <see cref="BigSegmentsStatus.NotConfigured"/>.
+        /// </para>
+        /// </remarks>
+        /// <example>
+        /// <code>
+        ///     // This example uses the Redis integration
+        ///     var config = Configuration.Builder(sdkKey)
+        ///         .BigSegments(Components.BigSegments(Redis.DataStore().Prefix("app1"))
+        ///             .UserCacheSize(2000))
+        ///         .Build();
+        /// </code>
+        /// </example>
+        /// <param name="bigSegmentsConfigurationFactory">a configuration factory object returned by
+        /// <see cref="Components.BigSegments(IBigSegmentStoreFactory)"/></param>
+        /// <returns>the same builder</returns>
+        public ConfigurationBuilder BigSegments(IBigSegmentsConfigurationFactory bigSegmentsConfigurationFactory)
+        {
+            _bigSegmentsConfigurationFactory = bigSegmentsConfigurationFactory;
+            return this;
+        }
+
         /// <summary>
         /// Sets the implementation of the component that receives feature flag data from LaunchDarkly,
         /// using a factory object.

src/LaunchDarkly.ServerSdk/Integrations/BigSegmentsConfigurationBuilder.cs

@@ -0,0 +1,167 @@
+using System;
+using LaunchDarkly.Sdk.Server.Interfaces;
+
+namespace LaunchDarkly.Sdk.Server.Integrations
+{
+    /// <summary>
+    /// Contains methods for configuring the SDK's big segments behavior.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// "Big segments" are a specific type of user segments. For more information, read the LaunchDarkly
+    /// documentation about user segments: https://docs.launchdarkly.com/home/users
+    /// </para>
+    /// <para>
+    /// If you want to set non-default values for any of these properties, create a builder with
+    /// <see cref="Components.BigSegments(IBigSegmentStoreFactory)"/>, change its properties with the
+    /// methods of this class, and pass it to <see cref="ConfigurationBuilder.BigSegments(IBigSegmentsConfigurationFactory)"/>:
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    ///     // This example uses the Redis integration
+    ///     var config = Configuration.Builder(sdkKey)
+    ///         .BigSegments(Components.BigSegments(Redis.DataStore().Prefix("app1"))
+    ///             .UserCacheSize(2000))
+    ///         .Build();
+    /// </code>
+    /// </example>
+    public sealed class BigSegmentsConfigurationBuilder : IBigSegmentsConfigurationFactory
+    {
+        /// <summary>
+        /// Default value for <see cref="UserCacheSize(int)"/>.
+        /// </summary>
+        public const int DefaultUserCacheSize = 1000;
+
+        /// <summary>
+        /// Default value for <see cref="UserCacheTime(TimeSpan)"/>: five seconds.
+        /// </summary>
+        public static readonly TimeSpan DefaultUserCacheTime = TimeSpan.FromSeconds(5);
+
+        /// <summary>
+        /// Default value for <see cref="StatusPollInterval(TimeSpan)"/>: five seconds.
+        /// </summary>
+        public static readonly TimeSpan DefaultStatusPollInterval = TimeSpan.FromSeconds(5);
+
+        /// <summary>
+        /// Default value for <see cref="StaleAfter(TimeSpan)"/>: two minutes.
+        /// </summary>
+        public static readonly TimeSpan DefaultStaleAfter = TimeSpan.FromMinutes(2);
+
+        private readonly IBigSegmentStoreFactory _storeFactory;
+        private int _userCacheSize = DefaultUserCacheSize;
+        private TimeSpan _userCacheTime = DefaultUserCacheTime;
+        private TimeSpan _statusPollInterval = DefaultStatusPollInterval;
+        private TimeSpan _staleAfter = DefaultStaleAfter;
+
+        internal BigSegmentsConfigurationBuilder(IBigSegmentStoreFactory storeFactory)
+        {
+            _storeFactory = storeFactory;
+        }
+
+        /// <summary>
+        /// Sets the maximum number of users whose big segment state will be cached by the SDK
+        /// at any given time.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// To reduce database traffic, the SDK maintains a least-recently-used cache by user key. When a feature
+        /// flag that references a big segment is evaluated for some user who is not currently in the cache, the
+        /// SDK queries the database for all big segment memberships of that user, and stores them together in a
+        /// single cache entry. If the cache is full, the oldest entry is dropped.
+        /// </para>
+        /// <para>
+        /// A higher value for <see cref="UserCacheSize(int)"/> means that database queries for big segments will
+        /// be done less often for recently-referenced users, if the application has many users, at the cost of
+        /// increased memory used by the cache.
+        /// </para>
+        /// <para>
+        /// Cache entries can also expire based on the setting of <see cref="UserCacheTime(TimeSpan)"/>.
+        /// </para>
+        /// </remarks>
+        /// <param name="userCacheSize">the maximum number of user states to cache</param>
+        /// <returns>the builder</returns>
+        /// <seealso cref="DefaultUserCacheSize"/>
+        public BigSegmentsConfigurationBuilder UserCacheSize(int userCacheSize)
+        {
+            _userCacheSize = userCacheSize;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the maximum length of time that the big segment state for a user will be cached
+        /// by the SDK.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// See <see cref="UserCacheSize(int)"/> for more about this cache. A higher value for
+        /// <see cref="UserCacheTime(TimeSpan)"/> means that database queries for the big segment state of any
+        /// given user will be done less often, but that changes to segment membership may not be detected as soon.
+        /// </para>
+        /// </remarks>
+        /// <param name="userCacheTime">the cache TTL</param>
+        /// <returns>the builder</returns>
+        /// <seealso cref="DefaultUserCacheTime"/>
+        public BigSegmentsConfigurationBuilder UserCacheTime(TimeSpan userCacheTime)
+        {
+            _userCacheTime = userCacheTime;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the interval at which the SDK will poll the big segment store to make sure
+        /// it is available and to determine how long ago it was updated.
+        /// </summary>
+        /// <param name="statusPollInterval">the status polling interval (any value less than or
+        /// equal to zero will be changed to <see cref="DefaultStatusPollInterval"/>)</param>
+        /// <returns>the builder</returns>
+        /// <seealso cref="DefaultStatusPollInterval"/>
+        public BigSegmentsConfigurationBuilder StatusPollInterval(TimeSpan statusPollInterval)
+        {
+            _statusPollInterval = statusPollInterval > TimeSpan.Zero ? statusPollInterval :
+                DefaultStatusPollInterval;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the maximum length of time between updates of the big segments data before the data
+        /// is considered out of date.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Normally, the LaunchDarkly Relay Proxy updates a timestamp in the big segments store at intervals to
+        /// confirm that it is still in sync with the LaunchDarkly data, even if there have been no changes to the
+        /// data. If the timestamp falls behind the current time by the amount specified in
+        /// <see cref="StaleAfter(TimeSpan)"/>, the SDK assumes that something is not working correctly in this
+        /// process and that the data may not be accurate.
+        /// </para>
+        /// <para>
+        /// While in a stale state, the SDK will still continue using the last known data, but
+        /// <see cref="IBigSegmentStoreStatusProvider.Status"/> will return true in its Stale property, and any
+        /// <see cref="EvaluationReason"/> generated from a feature flag that references a big segment will have
+        /// a <see cref="EvaluationReason.BigSegmentsStatus"/> of <see cref="BigSegmentsStatus.Stale"/>.
+        /// </para>
+        /// </remarks>
+        /// <param name="staleAfter">the time limit for marking the data as stale (any value less
+        /// than or equal to zero will be changed to <see cref="DefaultStaleAfter"/>)</param>
+        /// <returns>the builder</returns>
+        public BigSegmentsConfigurationBuilder StaleAfter(TimeSpan staleAfter)
+        {
+            _staleAfter = staleAfter > TimeSpan.Zero ? staleAfter : DefaultStaleAfter;
+            return this;
+        }
+
+        /// <inheritdoc/>
+        public BigSegmentsConfiguration CreateBigSegmentsConfiguration(LdClientContext context)
+        {
+            var store = _storeFactory is null ? null : _storeFactory.CreateBigSegmentStore(context);
+            return new BigSegmentsConfiguration(
+                store,
+                _userCacheSize,
+                _userCacheTime,
+                _statusPollInterval,
+                _staleAfter
+                );
+        }
+    }
+}

src/LaunchDarkly.ServerSdk/Integrations/TestData.cs

@@ -215,7 +215,8 @@ internal TestData UsePreconfiguredSegment(Segment segment)
                 {
                     segment = new Segment(segment.Key,
                         newVersion,
-                        segment.Deleted, segment.Included, segment.Excluded, segment.Rules, segment.Salt);
+                        segment.Deleted, segment.Included, segment.Excluded, segment.Rules, segment.Salt,
+                        segment.Unbounded, segment.Generation);
                 }
                 newItem = new ItemDescriptor(newVersion, segment);
                 _currentSegments[segment.Key] = newItem;

src/LaunchDarkly.ServerSdk/Interfaces/BigSegmentStoreStatus.cs

@@ -0,0 +1,45 @@
+using System;
+
+namespace LaunchDarkly.Sdk.Server.Interfaces
+{
+    /// <summary>
+    /// Information about the status of a big segment store, provided by
+    /// <see cref="IBigSegmentStoreStatusProvider"/>.
+    /// </summary>
+    /// <remarks>
+    /// "Big segments" are a specific type of user segments. For more information, read the LaunchDarkly
+    /// documentation about user segments: https://docs.launchdarkly.com/home/users
+    /// </remarks>
+    public struct BigSegmentStoreStatus
+    {
+        /// <summary>
+        /// True if the big segment store is able to respond to queries, so that the SDK can
+        /// evaluate whether a user is in a segment or not.
+        /// </summary>
+        /// <remarks>
+        /// If this property is false, the store is not able to make queries (for instance, it may not have
+        /// a valid database connection). In this case, the SDK will treat any reference to a big segment
+        /// as if no users are included in that segment. Also, the <see cref="EvaluationReason"/>
+        /// associated with any flag evaluation that references a big segment when the store is not
+        /// available will have a <see cref="EvaluationReason.BigSegmentsStatus"/> of
+        /// <see cref="BigSegmentsStatus.StoreError"/>.
+        /// </remarks>
+        public bool Available { get; set; }
+
+        /// <summary>
+        /// True if the big segment store is available, but has not been updated within the amount of time
+        /// specified by <see cref="LaunchDarkly.Sdk.Server.Integrations.BigSegmentsConfigurationBuilder.StaleAfter(TimeSpan)"/>.
+        /// </summary>
+        /// <remarks>
+        /// This may indicate that the LaunchDarkly Relay Proxy, which populates the store, has stopped
+        /// running or has become unable to receive fresh data from LaunchDarkly. Any feature flag
+        /// evaluations that reference a big segment will be using the last known data, which may be out
+        /// of date.
+        /// </remarks>
+        public bool Stale { get; set; }
+
+        /// <inheritdoc/>
+        public override string ToString() =>
+            string.Format("(Available={0},Stale={1})", Available, Stale);
+    }
+}