feat(historian-gateway): EnsureTags provisioning hook in AddressSpaceApplier (non-blocking)

Claude-Session: https://claude.ai/code/session_012SDSQ3AcaXqPcBtDESBRii
2026-06-26 18:03:40 -04:00
parent 035bde0562
commit 8b4028de84
3 changed files with 262 additions and 1 deletions
@@ -1,5 +1,6 @@
 using Microsoft.Extensions.Logging;
 using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;

@@ -27,16 +28,29 @@ public sealed class AddressSpaceApplier
 {
    private readonly IOpcUaAddressSpaceSink _sink;
    private readonly ILogger<AddressSpaceApplier> _logger;
+    private readonly IHistorianProvisioning _provisioning;

    /// <summary>Initializes a new instance of the AddressSpaceApplier class.</summary>
    /// <param name="sink">The OPC UA address space sink to apply changes to.</param>
    /// <param name="logger">The logger instance.</param>
-    public AddressSpaceApplier(IOpcUaAddressSpaceSink sink, ILogger<AddressSpaceApplier> logger)
+    /// <param name="provisioning">
+    ///     Optional historian tag provisioner — when an address space is (re)built, historized added
+    ///     tags are auto-ensured in the historian via <see cref="IHistorianProvisioning.EnsureTagsAsync"/>.
+    ///     Defaults (a <c>null</c> argument) to the no-op <see cref="NullHistorianProvisioning"/>, so every
+    ///     existing two-argument call site compiles and behaves unchanged. The provisioning round-trip is
+    ///     dispatched fire-and-forget off <see cref="Apply"/> (which runs on the OPC UA publish actor's
+    ///     pinned thread), so it can never block or break a deploy.
+    /// </param>
+    public AddressSpaceApplier(
+        IOpcUaAddressSpaceSink sink,
+        ILogger<AddressSpaceApplier> logger,
+        IHistorianProvisioning? provisioning = null)
    {
        ArgumentNullException.ThrowIfNull(sink);
        ArgumentNullException.ThrowIfNull(logger);
        _sink = sink;
        _logger = logger;
+        _provisioning = provisioning ?? NullHistorianProvisioning.Instance;
    }

    /// <summary>
@@ -177,9 +191,88 @@ public sealed class AddressSpaceApplier
            "AddressSpaceApplier: applied plan (added={Added}, removed={Removed}, changed={Changed}, surgicalTags={Surgical}, renamedFolders={Renamed}, rebuild={Rebuild})",
            addedCount, removedCount, changedCount, rebuilt ? 0 : surgicalTagDeltas.Count, rebuilt ? 0 : renamedFolders.Count, rebuilt);

+        // After the address-space work has completed, auto-provision the historian for the added
+        // historized tags. This is fully detached (fire-and-forget) and wrapped so it can NEVER block
+        // or break the deploy — Apply has already produced its outcome and returns it regardless.
+        ProvisionHistorizedTags(plan);
+
        return new AddressSpaceApplyOutcome(removedCount, addedCount, changedCount, rebuilt);
    }

+    /// <summary>
+    ///     Auto-provision the historian for the added historized equipment tags. Runs on the OPC UA
+    ///     publish actor's pinned thread, so the synchronous portion is kept to building the request
+    ///     list only and the gateway round-trip is dispatched fire-and-forget. The whole hook is wrapped
+    ///     in try/catch — a synchronously-throwing provisioner (or any request-building fault) is
+    ///     swallowed so it cannot break a deploy.
+    /// </summary>
+    /// <param name="plan">The plan whose added historized tags to ensure in the historian.</param>
+    private void ProvisionHistorizedTags(AddressSpacePlan plan)
+    {
+        try
+        {
+            List<HistorianTagProvisionRequest>? requests = null;
+            foreach (var tag in plan.AddedEquipmentTags)
+            {
+                // Only historized value variables are provisioned. Native-alarm tags materialise as
+                // Part 9 condition nodes (never historized value variables) — the materialiser resolves
+                // a historian tagname only for the non-alarm branch, so mirror that and skip them.
+                if (!tag.IsHistorized || tag.Alarm is not null) continue;
+
+                // Parse the driver-agnostic data type from the tag's DataType string. An unparseable
+                // type is skipped (logged at Debug) rather than faulting the hook.
+                if (!Enum.TryParse<DriverDataType>(tag.DataType, ignoreCase: true, out var dataType))
+                {
+                    _logger.LogDebug(
+                        "AddressSpaceApplier: skipping historian provisioning for an added historized tag whose data type '{DataType}' is not a DriverDataType",
+                        tag.DataType);
+                    continue;
+                }
+
+                // Resolve the historian name EXACTLY as MaterialiseEquipmentTags does: a null/blank
+                // override falls back to the driver-side FullName.
+                var historianName = string.IsNullOrWhiteSpace(tag.HistorianTagname) ? tag.FullName : tag.HistorianTagname;
+                (requests ??= new List<HistorianTagProvisionRequest>()).Add(
+                    new HistorianTagProvisionRequest(historianName, dataType, EngineeringUnit: null, Description: tag.Name));
+            }
+
+            if (requests is null) return;
+
+            // Fire-and-forget OFF the apply path. Never await/.Wait()/.Result here — Apply must return
+            // its outcome without blocking on the gateway. The continuation observes the task so a
+            // faulted provisioning never becomes an unobserved exception, and logs the tally.
+            var provisionCount = requests.Count;
+            var dispatch = _provisioning.EnsureTagsAsync(requests, CancellationToken.None);
+            _ = dispatch.ContinueWith(
+                t =>
+                {
+                    if (t.IsFaulted)
+                    {
+                        _logger.LogWarning(t.Exception?.GetBaseException(),
+                            "AddressSpaceApplier: historian provisioning of {Count} tag(s) faulted; deploy unaffected", provisionCount);
+                        return;
+                    }
+
+                    var result = t.Result;
+                    if (result.Failed > 0 || result.Skipped > 0)
+                    {
+                        _logger.LogInformation(
+                            "AddressSpaceApplier: historian provisioning completed (requested={Requested}, ensured={Ensured}, skipped={Skipped}, failed={Failed})",
+                            result.Requested, result.Ensured, result.Skipped, result.Failed);
+                    }
+                },
+                CancellationToken.None,
+                TaskContinuationOptions.None,
+                TaskScheduler.Default);
+        }
+        catch (Exception ex)
+        {
+            // A synchronous fault (e.g. the provisioner throws before returning a task) must not break
+            // the deploy. Apply has already produced its outcome.
+            _logger.LogWarning(ex, "AddressSpaceApplier: historian provisioning hook faulted synchronously; deploy unaffected");
+        }
+    }
+
    private void SafeRebuild()
    {
        try
@@ -16,6 +16,7 @@
    </ItemGroup>

    <ItemGroup>
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Commons\ZB.MOM.WW.OtOpcUa.Commons.csproj"/>
        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Configuration\ZB.MOM.WW.OtOpcUa.Configuration.csproj"/>
    </ItemGroup>