lmxopcua/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/DeferredAddressSpaceSinkTests.cs

using System.Collections.Concurrent;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;

namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests;

public sealed class DeferredAddressSpaceSinkTests
{
    /// <summary>Verifies that the default inner is a null sink so calls before SetSink are safe.</summary>
    [Fact]
    public void Default_inner_is_null_sink_so_calls_before_SetSink_are_safe()
    {
        var deferred = new DeferredAddressSpaceSink();

        // No throw, no observable side effect.
        deferred.WriteValue("x", 1, OpcUaQuality.Good, DateTime.UtcNow, AddressSpaceRealm.Uns);
        deferred.WriteAlarmCondition("a", Snapshot(active: true), DateTime.UtcNow, AddressSpaceRealm.Uns);
        deferred.RebuildAddressSpace();
    }

    /// <summary>Verifies that calls after SetSink are forwarded to the inner sink.</summary>
    [Fact]
    public void Calls_after_SetSink_are_forwarded_to_the_inner()
    {
        var deferred = new DeferredAddressSpaceSink();
        var inner = new RecordingSink();
        deferred.SetSink(inner);

        deferred.WriteValue("x", 42, OpcUaQuality.Good, DateTime.UtcNow, AddressSpaceRealm.Uns);
        deferred.WriteAlarmCondition("a-1", Snapshot(active: true), DateTime.UtcNow, AddressSpaceRealm.Uns);
        deferred.RebuildAddressSpace();
        deferred.RaiseNodesAddedModelChange("eq-1", AddressSpaceRealm.Uns);

        inner.Calls.ShouldBe(new[] { "WV:x", "WA:a-1", "RB", "NA:eq-1" });
    }

    /// <summary>Verifies that setting sink to null reverts to null sink.</summary>
    [Fact]
    public void SetSink_to_null_reverts_to_null_sink()
    {
        var deferred = new DeferredAddressSpaceSink();
        var inner = new RecordingSink();
        deferred.SetSink(inner);
        deferred.WriteValue("x", 1, OpcUaQuality.Good, DateTime.UtcNow, AddressSpaceRealm.Uns);
        inner.Calls.Count.ShouldBe(1);

        deferred.SetSink(null);
        deferred.WriteValue("y", 2, OpcUaQuality.Good, DateTime.UtcNow, AddressSpaceRealm.Uns); // dropped
        inner.Calls.Count.ShouldBe(1);
    }

    /// <summary>Verifies that sink can be swapped between implementations.</summary>
    [Fact]
    public void SetSink_can_swap_between_implementations()
    {
        var deferred = new DeferredAddressSpaceSink();
        var first = new RecordingSink();
        var second = new RecordingSink();

        deferred.SetSink(first);
        deferred.WriteValue("a", 1, OpcUaQuality.Good, DateTime.UtcNow, AddressSpaceRealm.Uns);

        deferred.SetSink(second);
        deferred.WriteValue("b", 2, OpcUaQuality.Good, DateTime.UtcNow, AddressSpaceRealm.Uns);

        first.Calls.Single().ShouldBe("WV:a");
        second.Calls.Single().ShouldBe("WV:b");
    }

    /// <summary>Verifies that <see cref="DeferredAddressSpaceSink.EnsureVariable"/> forwards the
    /// <c>historianTagname</c> argument to the inner sink unchanged.</summary>
    [Fact]
    public void EnsureVariable_forwards_historianTagname_to_inner_sink()
    {
        var deferred = new DeferredAddressSpaceSink();
        var inner = new RecordingSink();
        deferred.SetSink(inner);

        deferred.EnsureVariable("v-1", null, "MyVar", "Float", writable: false, historianTagname: "MyTag.PV", realm: AddressSpaceRealm.Uns);

        var call = inner.HistorianCalls.ShouldHaveSingleItem();
        call.NodeId.ShouldBe("v-1");
        call.HistorianTagname.ShouldBe("MyTag.PV");
    }

