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

src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs

@@ -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>

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/NodeManagerModelChangeOnAddTests.cs

@@ -0,0 +1,121 @@
+using Opc.Ua;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests;
+
+/// <summary>
+///     FixedTree injection — the BEHAVIOURAL half of the runtime node-add model-change announcement. When a
+///     driver discovers FixedTree nodes AFTER the server is up and they are materialised into the served
+///     Equipment address space, already-connected OPC UA clients won't see them unless the server emits a
+///     Part 3 <c>GeneralModelChangeEvent</c> (verb <c>NodeAdded</c>) under the affected parent so subscribed
+///     clients refresh their browse. <see cref="OtOpcUaNodeManager.RaiseNodesAddedModelChange"/> is that seam
+///     (Tasks 4/5 call it after materialising discovered nodes); this test asserts:
+///     <list type="bullet">
+///         <item>the built event announces the affected parent with verb <c>NodeAdded</c> (the runtime-add
+///         counterpart of <see cref="NodeManagerSurgicalShapeUpdateTests"/>'s <c>DataTypeChanged</c> case);</item>
+///         <item>raising it is tolerant — callable before AND after nodes exist, and never throws even when the
+///         event path is disabled / has no monitored items.</item>
+///     </list>
+///     <para>
+///         Coverage boundary (deliberate, mirrors <see cref="NodeManagerSurgicalShapeUpdateTests"/>): the
+///         model-change event is asserted via its <i>builder</i>
+///         (<see cref="OtOpcUaNodeManager.BuildNodesAddedModelChange"/>) in isolation, not its end-to-end
+///         <c>Server.ReportEvent</c> dispatch — observing that would require a subscribed event monitored-item.
+///         The single in-lock report call-site is covered by inspection (it mirrors the shape-changed reporter).
+///     </para>
+/// </summary>
+public sealed class NodeManagerModelChangeOnAddTests : IDisposable
+{
+    private static CancellationToken Ct => TestContext.Current.CancellationToken;
+
+    private readonly string _pkiRoot = Path.Combine(
+        Path.GetTempPath(),
+        $"otopcua-modelchange-add-{Guid.NewGuid():N}");
+
+    /// <summary>The built model-change event announces the affected parent with verb NodeAdded and the parent's
+    /// TypeDefinition as AffectedType — what model-aware clients consume to re-browse the new children.</summary>
+    [Trait("Category", "Unit")]
+    [Fact]
+    public async Task Built_nodes_added_event_announces_the_affected_parent_with_NodeAdded_verb()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+
+        nm.EnsureFolder("eq-7", parentNodeId: null, displayName: "Equipment 7");
+        nm.EnsureVariable("eq-7/speed", parentFolderNodeId: "eq-7", displayName: "Speed", dataType: "Float", writable: false);
+        var parent = nm.TryGetFolder("eq-7")!;
+
+        var e = nm.BuildNodesAddedModelChange("eq-7");
+
+        e.ShouldNotBeNull();
+        e.Changes.ShouldNotBeNull();
+        var changes = e.Changes.Value;
+        changes.Length.ShouldBe(1);
+        changes[0].Affected.ShouldBe(parent.NodeId);
+        changes[0].AffectedType.ShouldBe(ObjectTypeIds.FolderType);
+        changes[0].Verb.ShouldBe((byte)ModelChangeStructureVerbMask.NodeAdded);
+
+        await host.DisposeAsync();
+    }
+
+    /// <summary>Raising the announcement is tolerant: callable before any nodes exist (unknown affected id ⇒
+    /// AffectedType defaults to null, still a valid Part 3 change) AND after they are materialised, and never
+    /// throws even when the event path reaches no monitored items (same tolerance as the write-revert path).</summary>
+    [Trait("Category", "Unit")]
+    [Fact]
+    public async Task Raising_nodes_added_is_tolerant_before_and_after_nodes_exist()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+
+        // Before any nodes exist under the parent — must not throw.
+        Should.NotThrow(() => nm.RaiseNodesAddedModelChange("eq-9"));
+
+        nm.EnsureFolder("eq-9", parentNodeId: null, displayName: "Equipment 9");
+        nm.EnsureVariable("eq-9/temp", parentFolderNodeId: "eq-9", displayName: "Temp", dataType: "Float", writable: false);
+
+        // After the nodes are materialised — still must not throw.
+        Should.NotThrow(() => nm.RaiseNodesAddedModelChange("eq-9"));
+
+        await host.DisposeAsync();
+    }
+
+    private async Task<(OpcUaApplicationHost Host, OtOpcUaSdkServer Server)> BootAsync()
+    {
+        var host = new OpcUaApplicationHost(
+            new OpcUaApplicationHostOptions
+            {
+                ApplicationName = "OtOpcUa.ModelChangeOnAddTest",
+                ApplicationUri = $"urn:OtOpcUa.ModelChangeOnAddTest:{Guid.NewGuid():N}",
+                OpcUaPort = AllocateFreePort(),
+                PublicHostname = "localhost",
+                PkiStoreRoot = _pkiRoot,
+            },
+            Microsoft.Extensions.Logging.Abstractions.NullLogger<OpcUaApplicationHost>.Instance);
+
+        var server = new OtOpcUaSdkServer();
+        await host.StartAsync(server, Ct);
+        return (host, server);
+    }
+
+    private static int AllocateFreePort()
+    {
+        using var listener = new System.Net.Sockets.TcpListener(System.Net.IPAddress.Loopback, 0);
+        listener.Start();
+        var port = ((System.Net.IPEndPoint)listener.LocalEndpoint).Port;
+        listener.Stop();
+        return port;
+    }
+
+    /// <summary>Cleans up the PKI root directory.</summary>
+    public void Dispose()
+    {
+        if (Directory.Exists(_pkiRoot))
+        {
+            try { Directory.Delete(_pkiRoot, recursive: true); }
+            catch { /* best-effort cleanup */ }
+        }
+    }
+}