feat(historian): materialise historized vars with Historizing + HistoryRead bit + NodeId->tagname map

2026-06-14 19:09:32 -04:00
parent c35c1d3734
commit 6041dc202b
12 changed files with 308 additions and 23 deletions
@@ -30,6 +30,11 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
    private readonly ConcurrentDictionary<string, BaseDataVariableState> _variables = new(StringComparer.Ordinal);
    private readonly ConcurrentDictionary<string, FolderState> _folders = new(StringComparer.Ordinal);
    private readonly ConcurrentDictionary<string, AlarmConditionState> _alarmConditions = new(StringComparer.Ordinal);
+    /// <summary>Phase C: NodeId → resolved historian tagname for every variable materialised
+    /// Historizing. Populated by <see cref="EnsureVariable"/> when a historian tagname is supplied; the
+    /// (later) HistoryRead override resolves a HistoryRead request's NodeId against this map. Cleared on
+    /// <see cref="RebuildAddressSpace"/>.</summary>
+    private readonly ConcurrentDictionary<string, string> _historizedTagnames = new(StringComparer.Ordinal);
    /// <summary>Folders we have already promoted to event-notifiers + registered as root notifiers,
    /// so repeated <see cref="MaterialiseAlarmCondition"/> calls don't double-add (idempotent guard).
    /// Keyed by NodeId → the actual <see cref="FolderState"/> so <see cref="RebuildAddressSpace"/> can
@@ -113,6 +118,26 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
    public AlarmConditionState? TryGetAlarmCondition(string alarmNodeId) =>
        _alarmConditions.TryGetValue(alarmNodeId, out var condition) ? condition : null;

+    /// <summary>Phase C: look up the resolved historian tagname registered for a historized variable
+    /// node, or null when the node is not historized. The (later) HistoryRead override resolves an
+    /// inbound HistoryRead request's NodeId against this map. Exposed for tests + the override.</summary>
+    /// <param name="nodeId">The variable node identifier.</param>
+    /// <param name="tagname">The resolved historian tagname when historized; otherwise null.</param>
+    /// <returns>True when the node is registered as historized; otherwise false.</returns>
+    public bool TryGetHistorizedTagname(string nodeId, out string? tagname)
+    {
+        if (_historizedTagnames.TryGetValue(nodeId, out var t)) { tagname = t; return true; }
+        tagname = null;
+        return false;
+    }
+
+    /// <summary>Look up a materialised variable node by its NodeId string, or null if not present.
+    /// Exposed for tests so they can assert the SDK node's Historizing / AccessLevel attributes.</summary>
+    /// <param name="nodeId">The variable node identifier.</param>
+    /// <returns>The cached <see cref="BaseDataVariableState"/>, or null when none is registered.</returns>
+    internal BaseDataVariableState? TryGetVariable(string nodeId) =>
+        _variables.TryGetValue(nodeId, out var variable) ? variable : null;
+
    /// <summary>
    ///     Apply a value write from <see cref="IOpcUaAddressSpaceSink.WriteValue"/>. Creates the
    ///     variable node on first call; subsequent calls update Value + StatusCode +