    /// <summary>F10b regression: the deferred wrapper MUST forward the surgical capability to a
    /// surgical inner sink — otherwise <c>AddressSpaceApplier</c> (which injects THIS wrapper on every
    /// driver-role host, not the inner <c>SdkAddressSpaceSink</c>) never sees the capability and the
    /// in-place tag-attribute optimization is inert in production (it silently falls back to rebuild).</summary>
    [Fact]
    public void UpdateTagAttributes_forwards_to_a_surgical_inner_sink()
    {
        var deferred = new DeferredAddressSpaceSink();
        var inner = new SurgicalRecordingSink { Result = true };
        deferred.SetSink(inner);

        ((ISurgicalAddressSpaceSink)deferred).UpdateTagAttributes("v-1", writable: true, historianTagname: "MyTag.PV",
            dataType: "Int32", isArray: true, arrayLength: 8u, AddressSpaceRealm.Uns)
            .ShouldBeTrue();

        var call = inner.SurgicalCalls.ShouldHaveSingleItem();
        call.NodeId.ShouldBe("v-1");
        call.Writable.ShouldBeTrue();
        call.Historian.ShouldBe("MyTag.PV");
        // FB-7: the DataType/array-shape args must forward verbatim too — a partial forward would silently
        // drop the shape update on every driver-role host.
        call.DataType.ShouldBe("Int32");
        call.IsArray.ShouldBeTrue();
        call.ArrayLength.ShouldBe(8u);
    }

    /// <summary>The surgical forward returns the inner's own result (false ⇒ node missing) so the caller
    /// falls back to a full rebuild.</summary>
    [Fact]
    public void UpdateTagAttributes_returns_inner_result_when_node_missing()
    {
        var deferred = new DeferredAddressSpaceSink();
        deferred.SetSink(new SurgicalRecordingSink { Result = false });

        ((ISurgicalAddressSpaceSink)deferred).UpdateTagAttributes("v-1", writable: false, historianTagname: null,
            dataType: "Float", isArray: false, arrayLength: null, AddressSpaceRealm.Uns)
            .ShouldBeFalse();
    }

    /// <summary>When the inner sink does NOT implement <see cref="ISurgicalAddressSpaceSink"/> (e.g. the
    /// null sink before the real one is swapped in, or any non-surgical sink) the wrapper returns false
    /// so the caller rebuilds.</summary>
    [Fact]
    public void UpdateTagAttributes_returns_false_when_inner_is_not_surgical()
    {
        var deferred = new DeferredAddressSpaceSink();   // default inner = null sink (not surgical)
        ((ISurgicalAddressSpaceSink)deferred).UpdateTagAttributes("v-1", writable: true, historianTagname: null,
            dataType: "Float", isArray: false, arrayLength: null, AddressSpaceRealm.Uns)
            .ShouldBeFalse();

        deferred.SetSink(new RecordingSink());           // a non-surgical inner
        ((ISurgicalAddressSpaceSink)deferred).UpdateTagAttributes("v-1", writable: true, historianTagname: null,
            dataType: "Float", isArray: false, arrayLength: null, AddressSpaceRealm.Uns)
            .ShouldBeFalse();
    }

    /// <summary>OpcUaServer-001 regression: the deferred wrapper MUST forward the folder-rename surgical
    /// capability to a surgical inner sink — otherwise <c>AddressSpaceApplier</c> (which injects THIS
    /// wrapper on every driver-role host) never sees the capability and the in-place UNS Area/Line rename
    /// refresh is inert in production (silently falls back to a full rebuild).</summary>
    [Fact]
    public void UpdateFolderDisplayName_forwards_to_a_surgical_inner_sink()
    {
        var deferred = new DeferredAddressSpaceSink();
        var inner = new SurgicalRecordingSink { Result = true };
        deferred.SetSink(inner);

        ((ISurgicalAddressSpaceSink)deferred).UpdateFolderDisplayName("area-1", "Plant South", AddressSpaceRealm.Uns)
            .ShouldBeTrue();

        var call = inner.FolderRenameCalls.ShouldHaveSingleItem();
        call.FolderNodeId.ShouldBe("area-1");
        call.DisplayName.ShouldBe("Plant South");
    }

