feat: Add Identify hooks to Client SDK

pkgs/sdk/client/src/Hooks/Hook.cs

@@ -74,6 +74,35 @@ public virtual SeriesData BeforeEvaluation(EvaluationSeriesContext context, Seri
         public virtual SeriesData AfterEvaluation(EvaluationSeriesContext context, SeriesData data,
             EvaluationDetail<LdValue> detail) => data;
 
+
+        /// <summary>
+        /// BeforeIdentify is executed by the SDK before an identify operation.
+        ///
+        /// The modified data is not shared with any other hook. It will be passed to subsequent stages in the identify
+        /// series, including <see cref="AfterIdentify"/>.
+        ///
+        /// </summary>
+        /// <param name="context">parameters associated with this identify operation</param>
+        /// <param name="data">user-configurable data, currently empty</param>
+        /// <returns>user-configurable data, which will be forwarded to <see cref="AfterIdentify"/></returns>
+        public virtual SeriesData BeforeIdentify(IdentifySeriesContext context, SeriesData data) =>
+            data;
+
+
+        /// <summary>
+        /// AfterIdentify is executed by the SDK after an identify operation.
+        ///
+        /// The function should return the given <see cref="SeriesData"/> unmodified, for forward compatibility with subsequent
+        /// stages that may be added.
+        ///
+        /// </summary>
+        /// <param name="context">parameters associated with this identify operation</param>
+        /// <param name="data">user-configurable data from the <see cref="BeforeIdentify"/> stage</param>
+        /// <param name="result">the result of the identify operation</param>
+        /// <returns>user-configurable data, which is currently unused but may be forwarded to subsequent stages in future versions of the SDK</returns>
+        public virtual SeriesData AfterIdentify(IdentifySeriesContext context, SeriesData data,
+            IdentifySeriesResult result) => data;
+
         /// <summary>
         /// Constructs a new Hook with the given name. The name may be used in log messages.
         /// </summary>

pkgs/sdk/client/src/Hooks/IdentifySeriesContext.cs

@@ -0,0 +1,33 @@
+using System;
+
+namespace LaunchDarkly.Sdk.Client.Hooks
+{
+    /// <summary>
+    /// IdentifySeriesContext represents parameters associated with an identify operation. It is
+    /// made available in <see cref="Hook"/> stage callbacks.
+    /// </summary>
+    public sealed class IdentifySeriesContext
+    {
+        /// <summary>
+        /// The Context being identified.
+        /// </summary>
+        public Context Context { get; }
+
+        /// <summary>
+        /// The timeout for the identify operation. A value of <see cref="TimeSpan.Zero"/> indicates
+        /// that no timeout was specified.
+        /// </summary>
+        public TimeSpan Timeout { get; }
+
+        /// <summary>
+        /// Constructs a new IdentifySeriesContext.
+        /// </summary>
+        /// <param name="context">the context being identified</param>
+        /// <param name="timeout">the timeout for the identify operation</param>
+        public IdentifySeriesContext(Context context, TimeSpan timeout)
+        {
+            Context = context;
+            Timeout = timeout;
+        }
+    }
+}

pkgs/sdk/client/src/Hooks/IdentifySeriesResult.cs

@@ -0,0 +1,38 @@
+namespace LaunchDarkly.Sdk.Client.Hooks
+{
+    /// <summary>
+    /// IdentifySeriesResult contains the outcome of an identify operation.
+    /// </summary>
+    public sealed class IdentifySeriesResult
+    {
+        /// <summary>
+        /// Represents the possible statuses of an identify operation.
+        /// </summary>
+        public enum IdentifySeriesStatus
+        {
+            /// <summary>
+            /// The identify operation completed successfully.
+            /// </summary>
+            Completed,
+
+            /// <summary>
+            /// The identify operation encountered an error.
+            /// </summary>
+            Error
+        }
+
+        /// <summary>
+        /// The status of the identify operation.
+        /// </summary>
+        public IdentifySeriesStatus Status { get; }
+
+        /// <summary>
+        /// Constructs a new IdentifySeriesResult.
+        /// </summary>
+        /// <param name="status">the status of the identify operation</param>
+        public IdentifySeriesResult(IdentifySeriesStatus status)
+        {
+            Status = status;
+        }
+    }
+}

pkgs/sdk/client/src/ILdClientExtensions.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Interfaces;
 

pkgs/sdk/client/src/Interfaces/IFlagTracker.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 
 namespace LaunchDarkly.Sdk.Client.Interfaces
 {

pkgs/sdk/client/src/Interfaces/ILdClient.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Integrations;

pkgs/sdk/client/src/Internal/Hooks/Executor/Executor.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Threading.Tasks;
 using LaunchDarkly.Logging;
 using LaunchDarkly.Sdk.Client.Hooks;
 using LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces;
@@ -16,12 +17,17 @@ internal sealed class Executor : IHookExecutor
         private readonly IStageExecutor<EvaluationSeriesContext> _beforeEvaluation;
         private readonly IStageExecutor<EvaluationSeriesContext, EvaluationDetail<LdValue>> _afterEvaluation;
 
+        private readonly IStageExecutor<IdentifySeriesContext> _beforeIdentify;
+        private readonly IStageExecutor<IdentifySeriesContext, IdentifySeriesResult> _afterIdentify;
+
         public Executor(Logger logger, IEnumerable<Hook> hooks)
         {
             _logger = logger;
             _hooks = hooks.ToList();
             _beforeEvaluation = new BeforeEvaluation(logger, _hooks, EvaluationStage.Order.Forward);
             _afterEvaluation = new AfterEvaluation(logger, _hooks, EvaluationStage.Order.Reverse);
+            _beforeIdentify = new BeforeIdentify(logger, _hooks, EvaluationStage.Order.Forward);
+            _afterIdentify = new AfterIdentify(logger, _hooks, EvaluationStage.Order.Reverse);
         }
 
         public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
@@ -38,6 +44,31 @@ public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
             return detail;
         }
 
+        public async Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Func<Task<bool>> identify)
+        {
+            var identifyContext = new IdentifySeriesContext(context, maxWaitTime);
+            var seriesData = _beforeIdentify.Execute(identifyContext, default);
+
+            try
+            {
+                var result = await identify();
+
+                _afterIdentify.Execute(identifyContext,
+                    new IdentifySeriesResult(IdentifySeriesResult.IdentifySeriesStatus.Completed),
+                    seriesData);
+
+                return result;
+            }
+            catch (Exception)
+            {
+                _afterIdentify.Execute(identifyContext,
+                    new IdentifySeriesResult(IdentifySeriesResult.IdentifySeriesStatus.Error),
+                    seriesData);
+
+                throw;
+            }
+        }
+
         public void Dispose()
         {
             foreach (var hook in _hooks)

pkgs/sdk/client/src/Internal/Hooks/Executor/NoopExecutor.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Hooks;
 using LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces;
 
@@ -13,6 +14,9 @@ internal sealed class NoopExecutor : IHookExecutor
         public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
             LdValue.Converter<T> converter, Func<EvaluationDetail<T>> evaluate) => evaluate();
 
