fix(historian-gateway): wire dormant GatewayTagProvisioner + provisioning observability/docs

PR #423 shipped GatewayTagProvisioner + unit tests but never registered it in DI nor passed it into the AddressSpaceApplier, so deploying historized tags used the no-op NullHistorianProvisioning and never called the gateway's EnsureTags (confirmed live on wonder-app-vd03: zero EnsureTags calls on a historized deploy). Addresses HISTORIAN-GATEWAY-INTEGRATION-ISSUES.md. Issue 1 (wire provisioner): - Runtime: AddHistorianProvisioning extension (gated on ServerHistorian:Enabled, mirrors AddServerHistorian) + NullHistorianProvisioning TryAdd default in AddOtOpcUaRuntime; WithOtOpcUaRuntimeActors resolves IHistorianProvisioning and passes it into the applier. - Gateway driver: GatewayHistorian.CreateProvisioner factory (mirrors CreateDataSource). - Host: Program.cs calls AddHistorianProvisioning after AddServerHistorian. - Tests: AddHistorianProvisioningTests (config-gated registration + the register->resolve->applier->EnsureTags chain). Issue 2 (observability): AddressSpaceApplier logs the provisioning tally on every successful dispatch (was gated behind Failed/Skipped > 0), including dispatched=N so a dispatched=N/requested=0 line flags the dormant no-op. +2 tests. Issue 3 (30s HistoryRead on unprovisioned tags): root coupling fixed by Issue 1; documented the CallTimeout knob + coupling. Default left at 30s pending the multi-data-point investigation the issue requests (lowering risks truncating legitimate large reads). Issue 4 (docs): docs/Historian.md gains a "Tag auto-provisioning (EnsureTags)" section and CLAUDE.md a wiring/gating note (both stress ServerHistorian:Enabled). Sibling scadaproj/CLAUDE.md carries no false claim -> unchanged. Pre-existing Serilog observation: anchor CWD to AppContext.BaseDirectory before AddZbSerilog so the relative file sink stops landing in C:\Windows\System32 under the Windows-service CWD. Builds 0-error; Runtime.Tests 355, OpcUaServer.Tests 329, Gateway.Tests 99 (+4 live-skipped) all green.
2026-06-27 23:24:29 -04:00
parent 245316d80d
commit 257214f775
8 changed files with 416 additions and 7 deletions
@@ -1,3 +1,4 @@
+using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Shouldly;
 using Xunit;
@@ -143,6 +144,77 @@ public sealed class AddressSpaceApplierProvisioningTests
        prov.Seen[0].TagName.ShouldBe("Pump1.Good");
    }

