feat(bootstrap): OnConfigReady callback receiving the whole config manager

Runs after every configuration load, once all typed OnConfigLoaded hooks
have been applied and before the logger and services consume the sections.

Author: tgiachi

docs/articles/concepts/bootstrap-lifecycle.md

@@ -46,7 +46,9 @@ await bootstrap.StartAsync();
 ```
 
 The effective order is: load configuration, apply config hooks, configure the logger, start
-services. Hooks are re-applied on every configuration load, so overrides are never lost. See
+services. Hooks are re-applied on every configuration load, so overrides are never lost. To
+receive the whole configuration manager once every typed hook has run, use
+`bootstrap.OnConfigReady(cfg => ...)`. See
 [Inspecting and overriding loaded configuration](../guides/configuration.md#inspecting-and-overriding-loaded-configuration) for more examples.
 
 ## Migrating to 0.15: explicit core services

docs/articles/guides/configuration.md

@@ -79,3 +79,17 @@ bootstrap.OnConfigLoaded<StorageConfig>(s => Console.WriteLine($"storage root: {
 Hooks compose: register as many as you need, also on the same section - they run in
 registration order. Registering a hook for a type that is not a config section fails at
 startup with a clear error; registering one after the bootstrap has started throws.
+
+To receive the whole configuration in one callback - after every typed hook has been
+applied - use `OnConfigReady`. It hands you the config manager, so you can dump or inspect
+the final values:
+
+```csharp
+bootstrap.OnConfigReady(cfg =>
+{
+    Console.WriteLine(cfg.Compose());   // final configuration, overrides included
+});
+```
+
+`OnConfigReady` follows the same rules as the typed hooks: it runs after every configuration
+load, before the logger and the services, and must be registered before the bootstrap starts.

src/SquidStd.Core/Interfaces/Bootstrap/ISquidStdBootstrap.cs

@@ -1,5 +1,6 @@
 using DryIoc;
 using SquidStd.Core.Data.Bootstrap;
+using SquidStd.Core.Interfaces.Config;
 
 namespace SquidStd.Core.Interfaces.Bootstrap;
 
@@ -43,6 +44,16 @@ public interface ISquidStdBootstrap : IAsyncDisposable
     /// <returns>The same bootstrap for chaining.</returns>
     ISquidStdBootstrap OnConfigLoaded<TConfig>(Action<TConfig> configure) where TConfig : class;
 
+    /// <summary>
+    /// Registers a callback invoked with the whole configuration manager after every load, once
+    /// all <see cref="OnConfigLoaded{TConfig}" /> hooks have been applied and before the logger
+    /// and services consume the sections. Use it to inspect (or dump via
+    /// <see cref="IConfigManagerService.Compose" />) the final configuration.
+    /// </summary>
+    /// <param name="ready">Callback that receives the configuration manager.</param>
+    /// <returns>The same bootstrap for chaining.</returns>
+    ISquidStdBootstrap OnConfigReady(Action<IConfigManagerService> ready);
+
     /// <summary>
     /// Resolves a service from the owned dependency injection container.
     /// </summary>

src/SquidStd.Services.Core/Services/Bootstrap/SquidStdBootstrap.cs

@@ -24,6 +24,7 @@ namespace SquidStd.Services.Core.Services.Bootstrap;
 public sealed class SquidStdBootstrap : ISquidStdBootstrap
 {
     private readonly List<(Type ConfigType, Action<object> Apply)> _configHooks = [];
+    private readonly List<Action<IConfigManagerService>> _configReadyCallbacks = [];
     private readonly bool _ownsContainer;
     private readonly List<ISquidStdService> _startedServices = [];
     private readonly Lock _syncRoot = new();
@@ -112,6 +113,25 @@ public ISquidStdBootstrap OnConfigLoaded<TConfig>(Action<TConfig> configure) whe
         return this;
     }
 
+    /// <inheritdoc />
+    public ISquidStdBootstrap OnConfigReady(Action<IConfigManagerService> ready)
+    {
+        ArgumentNullException.ThrowIfNull(ready);
+        ThrowIfDisposed();
+
+        lock (_syncRoot)
+        {
+            if (_state != BootstrapStateType.Created)
+            {
+                throw new InvalidOperationException("Config callbacks cannot be registered after bootstrap start.");
+            }
+        }
+
+        _configReadyCallbacks.Add(ready);
+
+        return this;
+    }
+
     /// <inheritdoc />
     public async ValueTask DisposeAsync()
     {
@@ -413,7 +433,7 @@ private void ConfigureLogger()
 
     private void ApplyConfigHooks()
     {
-        if (_configHooks.Count == 0)
+        if (_configHooks.Count == 0 && _configReadyCallbacks.Count == 0)
         {
             return;
         }
@@ -436,6 +456,20 @@ private void ApplyConfigHooks()
             apply(Container.Resolve(configType));
             logger.Debug("Applied config hook to {Section:l}", configType.Name);
         }
+
+        if (_configReadyCallbacks.Count == 0)
+        {
+            return;
+        }
+
+        var configManager = Container.Resolve<IConfigManagerService>();
+
+        foreach (var ready in _configReadyCallbacks)
+        {
+            ready(configManager);
+        }
+
+        logger.Debug("Invoked {Count} config ready callback(s)", _configReadyCallbacks.Count);
     }
 
     private void LogRegistrations(ILogger logger, ServiceRegistrationData[] lifecycleRegistrations)

tests/SquidStd.Tests/AspNetCore/FakeSquidStdBootstrap.cs

@@ -1,6 +1,7 @@
 using DryIoc;
 using SquidStd.Core.Data.Bootstrap;
 using SquidStd.Core.Interfaces.Bootstrap;
+using SquidStd.Core.Interfaces.Config;
 
 namespace SquidStd.Tests.AspNetCore;
 
@@ -36,6 +37,13 @@ public ISquidStdBootstrap OnConfigLoaded<TConfig>(Action<TConfig> configure) whe
         return this;
     }
 
+    public ISquidStdBootstrap OnConfigReady(Action<IConfigManagerService> ready)
+    {
+        ArgumentNullException.ThrowIfNull(ready);
+
+        return this;
+    }
+
     public ValueTask DisposeAsync()
     {
         Container.Dispose();

tests/SquidStd.Tests/Bootstrap/SquidStdBootstrapConfigHooksTests.cs

@@ -178,6 +178,97 @@ public async Task OnConfigLoaded_DoesNotRewriteYamlFile()
         }
     }
 
+    [Fact]
+    public async Task OnConfigReady_ReceivesManagerWithHookAdjustedValues()
+    {
+        using var temp = new TempDirectory();
+        await using var bootstrap = NewBootstrap(temp.Path);
+        var observedLimit = 0;
+        var invocations = 0;
+        bootstrap.ConfigureServices(c =>
+        {
+            c.RegisterConfigSection("fakeSection", static () => new FakeSectionConfig(), 0);
+            return c;
+        });
+        bootstrap.OnConfigLoaded<FakeSectionConfig>(f => f.Limit = 42);
+        bootstrap.OnConfigReady(cfg =>
+        {
+            invocations++;
+            observedLimit = cfg.GetConfig<FakeSectionConfig>().Limit;
+        });
+
+        await bootstrap.StartAsync();
+        try
+        {
+            Assert.True(invocations >= 1);
+            Assert.Equal(42, observedLimit);
+        }
+        finally
+        {
+            await bootstrap.StopAsync();
+        }
+    }
+
+    [Fact]
+    public async Task OnConfigReady_MultipleCallbacks_RunInOrder()
+    {
+        using var temp = new TempDirectory();
+        await using var bootstrap = NewBootstrap(temp.Path);
+        var order = new List<string>();
+        bootstrap.OnConfigReady(_ => order.Add("a"));
+        bootstrap.OnConfigReady(_ => order.Add("b"));
+
+        await bootstrap.StartAsync();
+        try
+        {
+            Assert.True(order.Count >= 2);
+            Assert.Equal("a", order[0]);
+            Assert.Equal("b", order[1]);
+        }
+        finally
+        {
+            await bootstrap.StopAsync();
+        }
+    }
+
+    [Fact]
+    public async Task OnConfigReady_WithoutTypedHooks_StillRuns()
+    {
+        using var temp = new TempDirectory();
+        await using var bootstrap = NewBootstrap(temp.Path);
+        var composed = string.Empty;
+        bootstrap.OnConfigReady(cfg => composed = cfg.Compose());
+
+        await bootstrap.StartAsync();
+        try
+        {
+            Assert.Contains("logger", composed, StringComparison.Ordinal);
+        }
+        finally
+        {
+            await bootstrap.StopAsync();
+        }
+    }
+
+    [Fact]
+    public async Task OnConfigReady_AfterStart_Throws()
+    {
+        using var temp = new TempDirectory();
+        await using var bootstrap = NewBootstrap(temp.Path);
+
+        await bootstrap.StartAsync();
+        try
+        {
+            Assert.Throws<InvalidOperationException>(
+                () => bootstrap.OnConfigReady(_ => { })
+            );
+        }
+        finally
+        {
+            await bootstrap.StopAsync();
+        }
+    }
+
     private static SquidStdBootstrap NewBootstrap(string root)
         => SquidStdBootstrap.Create(new SquidStdOptions { ConfigName = "app", RootDirectory = root });
 }