+        public Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Func<Task<bool>> identify) =>
+            identify();
+
         public void Dispose()
         {
         }

pkgs/sdk/client/src/Internal/Hooks/Interfaces/IHookExecutor.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Hooks;
 
 namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces
@@ -12,7 +13,8 @@ namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces
     internal interface IHookExecutor : IDisposable
     {
         /// <summary>
-        /// EvaluationSeries should run the evaluation series for each configured hook.
+        /// Runs the evaluation series for each configured hook, invoking the <paramref name="evaluate"/>
+        /// delegate to obtain the flag value. Exceptions thrown by the delegate are propagated to the caller.
         /// </summary>
         /// <param name="context">context for the evaluation series</param>
         /// <param name="converter">used to convert the primitive evaluation value into a wrapped <see cref="LdValue"/> suitable for use in hooks</param>
@@ -21,5 +23,16 @@ internal interface IHookExecutor : IDisposable
         /// <returns>the EvaluationDetail returned from the evaluator</returns>
         EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
             LdValue.Converter<T> converter, Func<EvaluationDetail<T>> evaluate);
+
+        /// <summary>
+        /// Runs the identify series for each configured hook, invoking the <paramref name="identify"/>
+        /// delegate to perform the identify operation. Exceptions thrown by the delegate are propagated
+        /// to the caller.
+        /// </summary>
+        /// <param name="context">the evaluation context being identified</param>
+        /// <param name="maxWaitTime">the timeout for the identify operation</param>
+        /// <param name="identify">async function that performs the identify operation</param>
+        /// <returns>the result of the identify operation</returns>
+        Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Func<Task<bool>> identify);
     }
 }