@@ -817,7 +842,12 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
    /// ReadWrite equipment tag) and the inbound-write handler <see cref="OnEquipmentTagWrite"/> is attached
    /// to its <c>OnWriteValue</c> (Task 11) so a client write gates on the <c>WriteOperate</c> role + routes
    /// to the backing driver; when false it stays <c>CurrentRead</c> (read-only) with no write handler.</param>
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable)
+    /// <param name="historianTagname">Phase C: null ⇒ the node is NOT historized (Historizing=false, no
+    /// HistoryRead bit, not registered). Non-null ⇒ the node is created <c>Historizing</c> with the
+    /// <c>HistoryRead</c> access bit OR-ed into both <c>AccessLevel</c> and <c>UserAccessLevel</c>, and the
+    /// (already default-resolved) tagname is registered in the NodeId→tagname map the HistoryRead override
+    /// resolves against.</param>
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
    {
        ArgumentException.ThrowIfNullOrEmpty(variableNodeId);
        ArgumentException.ThrowIfNullOrEmpty(displayName);
@@ -830,6 +860,13 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
            if (_variables.ContainsKey(variableNodeId)) return;

            var parent = ResolveParentFolder(parentFolderNodeId);
+            // Phase C: a non-null historian tagname makes the node Historizing and grants the HistoryRead
+            // access bit (on top of the writable composite) so clients can browse + HistoryRead it.
+            var historized = historianTagname is not null;
+            // The SDK exposes the flags separately (no CurrentReadWrite composite): ReadWrite is
+            // CurrentRead | CurrentWrite. OR-ing two byte constants promotes to int, so cast back.
+            byte access = writable ? (byte)(AccessLevels.CurrentRead | AccessLevels.CurrentWrite) : AccessLevels.CurrentRead;
+            if (historized) access = (byte)(access | AccessLevels.HistoryRead);
            var variable = new BaseDataVariableState(parent)
            {
                NodeId = new NodeId(variableNodeId, NamespaceIndex),
@@ -839,11 +876,9 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
                ReferenceTypeId = ReferenceTypeIds.Organizes,
                DataType = ResolveBuiltInDataType(dataType),
                ValueRank = ValueRanks.Scalar,
-                // The SDK exposes the flags separately (no CurrentReadWrite composite): ReadWrite is
-                // CurrentRead | CurrentWrite. OR-ing two byte constants promotes to int, so cast back.
-                AccessLevel = writable ? (byte)(AccessLevels.CurrentRead | AccessLevels.CurrentWrite) : AccessLevels.CurrentRead,
-                UserAccessLevel = writable ? (byte)(AccessLevels.CurrentRead | AccessLevels.CurrentWrite) : AccessLevels.CurrentRead,
-                Historizing = false,
+                AccessLevel = access,
+                UserAccessLevel = access,
+                Historizing = historized,
                Value = null,
                StatusCode = StatusCodes.BadWaitingForInitialData,
                Timestamp = DateTime.MinValue,
@@ -859,6 +894,9 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
            parent.AddChild(variable);
            AddPredefinedNode(SystemContext, variable);
            _variables[variableNodeId] = variable;
+            // Phase C: register the resolved historian tagname so the HistoryRead override can map this
+            // NodeId back to its Aveva/historian source.
+            if (historized) _historizedTagnames[variableNodeId] = historianTagname!;
        }
    }

@@ -896,6 +934,8 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
                PredefinedNodes?.Remove(v.NodeId);
            }
            _variables.Clear();
+            // Phase C: drop the NodeId→historian-tagname registrations alongside the variables they map.
+            _historizedTagnames.Clear();

            foreach (var alarm in _alarmConditions.Values)
            {
@@ -197,7 +197,13 @@ public sealed class Phase7Applier
            }
            else
            {
-                SafeEnsureVariable(nodeId, parent, tag.Name, tag.DataType, tag.Writable);
+                // Phase C: a historized tag materialises Historizing + HistoryRead. Resolve the effective
+                // historian tagname HERE (default-vs-override): a null/blank override falls back to the
+                // driver-side FullName; null means the tag is not historized at all.
+                string? historianTagname = tag.IsHistorized
+                    ? (string.IsNullOrWhiteSpace(tag.HistorianTagname) ? tag.FullName : tag.HistorianTagname)
+                    : null;
+                SafeEnsureVariable(nodeId, parent, tag.Name, tag.DataType, tag.Writable, historianTagname);
            }
        }

@@ -291,9 +297,9 @@ public sealed class Phase7Applier
        catch (Exception ex) { _logger.LogWarning(ex, "Phase7Applier: EnsureFolder threw for {Node}", nodeId); }
    }

-    private void SafeEnsureVariable(string nodeId, string? parentNodeId, string displayName, string dataType, bool writable)
+    private void SafeEnsureVariable(string nodeId, string? parentNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
    {
-        try { _sink.EnsureVariable(nodeId, parentNodeId, displayName, dataType, writable); }
+        try { _sink.EnsureVariable(nodeId, parentNodeId, displayName, dataType, writable, historianTagname); }
        catch (Exception ex) { _logger.LogWarning(ex, "Phase7Applier: EnsureVariable threw for {Node}", nodeId); }
    }

@@ -57,8 +57,10 @@ public sealed class SdkAddressSpaceSink : IOpcUaAddressSpaceSink
    /// <param name="displayName">The display name for the variable.</param>
    /// <param name="dataType">The OPC UA data type.</param>
    /// <param name="writable">When true the node is created read/write; otherwise read-only.</param>
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable)
-        => _nodeManager.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable);
+    /// <param name="historianTagname">null ⇒ not historized; non-null ⇒ create Historizing with the
+    /// HistoryRead access bit and register the historian tagname.</param>
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
+        => _nodeManager.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, historianTagname);

    /// <summary>Rebuilds the entire OPC UA address space.</summary>
    public void RebuildAddressSpace() => _nodeManager.RebuildAddressSpace();