    /// <summary>The folder-rename forward returns the inner's own result (false ⇒ folder missing) so the
    /// caller falls back to a full rebuild; and returns false when the inner is not surgical at all.</summary>
    [Fact]
    public void UpdateFolderDisplayName_returns_inner_result_and_false_when_not_surgical()
    {
        var deferred = new DeferredAddressSpaceSink();
        // Inner reports the folder missing ⇒ forward returns false.
        deferred.SetSink(new SurgicalRecordingSink { Result = false });
        ((ISurgicalAddressSpaceSink)deferred).UpdateFolderDisplayName("area-1", "X", AddressSpaceRealm.Uns).ShouldBeFalse();

        // Non-surgical inner (the null sink before swap-in) ⇒ false.
        deferred.SetSink(null);
        ((ISurgicalAddressSpaceSink)deferred).UpdateFolderDisplayName("area-1", "X", AddressSpaceRealm.Uns).ShouldBeFalse();
    }

    /// <summary>R2-07 Phase 2 — the three surgical remove members forward to a surgical inner with
    /// arg-fidelity (kind + node id), returning the inner's own result; false when the inner is not surgical
    /// so the caller falls back to a full rebuild.</summary>
    [Fact]
    public void Remove_members_forward_to_a_surgical_inner_sink_with_arg_fidelity()
    {
        var deferred = new DeferredAddressSpaceSink();
        var inner = new SurgicalRecordingSink { Result = true };
        deferred.SetSink(inner);

        ((ISurgicalAddressSpaceSink)deferred).RemoveVariableNode("eq-1/A", AddressSpaceRealm.Uns).ShouldBeTrue();
        ((ISurgicalAddressSpaceSink)deferred).RemoveAlarmConditionNode("alm-1", AddressSpaceRealm.Uns).ShouldBeTrue();
        ((ISurgicalAddressSpaceSink)deferred).RemoveEquipmentSubtree("eq-1", AddressSpaceRealm.Uns).ShouldBeTrue();

        inner.RemoveCalls.ShouldBe(new[] { ("var", "eq-1/A"), ("alarm", "alm-1"), ("equipment", "eq-1") });
    }

    /// <summary>The remove forwards return the inner's own result (false ⇒ id unknown ⇒ caller rebuilds),
    /// and return false when the inner is not surgical at all.</summary>
    [Fact]
    public void Remove_members_return_inner_result_and_false_when_not_surgical()
    {
        var deferred = new DeferredAddressSpaceSink();
        deferred.SetSink(new SurgicalRecordingSink { Result = false });
        ((ISurgicalAddressSpaceSink)deferred).RemoveVariableNode("v-1", AddressSpaceRealm.Uns).ShouldBeFalse();
        ((ISurgicalAddressSpaceSink)deferred).RemoveAlarmConditionNode("a-1", AddressSpaceRealm.Uns).ShouldBeFalse();
        ((ISurgicalAddressSpaceSink)deferred).RemoveEquipmentSubtree("eq-1", AddressSpaceRealm.Uns).ShouldBeFalse();

        deferred.SetSink(null);
        ((ISurgicalAddressSpaceSink)deferred).RemoveVariableNode("v-1", AddressSpaceRealm.Uns).ShouldBeFalse();
        ((ISurgicalAddressSpaceSink)deferred).RemoveAlarmConditionNode("a-1", AddressSpaceRealm.Uns).ShouldBeFalse();
        ((ISurgicalAddressSpaceSink)deferred).RemoveEquipmentSubtree("eq-1", AddressSpaceRealm.Uns).ShouldBeFalse();
    }

    /// <summary>Builds a minimal <see cref="AlarmConditionSnapshot"/> for the forwarding tests (the
    /// inner sink only records the node id, so the exact state values don't matter here).</summary>
    private static AlarmConditionSnapshot Snapshot(bool active = false) =>
        new(active, Acknowledged: true, Confirmed: true, Enabled: true,
            Shelving: AlarmShelvingKind.Unshelved, Severity: 500, Message: "test");

    private sealed class RecordingSink : IOpcUaAddressSpaceSink
    {
        /// <summary>Gets the queue of recorded calls.</summary>
        public ConcurrentQueue<string> CallQueue { get; } = new();
        /// <summary>Gets the list of recorded calls.</summary>
        public List<string> Calls => CallQueue.ToList();