pkgs/sdk/client/src/Internal/Hooks/Series/IdentifySeries.cs

@@ -0,0 +1,89 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Linq;
+using LaunchDarkly.Logging;
+using LaunchDarkly.Sdk.Client.Hooks;
+using LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces;
+
+namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Series
+{
+    using SeriesData = ImmutableDictionary<string, object>;
+
+    internal class IdentifyStage
+    {
+        protected enum Stage
+        {
+            BeforeIdentify,
+            AfterIdentify
+        }
+
+        protected readonly EvaluationStage.Order _order;
+        private readonly Logger _logger;
+
+        protected IdentifyStage(Logger logger, EvaluationStage.Order order)
+        {
+            _logger = logger;
+            _order = order;
+        }
+
+        protected void LogFailure(IdentifySeriesContext context, Hook h, Stage stage, Exception e)
+        {
+            _logger.Error("During identify of context \"{0}\", stage \"{1}\" of hook \"{2}\" reported error: {3}",
+                context.Context.Key, stage.ToString(), h.Metadata.Name, e.Message);
+        }
+    }
+
+    internal sealed class BeforeIdentify : IdentifyStage, IStageExecutor<IdentifySeriesContext>
+    {
+        private readonly IEnumerable<Hook> _hooks;
+
+        public BeforeIdentify(Logger logger, IEnumerable<Hook> hooks, EvaluationStage.Order order) : base(logger, order)
+        {
+            _hooks = (order == EvaluationStage.Order.Forward) ? hooks : hooks.Reverse();
+        }
+
+        public IEnumerable<SeriesData> Execute(IdentifySeriesContext context, IEnumerable<SeriesData> _)
+        {
+            return _hooks.Select(hook =>
+            {
+                try
+                {
+                    return hook.BeforeIdentify(context, SeriesData.Empty);
+                }
+                catch (Exception e)
+                {
+                    LogFailure(context, hook, Stage.BeforeIdentify, e);
+                    return SeriesData.Empty;
+                }
+            }).ToList();
+        }
+    }
+
+    internal sealed class AfterIdentify : IdentifyStage, IStageExecutor<IdentifySeriesContext, IdentifySeriesResult>
+    {
+        private readonly IEnumerable<Hook> _hooks;
+
+        public AfterIdentify(Logger logger, IEnumerable<Hook> hooks, EvaluationStage.Order order) : base(logger, order)
+        {
+            _hooks = (order == EvaluationStage.Order.Forward) ? hooks : hooks.Reverse();
+        }
+
+        public IEnumerable<SeriesData> Execute(IdentifySeriesContext context, IdentifySeriesResult result,
+            IEnumerable<SeriesData> seriesData)
+        {
+            return _hooks.Zip((_order == EvaluationStage.Order.Reverse ? seriesData.Reverse() : seriesData), (hook, data) =>
+            {
+                try
+                {
+                    return hook.AfterIdentify(context, data, result);
+                }
+                catch (Exception e)
+                {
+                    LogFailure(context, hook, Stage.AfterIdentify, e);
+                    return SeriesData.Empty;
+                }
+            }).ToList();
+        }
+    }
+}