feat: Allow register plugins dynamically (#266)

**Requirements**

Add possibility to Register plugins dynamically for separation concerns
from LD flagging and Observability.
It is not customer facing API and doesn't require documentation change.

```
    var client = await LdClient.InitAsync(ldConfig, context, TimeSpan.FromSeconds(5));
    client.RegisterPlugin(observabilityPlugin);

```             


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes hook execution and evaluation/identify wrapping for all
clients (unified Executor path) and introduces concurrent hook list
updates; failures are logged but mis-registered plugins could affect
observability behavior.
> 
> **Overview**
> Adds **`LdClient.RegisterPlugin`** so plugins (e.g. observability) can
be attached after `Init`/`InitAsync`, without listing them in
`ConfigurationBuilder.Plugins`.
> 
> The hook pipeline is refactored for **runtime hook registration**:
`IHookExecutor` gains **`AddHooks`**, and **`Executor`** keeps an
immutable **`Stages`** snapshot (hooks + before/after executors)
published under a lock; each evaluation/identify call snapshots
`_stages` so before/after stages stay consistent if hooks are added
mid-flight. With zero hooks, evaluation/identify skip hook work.
> 
> **`NoopExecutor`** is removed—the client always uses **`Executor`**
(including when no hooks are configured at startup).
**`EnvironmentMetadata`** is always created on the client (not only when
config plugins exist), and is reused for dynamic registration.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
6e1d766. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: abelonogov-ld

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

@@ -11,33 +11,65 @@ namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Executor
 {
     internal sealed class Executor : IHookExecutor
     {
-        private readonly List<Hook> _hooks;
-        private readonly Logger _logger;
+        // Immutable bundle of per-generation state. Once a Stages instance is published via the
+        // volatile _stages field, none of its fields (including the contents of Hooks) are
+        // mutated. AddHooks always builds a fresh Stages over a fresh List<Hook>.
+        private sealed class Stages
+        {
+            public readonly List<Hook> Hooks;
+            public readonly IStageExecutor<EvaluationSeriesContext> BeforeEvaluation;
+            public readonly IStageExecutor<EvaluationSeriesContext, EvaluationDetail<LdValue>> AfterEvaluation;
+            public readonly IStageExecutor<IdentifySeriesContext> BeforeIdentify;
+            public readonly IStageExecutor<IdentifySeriesContext, IdentifySeriesResult> AfterIdentify;
 
-        private readonly IStageExecutor<EvaluationSeriesContext> _beforeEvaluation;
-        private readonly IStageExecutor<EvaluationSeriesContext, EvaluationDetail<LdValue>> _afterEvaluation;
+            public Stages(Logger logger, List<Hook> hooks)
+            {
+                Hooks = hooks;
+                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);
+            }
+        }
 
-        private readonly IStageExecutor<IdentifySeriesContext> _beforeIdentify;
-        private readonly IStageExecutor<IdentifySeriesContext, IdentifySeriesResult> _afterIdentify;
+        private readonly Logger _logger;
+        private readonly object _lock = new object();
+        private volatile Stages _stages;
 
         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);
+            _stages = new Stages(logger, hooks.ToList());
+        }
+
+        public void AddHooks(IEnumerable<Hook> hooks)
+        {
+            if (hooks == null) return;
+            lock (_lock)
+            {
+                var added = hooks.ToList();
+                if (added.Count == 0) return;
+                var current = _stages.Hooks;
+                var newHooks = new List<Hook>(current.Count + added.Count);
+                newHooks.AddRange(current);
+                newHooks.AddRange(added);
+                _stages = new Stages(_logger, newHooks);
+            }
         }
 
         public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
             LdValue.Converter<T> converter, Func<EvaluationDetail<T>> evaluate)
         {
-            var seriesData = _beforeEvaluation.Execute(context, default);
+            // Snapshot the stages once so Before/After see a single, consistent generation
+            // even if AddHooks publishes a new Stages mid-call.
+            var stages = _stages;
+            if (stages.Hooks.Count == 0) return evaluate();
+
+            var seriesData = stages.BeforeEvaluation.Execute(context, default);
 
             var detail = evaluate();
 
-            _afterEvaluation.Execute(context,
+            stages.AfterEvaluation.Execute(context,
                 new EvaluationDetail<LdValue>(converter.FromType(detail.Value), detail.VariationIndex, detail.Reason),
                 seriesData);
 
@@ -46,22 +78,25 @@ public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
 
         public async Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Func<Task<bool>> identify)
         {
+            var stages = _stages;
+            if (stages.Hooks.Count == 0) return await identify();
+
             var identifyContext = new IdentifySeriesContext(context, maxWaitTime);
-            var seriesData = _beforeIdentify.Execute(identifyContext, default);
+            var seriesData = stages.BeforeIdentify.Execute(identifyContext, default);
 
             try
             {
                 var result = await identify();
 
-                _afterIdentify.Execute(identifyContext,
+                stages.AfterIdentify.Execute(identifyContext,
                     new IdentifySeriesResult(IdentifySeriesResult.IdentifySeriesStatus.Completed),
                     seriesData);
 
                 return result;
             }
             catch (Exception)
             {
-                _afterIdentify.Execute(identifyContext,
+                stages.AfterIdentify.Execute(identifyContext,
                     new IdentifySeriesResult(IdentifySeriesResult.IdentifySeriesStatus.Error),
                     seriesData);
 
@@ -71,7 +106,8 @@ public async Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Fu
 
         public void Dispose()
         {
-            foreach (var hook in _hooks)
+            var stages = _stages;
+            foreach (var hook in stages.Hooks)
             {
                 try
                 {

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

@@ -1,14 +1,12 @@
 using System;
+using System.Collections.Generic;
 using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Hooks;
 
 namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces
 {
     /// <summary>
     /// An IHookExecutor is responsible for executing the logic contained in a series of hook stages.
-    ///
-    /// The purpose of this interface is to allow the SDK to swap out the executor based on having any hooks
-    /// configured or not. If there are no hooks, the interface methods can be no-ops.
     /// </summary>
     internal interface IHookExecutor : IDisposable
     {
@@ -34,5 +32,13 @@ EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
         /// <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);
+
+        /// <summary>
+        /// Adds additional hooks to the executor so that subsequent <see cref="EvaluationSeries{T}"/> and
+        /// <see cref="IdentifySeries"/> calls invoke them. The implementation is responsible for
+        /// synchronizing concurrent calls.
+        /// </summary>
+        /// <param name="hooks">the hooks to add; may be empty or null (no-op in either case)</param>
+        void AddHooks(IEnumerable<Hook> hooks);
     }
 }

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

@@ -15,6 +15,7 @@
 using LaunchDarkly.Sdk.Client.Internal.Events;
 using LaunchDarkly.Sdk.Client.Internal.Interfaces;
 using LaunchDarkly.Sdk.Client.PlatformSpecific;
+using LaunchDarkly.Sdk.Client.Plugins;
 using LaunchDarkly.Sdk.Client.Subsystems;
 using LaunchDarkly.Sdk.Integrations.Plugins;
 using LaunchDarkly.Sdk.Internal;
@@ -72,6 +73,7 @@ public sealed class LdClient : ILdClient
         readonly TaskExecutor _taskExecutor;
         readonly AnonymousKeyContextDecorator _anonymousKeyContextDecorator;
         private readonly AutoEnvContextDecorator _autoEnvContextDecorator;
+        private readonly EnvironmentMetadata _environmentMetadata;
         private readonly IHookExecutor _hookExecutor;
 
         private readonly Logger _log;
@@ -224,16 +226,14 @@ public sealed class LdClient : ILdClient
 
             // Build the plugin config and environment metadata
             var pluginConfig = (_config.Plugins ?? Components.Plugins()).Build();
-            var environmentMetadata = pluginConfig.Plugins.Any() ? CreateEnvironmentMetadata() : null;
+            _environmentMetadata = CreateEnvironmentMetadata();
             var hooks = pluginConfig.Plugins.Any()
-                ? this.GetPluginHooks(pluginConfig.Plugins, environmentMetadata, _log)
+                ? this.GetPluginHooks(pluginConfig.Plugins, _environmentMetadata, _log)
                 : new List<Hook>();
 
-            _hookExecutor = hooks.Any()
-                ? (IHookExecutor)new Executor(_log.SubLogger(LogNames.HooksSubLog), hooks)
-                : new NoopExecutor();
+            _hookExecutor = new Executor(_log.SubLogger(LogNames.HooksSubLog), hooks);
 
-            this.RegisterPlugins(pluginConfig.Plugins, environmentMetadata, _log);
+            this.RegisterPlugins(pluginConfig.Plugins, _environmentMetadata, _log);
 
             // Start the background mode manager
             _backgroundModeManager = _config.BackgroundModeManager ?? new DefaultBackgroundModeManager();
@@ -902,6 +902,80 @@ public bool FlushAndWait(TimeSpan timeout) =>
         public Task<bool> FlushAndWaitAsync(TimeSpan timeout) =>
             _eventProcessor.FlushAndWaitAsync(timeout);
 
+        /// <summary>
+        /// Registers a single <see cref="Plugin"/> with this client after construction.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Retrieves hooks via <c>GetHooks</c>, calls <c>Register</c>, then merges the hooks into
+        /// the live pipeline. This ordering differs from construction-time registration for plugins
+        /// configured via <see cref="ConfigurationBuilder.Plugins"/>, where hooks are added to the
+        /// executor before <c>Register</c> is called: here, hooks are not active during
+        /// <c>Register</c>, so flag evaluations or identify calls made inside <c>Register</c> will
+        /// not invoke this plugin's hooks. After this method returns successfully, subsequent
+        /// evaluations and identify calls will invoke them.
+        /// </para>
+        /// <para>
+        /// Exceptions thrown by the plugin's <c>Register</c> or <c>GetHooks</c> are caught and
+        /// logged; they do not propagate to the caller. If either throws, the plugin is not
+        /// registered and its hooks are not added to the live pipeline. Hooks returned by
+        /// <c>GetHooks</c> are disposed if <c>Register</c> fails.
+        /// </para>
+        /// </remarks>
+        /// <param name="plugin">the plugin to register; must not be null</param>
+        /// <exception cref="ArgumentNullException">if <paramref name="plugin"/> is null</exception>
+        public void RegisterPlugin(Plugin plugin)
+        {
+            if (plugin == null) throw new ArgumentNullException(nameof(plugin));
+
+            IList<Hook> pluginHooks = null;
+            try
+            {
+                pluginHooks = plugin.GetHooks(_environmentMetadata);
+            }
+            catch (Exception ex)
+            {
+                _log.Error("Error getting hooks from plugin {0}: {1}",
+                    plugin.Metadata.Name ?? "unknown", ex);
+                return;
+            }
+
+            try
+            {
+                plugin.Register(this, _environmentMetadata);
+            }
+            catch (Exception ex)
+            {
+                _log.Error("Error registering plugin {0}: {1}",
+                    plugin.Metadata.Name ?? "unknown", ex);
+                DisposePluginHooks(pluginHooks);
+                return;
+            }
+
+            if (pluginHooks != null && pluginHooks.Count > 0)
+            {
+                _hookExecutor.AddHooks(pluginHooks);
+            }
+        }
+
+        private void DisposePluginHooks(IList<Hook> pluginHooks)
+        {
+            if (pluginHooks == null) return;
+
+            foreach (var hook in pluginHooks)
+            {
+                try
+                {
+                    hook?.Dispose();
+                }
+                catch (Exception e)
+                {
+                    _log.Error("During disposal of hook \"{0}\" reported error: {1}",
+                        hook?.Metadata.Name, e.Message);
+                }
+            }
+        }
+
         /// <inheritdoc/>
         public bool Identify(Context context, TimeSpan maxWaitTime)
         {