        /// <summary>Gets the queue of (NodeId, HistorianTagname) pairs captured per
        /// <c>EnsureVariable</c> call, in call order.</summary>
        public ConcurrentQueue<(string NodeId, string? HistorianTagname)> HistorianQueue { get; } = new();
        /// <summary>Gets the list of (NodeId, HistorianTagname) pairs captured per EnsureVariable call.</summary>
        public List<(string NodeId, string? HistorianTagname)> HistorianCalls => HistorianQueue.ToList();

        /// <inheritdoc />
        public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm = AddressSpaceRealm.Uns)
            => CallQueue.Enqueue($"WV:{nodeId}");
        /// <inheritdoc />
        public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc, AddressSpaceRealm realm = AddressSpaceRealm.Uns)
            => CallQueue.Enqueue($"WA:{alarmNodeId}");
        /// <inheritdoc />
        public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, AddressSpaceRealm realm, bool isNative = false)
            => CallQueue.Enqueue($"MA:{alarmNodeId}");
        /// <inheritdoc />
        public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName, AddressSpaceRealm realm = AddressSpaceRealm.Uns)
            => CallQueue.Enqueue($"EF:{folderNodeId}");
        /// <inheritdoc />
        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, AddressSpaceRealm realm, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
        {
            CallQueue.Enqueue($"EV:{variableNodeId}");
            HistorianQueue.Enqueue((variableNodeId, historianTagname));
        }
        /// <inheritdoc />
        public void RebuildAddressSpace() => CallQueue.Enqueue("RB");
        /// <inheritdoc />
        public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) => CallQueue.Enqueue($"NA:{affectedNodeId}");
        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
    }

    private sealed class SurgicalRecordingSink : IOpcUaAddressSpaceSink, ISurgicalAddressSpaceSink
    {
        /// <summary>Gets or sets the value <see cref="UpdateTagAttributes"/> + <see cref="UpdateFolderDisplayName"/> return.</summary>
        public bool Result { get; set; } = true;
        /// <summary>Gets the recorded surgical calls (incl. the FB-7 DataType/array-shape args).</summary>
        public List<(string NodeId, bool Writable, string? Historian, string DataType, bool IsArray, uint? ArrayLength)> SurgicalCalls { get; } = new();
        /// <summary>Gets the recorded surgical folder-rename calls (OpcUaServer-001).</summary>
        public List<(string FolderNodeId, string DisplayName)> FolderRenameCalls { get; } = new();

        /// <inheritdoc />
        public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength, AddressSpaceRealm realm = AddressSpaceRealm.Uns)
        {
            SurgicalCalls.Add((variableNodeId, writable, historianTagname, dataType, isArray, arrayLength));
            return Result;
        }

        /// <inheritdoc />
        public bool UpdateFolderDisplayName(string folderNodeId, string displayName, AddressSpaceRealm realm = AddressSpaceRealm.Uns)
        {
            FolderRenameCalls.Add((folderNodeId, displayName));
            return Result;
        }

        /// <summary>Gets the recorded surgical remove calls (kind + node id), in call order (R2-07 Phase 2).</summary>
        public List<(string Kind, string NodeId)> RemoveCalls { get; } = new();

        /// <inheritdoc />
        public bool RemoveVariableNode(string variableNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { RemoveCalls.Add(("var", variableNodeId)); return Result; }
        /// <inheritdoc />
        public bool RemoveAlarmConditionNode(string alarmNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { RemoveCalls.Add(("alarm", alarmNodeId)); return Result; }
        /// <inheritdoc />
        public bool RemoveEquipmentSubtree(string equipmentNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { RemoveCalls.Add(("equipment", equipmentNodeId)); return Result; }

        /// <inheritdoc />
        public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
        /// <inheritdoc />
        public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
        /// <inheritdoc />
        public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, AddressSpaceRealm realm, bool isNative = false) { }
        /// <inheritdoc />
        public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
        /// <inheritdoc />
        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, AddressSpaceRealm realm, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
        /// <inheritdoc />
        public void RebuildAddressSpace() { }
        /// <inheritdoc />
        public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) { }
        public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
    }
}