feat(otopcua): GeneralModelChangeEvent(NodeAdded) for runtime node adds

2026-06-26 06:55:52 -04:00
parent d7a0da5ea1
commit 33b0e639a5
2 changed files with 208 additions and 0 deletions
@@ -1567,6 +1567,93 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
        }
    }

+    /// <summary>
+    ///     Emit a Part 3 <c>GeneralModelChangeEvent</c> (verb <c>NodeAdded</c>) announcing that one or more
+    ///     nodes were added UNDER <paramref name="affectedNodeId"/> at runtime — so already-connected,
+    ///     model-aware OPC UA clients re-browse the affected node and discover the new children. This is the
+    ///     runtime-add counterpart of the shape-changed reporter (<see cref="ReportNodeShapeChangedEvent"/>):
+    ///     when a driver discovers FixedTree nodes AFTER the server is up and they are materialised into the
+    ///     served Equipment address space (Tasks 4/5), an attribute notification alone is invisible to a
+    ///     subscribed client — only a model-change event tells it the address space grew.
+    ///     <para>
+    ///         Built AND reported under <c>Lock</c> (like <see cref="ReportConditionEvent"/>) and wrapped in
+    ///         try/catch so it is tolerant when eventing is disabled / there are no monitored items / the
+    ///         server is shutting down — the same swallow-and-log tolerance as the write-revert path
+    ///         (<see cref="ReportAuditEvent"/>). The nodes have already been materialised, so a surprise from
+    ///         the event path MUST NOT propagate out of this announcement.
+    ///     </para>
+    /// </summary>
+    /// <param name="affectedNodeId">The folder-scoped node id of the parent under which nodes were added.</param>
+    public void RaiseNodesAddedModelChange(string affectedNodeId)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(affectedNodeId);
+        lock (Lock)
+        {
+            try
+            {
+                Server.ReportEvent(SystemContext, BuildNodesAddedModelChange(affectedNodeId));
+            }
+            catch (Exception ex)
+            {
+                // Model-change reporting disabled / no monitored items / server shutting down ⇒ ReportEvent may
+                // no-op or throw; either way the node add already stands. Log to the SDK trace, don't rethrow.
+#pragma warning disable CS0618 // Utils.LogError is [Obsolete] in favour of an ITelemetryContext this manager doesn't carry.
+                Utils.LogError(ex, "OtOpcUaNodeManager: failed to report GeneralModelChangeEvent(NodeAdded) for {0}", affectedNodeId);
+#pragma warning restore CS0618
+            }
+        }
+    }
+
+    /// <summary>Build (but do not report) the Part 3 <c>GeneralModelChangeEvent</c> announcing that nodes were
+    /// added under <paramref name="affectedNodeId"/>. MIRRORS <see cref="BuildNodeShapeChangedEvent"/> exactly —
+    /// the only differences are <c>Verb = NodeAdded</c> (vs <c>DataTypeChanged</c>) and <c>Affected</c> = the
+    /// passed parent node id (vs the variable's own NodeId). <c>AffectedType</c> carries the affected node's
+    /// TypeDefinition resolved from the live node maps (same semantics the shape-changed builder gets from the
+    /// variable), defaulting to <see cref="NodeId.Null"/> when the id is not (yet) materialised. <c>internal</c>
+    /// (not private) so a node-manager test can assert the populated Changes structure at the nearest
+    /// deterministic seam (the end-to-end <c>Server.ReportEvent</c> dispatch would need a subscribed event
+    /// monitored-item to observe).</summary>
+    /// <param name="affectedNodeId">The folder-scoped node id of the parent under which nodes were added.</param>
+    /// <returns>A populated, unreported <see cref="GeneralModelChangeEventState"/>.</returns>
+    internal GeneralModelChangeEventState BuildNodesAddedModelChange(string affectedNodeId)
+    {
+        var affected = new NodeId(affectedNodeId, NamespaceIndex);
+        var e = new GeneralModelChangeEventState(null);
+        e.Initialize(
+            SystemContext,
+            source: null,
+            severity: EventSeverity.Medium,
+            message: new LocalizedText($"Nodes added under {affected}"));
+        // Part 3 §8.7.4: a GeneralModelChangeEvent is emitted by the Server object — set SourceNode/SourceName
+        // to Server explicitly (we report with source:null since this manager has no Server NodeState handle),
+        // so conformant clients that filter events by SourceNode still match this one.
+        e.SetChildValue(SystemContext, BrowseNames.SourceNode, ObjectIds.Server, false);
+        e.SetChildValue(SystemContext, BrowseNames.SourceName, "Server", false);
+        var change = new ModelChangeStructureDataType
+        {
+            Affected = affected,
+            // The affected node is the parent the children were added under; carry its TypeDefinition (a Folder
+            // for an equipment parent) just as the shape-changed builder carries the variable's. Null when the
+            // id is unknown — a valid Part 3 "type not applicable", and clients re-browse Affected regardless.
+            AffectedType = ResolveAffectedTypeDefinition(affectedNodeId),
+            Verb = (byte)ModelChangeStructureVerbMask.NodeAdded,
+        };
+        // SetChildValue lazily creates + sets the Changes property (same pattern the audit-event builder
+        // relies on for its child PropertyStates).
+        e.SetChildValue(SystemContext, BrowseNames.Changes, new[] { change }, false);
+        return e;
+    }
+
+    /// <summary>Resolve the TypeDefinition of a materialised node id from the live folder/variable maps for a
+    /// model-change event's <c>AffectedType</c>; <see cref="NodeId.Null"/> when the id is not registered.</summary>
+    /// <param name="nodeId">The folder-scoped node id whose TypeDefinition is wanted.</param>
+    private NodeId ResolveAffectedTypeDefinition(string nodeId)
+    {
+        if (_folders.TryGetValue(nodeId, out var folder)) return folder.TypeDefinitionId;
+        if (_variables.TryGetValue(nodeId, out var variable)) return variable.TypeDefinitionId;
+        return NodeId.Null;
+    }
+
    /// <summary>Map a Tag.DataType string ("Boolean", "Int32", "Float", "Double", "String",
    /// "DateTime") to the OPC UA built-in NodeId. Unknown names fall back to BaseDataType
    /// (matches CreateVariable's default for lazy-created nodes).</summary>