+    /// <summary>Capturing <see cref="ILogger{T}"/> that records every log line and signals a
+    /// <see cref="TaskCompletionSource{TResult}"/> the first time a "historian provisioning completed" tally is
+    /// emitted, so the fire-and-forget continuation's log can be awaited deterministically.</summary>
+    private sealed class CapturingLogger : ILogger<AddressSpaceApplier>
+    {
+        private readonly TaskCompletionSource<string> _provisioningLogged =
+            new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        /// <summary>Completes with the rendered message of the first provisioning-completed tally logged.</summary>
+        public Task<string> ProvisioningLogged => _provisioningLogged.Task;
+
+        public IDisposable BeginScope<TState>(TState state) where TState : notnull => NullScope.Instance;
+
+        public bool IsEnabled(LogLevel logLevel) => true;
+
+        public void Log<TState>(
+            LogLevel logLevel, EventId eventId, TState state, Exception? exception,
+            Func<TState, Exception?, string> formatter)
+        {
+            var message = formatter(state, exception);
+            if (logLevel == LogLevel.Information &&
+                message.Contains("historian provisioning completed", StringComparison.Ordinal))
+            {
+                _provisioningLogged.TrySetResult(message);
+            }
+        }
+
+        private sealed class NullScope : IDisposable
+        {
+            public static readonly NullScope Instance = new();
+            public void Dispose() { }
+        }
+    }
+
+    /// <summary>Issue 2 (observability): a fully-successful provisioning (Ensured>0, Failed=0, Skipped=0) — the
+    /// case that previously logged NOTHING — now emits an Information tally, so a successful provisioning is
+    /// observable rather than silent.</summary>
+    [Fact]
+    public async Task Apply_logs_an_information_tally_on_a_fully_successful_provisioning()
+    {
+        var logger = new CapturingLogger();
+        var applier = new AddressSpaceApplier(
+            NullOpcUaAddressSpaceSink.Instance, logger, new CapturingProvisioner());
+
+        applier.Apply(PlanWithAddedTags(
+            HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
+
+        var message = await logger.ProvisioningLogged.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
+        message.ShouldContain("dispatched=1");
+        message.ShouldContain("ensured=1");
+        message.ShouldContain("failed=0");
+    }
+
+    /// <summary>Issue 2 (observability): the no-op <see cref="NullHistorianProvisioning"/> path is now
+    /// DETECTABLE — it reports Requested=0 regardless of input, so a tally showing dispatched=1 but requested=0
+    /// unmistakably flags "provisioning is not wired", the invisibility that let the dormant-provisioner bug
+    /// ship unnoticed.</summary>
+    [Fact]
+    public async Task Apply_logs_a_detectable_tally_for_the_noop_provisioning_path()
+    {
+        var logger = new CapturingLogger();
+        var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, logger);
+
+        applier.Apply(PlanWithAddedTags(
+            HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
+
+        var message = await logger.ProvisioningLogged.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
+        message.ShouldContain("dispatched=1");  // we DID hand one request to EnsureTagsAsync
+        message.ShouldContain("requested=0");   // ...but the no-op acknowledges nothing ⇒ dormant
+    }
+
    /// <summary>Capturing <see cref="IHistorizedTagSubscriptionSink"/> double. Records the add/remove
    /// ref deltas the applier feeds it. A <see cref="Throw"/> flag simulates a faulting feed.</summary>
    private sealed class CapturingSubscriptionSink : IHistorizedTagSubscriptionSink
@@ -0,0 +1,199 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging.Abstractions;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.OpcUaServer;
+using ZB.MOM.WW.OtOpcUa.Runtime;
+using ZB.MOM.WW.OtOpcUa.Runtime.Historian;
+
+namespace ZB.MOM.WW.OtOpcUa.Runtime.Tests.Historian;
+
+/// <summary>
+///     Verifies the config-gated <c>AddHistorianProvisioning</c> registration AND that a registered
+///     provisioner is actually reached by the address-space applier on a historized-tag deploy. This is the
+///     wiring the HistorianGateway-integration review found missing: PR #423 shipped
+///     <c>GatewayTagProvisioner</c> + unit tests but never registered it in DI nor passed it into the applier,
+///     so <c>EnsureTags</c> was dormant (every deploy used the no-op <see cref="NullHistorianProvisioning"/>).
+///     <para>
+///         When the <c>ServerHistorian</c> section is absent or disabled the <see cref="NullHistorianProvisioning"/>
+///         default seeded by <c>AddOtOpcUaRuntime</c> survives (the factory is never invoked); when it is enabled
+///         the factory's returned <see cref="IHistorianProvisioning"/> wins (last-registration-wins over the
+///         <c>TryAddSingleton</c> Null default) and — constructed into the applier the way
+///         <c>WithOtOpcUaRuntimeActors</c> does — its <see cref="IHistorianProvisioning.EnsureTagsAsync"/> fires
+///         for an added historized tag.
+///     </para>
+/// </summary>
+public sealed class AddHistorianProvisioningTests
+{
+    /// <summary>Capturing <see cref="IHistorianProvisioning"/> double — records the requests it was handed and
+    /// signals a <see cref="TaskCompletionSource"/> when invoked so the fire-and-forget applier dispatch can be
+    /// awaited deterministically.</summary>
+    private sealed class CapturingProvisioner : IHistorianProvisioning
+    {
+        private readonly TaskCompletionSource _called = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        /// <summary>The requests the applier handed to <see cref="EnsureTagsAsync"/>.</summary>
+        public List<HistorianTagProvisionRequest> Seen { get; } = new();
+
+        /// <summary>Completes once <see cref="EnsureTagsAsync"/> has been invoked.</summary>
+        public Task Called => _called.Task;
+
+        /// <inheritdoc />
+        public Task<HistorianProvisionResult> EnsureTagsAsync(
+            IReadOnlyList<HistorianTagProvisionRequest> requests, CancellationToken ct)
+        {
+            Seen.AddRange(requests);
+            _called.TrySetResult();
+            return Task.FromResult(new HistorianProvisionResult(requests.Count, requests.Count, 0, 0));
+        }
+    }
+
+    private static IConfiguration ConfigFrom(Dictionary<string, string?> values)
+        => new ConfigurationBuilder().AddInMemoryCollection(values).Build();
+
+    private static IConfiguration EnabledConfig() => ConfigFrom(new Dictionary<string, string?>
+    {
+        ["ServerHistorian:Enabled"] = "true",
+        ["ServerHistorian:Endpoint"] = "https://historian.example.com:5222",
+        ["ServerHistorian:ApiKey"] = "histgw_x_y",
+    });
+
+    [Fact]
+    public void Section_absent_keeps_null_provisioning_and_factory_not_invoked()
+    {
+        var factoryInvoked = false;
+        var services = new ServiceCollection();
+        services.AddOtOpcUaRuntime();
+
+        services.AddHistorianProvisioning(ConfigFrom(new Dictionary<string, string?>()), (_, _) =>
+        {
+            factoryInvoked = true;
+            return new CapturingProvisioner();
+        });
+
+        using var provider = services.BuildServiceProvider();
+        provider.GetRequiredService<IHistorianProvisioning>().ShouldBeSameAs(NullHistorianProvisioning.Instance);
+        factoryInvoked.ShouldBeFalse();
+    }
+
+    [Fact]
+    public void Section_disabled_keeps_null_provisioning_and_factory_not_invoked()
+    {
+        var factoryInvoked = false;
+        var services = new ServiceCollection();
+        services.AddOtOpcUaRuntime();
+        var config = ConfigFrom(new Dictionary<string, string?> { ["ServerHistorian:Enabled"] = "false" });
+
+        services.AddHistorianProvisioning(config, (_, _) =>
+        {
+            factoryInvoked = true;
+            return new CapturingProvisioner();
+        });
+
+        using var provider = services.BuildServiceProvider();
+        provider.GetRequiredService<IHistorianProvisioning>().ShouldBeSameAs(NullHistorianProvisioning.Instance);
+        factoryInvoked.ShouldBeFalse();
+    }
+
+    [Fact]
+    public void Section_enabled_registers_factory_provisioner_over_the_null_default()
+    {
+        var prov = new CapturingProvisioner();
+        var services = new ServiceCollection();
+        services.AddOtOpcUaRuntime();
+
+        services.AddHistorianProvisioning(EnabledConfig(), (_, _) => prov);
+
+        using var provider = services.BuildServiceProvider();
+        var resolved = provider.GetRequiredService<IHistorianProvisioning>();
+        resolved.ShouldBeSameAs(prov);
+        resolved.ShouldNotBeSameAs(NullHistorianProvisioning.Instance);
+    }
+
+    [Fact]
+    public void Section_enabled_passes_bound_options_to_factory()
+    {
+        ServerHistorianOptions? seen = null;
+        var services = new ServiceCollection();
+        services.AddOtOpcUaRuntime();
+        var config = ConfigFrom(new Dictionary<string, string?>
+        {
+            ["ServerHistorian:Enabled"] = "true",
+            ["ServerHistorian:Endpoint"] = "https://historian.example.com:5222",
+            ["ServerHistorian:ApiKey"] = "histgw_x_y",
+            ["ServerHistorian:UseTls"] = "true",
+            ["ServerHistorian:CaCertificatePath"] = "/etc/ssl/gateway-ca.pem",
+        });
+
+        services.AddHistorianProvisioning(config, (opts, _) =>
+        {
+            seen = opts;
+            return new CapturingProvisioner();
+        });
+
+        using var provider = services.BuildServiceProvider();
+        _ = provider.GetRequiredService<IHistorianProvisioning>();
+
+        seen.ShouldNotBeNull();
+        seen.Endpoint.ShouldBe("https://historian.example.com:5222");
+        seen.ApiKey.ShouldBe("histgw_x_y");
+        seen.UseTls.ShouldBeTrue();
+        seen.CaCertificatePath.ShouldBe("/etc/ssl/gateway-ca.pem");
+    }
+
+    /// <summary>
+    ///     The end-to-end wiring proof the dormant-provisioner bug needed: register the provisioner via
+    ///     <c>AddHistorianProvisioning</c>, resolve it, construct the <see cref="AddressSpaceApplier"/> EXACTLY
+    ///     as <c>WithOtOpcUaRuntimeActors</c> does (<c>provisioning: resolver.GetService&lt;IHistorianProvisioning&gt;()</c>),
+    ///     then apply a plan that adds a historized tag and assert the gateway-backed
+    ///     <see cref="IHistorianProvisioning.EnsureTagsAsync"/> actually fires (with the resolved historian name).
+    /// </summary>
+    [Fact]
+    public async Task Registered_provisioner_is_invoked_by_the_applier_on_a_historized_deploy()
+    {
+        var prov = new CapturingProvisioner();
+        var services = new ServiceCollection();
+        services.AddOtOpcUaRuntime();
+        services.AddHistorianProvisioning(EnabledConfig(), (_, _) => prov);
+        using var provider = services.BuildServiceProvider();
+
+        // Mirror the production construction in WithOtOpcUaRuntimeActors: resolve the provisioner and pass it in.
+        var resolved = provider.GetService<IHistorianProvisioning>();
+        var applier = new AddressSpaceApplier(
+            NullOpcUaAddressSpaceSink.Instance, NullLogger<AddressSpaceApplier>.Instance, provisioning: resolved);
+
+        applier.Apply(PlanWithAddedTags(
+            HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32"),
+            NonHistorizedTag(displayName: "Run", dataType: "Boolean")));
+
+        await prov.Called.WaitAsync(TimeSpan.FromSeconds(5));
+        prov.Seen.Count.ShouldBe(1);
+        prov.Seen[0].TagName.ShouldBe("Pump1.Temp");
+        prov.Seen[0].DataType.ShouldBe(DriverDataType.Float32);
+    }
+
+    private static EquipmentTagPlan HistorizedTag(string displayName, string? historianName, string dataType, string fullName = "ref")
+        => new("tag-" + displayName, "eq-1", "drv", FolderPath: "", Name: displayName, DataType: dataType, FullName: fullName,
+            Writable: false, Alarm: null, IsHistorized: true, HistorianTagname: historianName);
+
+    private static EquipmentTagPlan NonHistorizedTag(string displayName, string dataType)
+        => new("tag-" + displayName, "eq-1", "drv", FolderPath: "", Name: displayName, DataType: dataType, FullName: "ref",
+            Writable: false, Alarm: null, IsHistorized: false, HistorianTagname: null);
+
+    private static AddressSpacePlan PlanWithAddedTags(params EquipmentTagPlan[] tags) => new(
+        AddedEquipment: Array.Empty<EquipmentNode>(),
+        RemovedEquipment: Array.Empty<EquipmentNode>(),
+        ChangedEquipment: Array.Empty<AddressSpacePlan.EquipmentDelta>(),
+        AddedDrivers: Array.Empty<DriverInstancePlan>(),
+        RemovedDrivers: Array.Empty<DriverInstancePlan>(),
+        ChangedDrivers: Array.Empty<AddressSpacePlan.DriverDelta>(),
+        AddedAlarms: Array.Empty<ScriptedAlarmPlan>(),
+        RemovedAlarms: Array.Empty<ScriptedAlarmPlan>(),
+        ChangedAlarms: Array.Empty<AddressSpacePlan.AlarmDelta>())
+    {
+        AddedEquipmentTags = tags,
+    };
+}