review(Commons): record findings + add deferred-sink/equip-nodeid tests, fix stale Phase7 doc

Code review at HEAD 7286d320. Commons-001 (stale Phase7 telemetry doc) fixed; Commons-003/004 close test-coverage gaps (DeferredAddressSpaceSink/ServiceLevelPublisher forwarding seam + EquipmentNodeIds whitespace branch). Commons-002 (CorrelationId typing) deferred as cross-cutting.
2026-06-19 10:22:59 -04:00
parent 7286d3208a
commit 6dc74289ce
5 changed files with 332 additions and 1 deletions
@@ -0,0 +1,154 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Tests.OpcUa;
+
+/// <summary>
+/// Covers the deferred-sink forwarding invariants documented in Commons-003.
+/// The DeferredAddressSpaceSink is a production-critical seam: a new optional capability
+/// interface MUST be forwarded through it or the optimization is inert on every driver-role
+/// host (DeferredAddressSpaceSink is what actors inject, not the inner sink directly).
+/// </summary>
+public class DeferredAddressSpaceSinkTests
+{
+    // ---------- before SetSink — all calls are safe no-ops ----------
+
+    [Fact]
+    public void Before_SetSink_WriteValue_is_a_noop()
+    {
+        var sink = new DeferredAddressSpaceSink();
+        // Must not throw.
+        sink.WriteValue("ns=2;s=x", 42, OpcUaQuality.Good, DateTime.UtcNow);
+    }
+
+    [Fact]
+    public void Before_SetSink_RebuildAddressSpace_is_a_noop()
+    {
+        var sink = new DeferredAddressSpaceSink();
+        sink.RebuildAddressSpace(); // Must not throw.
+    }
+
+    [Fact]
+    public void Before_SetSink_UpdateTagAttributes_returns_false()
+    {
+        var sink = new DeferredAddressSpaceSink();
+        sink.UpdateTagAttributes("ns=2;s=x", writable: true, historianTagname: null,
+            dataType: "Boolean", isArray: false, arrayLength: null).ShouldBeFalse();
+    }
+
+    // ---------- after SetSink — operations are forwarded ----------
+
+    [Fact]
+    public void After_SetSink_WriteValue_is_forwarded()
+    {
+        var inner = new SpySink();
+        var sink = new DeferredAddressSpaceSink();
+        sink.SetSink(inner);
+
+        sink.WriteValue("ns=2;s=x", 99, OpcUaQuality.Good, DateTime.UtcNow);
+
+        inner.WriteValueCalled.ShouldBeTrue();
+    }
+
+    [Fact]
+    public void After_SetSink_RebuildAddressSpace_is_forwarded()
+    {
+        var inner = new SpySink();
+        var sink = new DeferredAddressSpaceSink();
+        sink.SetSink(inner);
+
+        sink.RebuildAddressSpace();
+
+        inner.RebuildCalled.ShouldBeTrue();
+    }
+
+    // ---------- ISurgicalAddressSpaceSink forwarding ----------
+
+    [Fact]
+    public void UpdateTagAttributes_returns_false_for_non_surgical_inner()
+    {
+        // SpySink does NOT implement ISurgicalAddressSpaceSink.
+        var sink = new DeferredAddressSpaceSink();
+        sink.SetSink(new SpySink());
+
+        sink.UpdateTagAttributes("ns=2;s=x", writable: true, historianTagname: null,
+            dataType: "Int32", isArray: false, arrayLength: null).ShouldBeFalse();
+    }
+
+    [Fact]
+    public void UpdateTagAttributes_returns_true_for_surgical_inner()
+    {
+        var surgical = new SpySurgicalSink();
+        var sink = new DeferredAddressSpaceSink();
+        sink.SetSink(surgical);
+
+        var result = sink.UpdateTagAttributes("ns=2;s=x", writable: true, historianTagname: null,
+            dataType: "Float", isArray: false, arrayLength: null);
+
+        result.ShouldBeTrue();
+        surgical.UpdateCalled.ShouldBeTrue();
+    }
+
+    // ---------- SetSink(null) reverts to null sink ----------
+
+    [Fact]
+    public void SetSink_null_reverts_to_null_sink_and_UpdateTagAttributes_returns_false()
+    {
+        var surgical = new SpySurgicalSink();
+        var sink = new DeferredAddressSpaceSink();
+        sink.SetSink(surgical);
+        sink.SetSink(null); // revert
+
+        sink.UpdateTagAttributes("ns=2;s=x", writable: false, historianTagname: null,
+            dataType: "Boolean", isArray: false, arrayLength: null).ShouldBeFalse();
+    }
+
+    [Fact]
+    public void SetSink_null_reverts_to_null_sink_and_WriteValue_is_noop()
+    {
+        var inner = new SpySink();
+        var sink = new DeferredAddressSpaceSink();
+        sink.SetSink(inner);
+        sink.SetSink(null); // revert
+
+        sink.WriteValue("ns=2;s=x", 1, OpcUaQuality.Good, DateTime.UtcNow);
+
+        inner.WriteValueCalled.ShouldBeFalse("write should be no-op after reverting to null sink");
+    }
+
+    // ---- test doubles ----
+
+    private sealed class SpySink : IOpcUaAddressSpaceSink
+    {
+        public bool WriteValueCalled { get; private set; }
+        public bool RebuildCalled { get; private set; }
+
+        public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc)
+            => WriteValueCalled = true;
+
+        public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc) { }
+        public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, bool isNative = false) { }
+        public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName) { }
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
+        public void RebuildAddressSpace() => RebuildCalled = true;
+    }
+
+    private sealed class SpySurgicalSink : IOpcUaAddressSpaceSink, ISurgicalAddressSpaceSink
+    {
+        public bool UpdateCalled { get; private set; }
+
+        public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc) { }
+        public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc) { }
+        public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, bool isNative = false) { }
+        public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName) { }
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
+        public void RebuildAddressSpace() { }
+
+        public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength)
+        {
+            UpdateCalled = true;
+            return true;
+        }
+    }
+}
@@ -0,0 +1,53 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Tests.OpcUa;
+
+/// <summary>
+/// Covers DeferredServiceLevelPublisher forwarding invariants (Commons-003 companion).
+/// </summary>
+public class DeferredServiceLevelPublisherTests
+{
+    [Fact]
+    public void Before_SetInner_Publish_is_a_noop()
+    {
+        var publisher = new DeferredServiceLevelPublisher();
+        // Must not throw; the NullServiceLevelPublisher absorbs it.
+        publisher.Publish(200);
+    }
+
+    [Fact]
+    public void After_SetInner_Publish_is_forwarded()
+    {
+        var spy = new SpyPublisher();
+        var publisher = new DeferredServiceLevelPublisher();
+        publisher.SetInner(spy);
+
+        publisher.Publish(240);
+
+        spy.LastPublished.ShouldBe((byte)240);
+    }
+
+    [Fact]
+    public void SetInner_null_reverts_to_null_publisher()
+    {
+        var spy = new SpyPublisher();
+        var publisher = new DeferredServiceLevelPublisher();
+        publisher.SetInner(spy);
+        publisher.SetInner(null); // revert
+
+        publisher.Publish(100);
+
+        // The spy should NOT have received the publish after revert.
+        spy.LastPublished.ShouldBe((byte)0, "spy should not have been updated after revert to null");
+    }
+
+    // ---- test double ----
+
+    private sealed class SpyPublisher : IServiceLevelPublisher
+    {
+        public byte LastPublished { get; private set; }
+        public void Publish(byte serviceLevel) => LastPublished = serviceLevel;
+    }
+}
@@ -18,6 +18,10 @@ public class EquipmentNodeIdsTests
    public void Variable_with_folder_is_equipment_slash_folder_slash_name()
        => EquipmentNodeIds.Variable("eq-1", "registers", "speed").ShouldBe("eq-1/registers/speed");

+    [Fact]
+    public void Variable_with_whitespace_folder_is_equipment_slash_name()
+        => EquipmentNodeIds.Variable("eq-1", "   ", "speed").ShouldBe("eq-1/speed");
+
    [Fact]
    public void SubFolder_is_equipment_slash_folder()
        => EquipmentNodeIds.SubFolder("eq-1", "registers").ShouldBe("eq-1/registers");