fix(driver-modbus): resolve Low code-review findings (Driver.Modbus-003,007,008,009,010,011,012)

- Driver.Modbus-003: route every _health access through ReadHealth / WriteHealth helpers backed by Volatile.Read / Volatile.Write so a burst of concurrent ReadAsync callers always sees a complete snapshot. - Driver.Modbus-007: promoted the Int64 / UInt64 → Int32 surfacing caveat to a full <remarks> block; rewrote DisableFC23's doc to flag it as reserved / no-op. - Driver.Modbus-008: deleted stale duplicate doc, rewrote the prohibition-block summaries to credit the shipped re-probe loop, and removed the unused 'status' local in the ModbusException catch arm. - Driver.Modbus-009: bind-time validation rejects StringLength < 1 for String tags; ModbusTcpTransport clamps keep-alive intervals to whole seconds (>=1). - Driver.Modbus-010: documented WriteOnChangeOnly's cache-invalidation policy (reads-only) and the write-only-tag caveat. - Driver.Modbus-011: collected the scattered instance fields into a single contiguous block at the top of ModbusDriver. - Driver.Modbus-012: covered the previously-uncovered Reinitialize state-hygiene, malformed/truncated/empty-bitmap response, and DisposeAsync teardown paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-23 08:17:51 -04:00
parent 3c75db7eb6
commit d5322b0f9a
7 changed files with 695 additions and 136 deletions
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusEdgeCaseValidationTests.cs
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusEdgeCaseValidationTests.cs
@@ -0,0 +1,106 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
+
+/// <summary>
+///     Regression coverage for Driver.Modbus-009: two configuration edge cases that previously
+///     silently produced wrong wire behaviour.
+///     (1) <c>StringLength = 0</c> for a <c>String</c>-typed tag — used to flow into an FC03
+///     with quantity 0, a spec-illegal request the PLC rejects with exception 03. Now bind-time
+///     validation in <c>ModbusDriverFactoryExtensions</c> rejects the misconfiguration with a
+///     clear diagnostic.
+///     (2) Sub-second <see cref="TimeSpan"/> values on <c>ModbusKeepAliveOptions.Time</c> /
+///     <c>Interval</c> — the int-cast in <c>EnableKeepAlive</c> truncated <c>500&#160;ms</c> to
+///     <c>0</c>, which most OSes interpret as "use the default", silently defeating the
+///     configured timing. <c>ModbusTcpTransport.ClampToWholeSeconds</c> rounds up to a minimum
+///     of 1&#160;second.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class ModbusEdgeCaseValidationTests
+{
+    [Fact]
+    public void Factory_rejects_String_tag_with_StringLength_zero_via_structured_form()
+    {
+        const string json = """
+        {
+          "host": "10.0.0.10",
+          "tags": [
+            { "name": "Greeting", "region": "HoldingRegisters", "address": 100, "dataType": "String", "stringLength": 0 }
+          ]
+        }
+        """;
+        var ex = Should.Throw<InvalidOperationException>(
+            () => ModbusDriverFactoryExtensions.CreateInstance("modbus-1", json));
+        ex.Message.ShouldContain("StringLength");
+        ex.Message.ShouldContain("Greeting");
+    }
+
+    [Fact]
+    public void Factory_rejects_String_tag_with_StringLength_zero_via_missing_field()
+    {
+        // No stringLength → defaults to 0. Same misconfiguration via a different DTO shape.
+        const string json = """
+        {
+          "host": "10.0.0.10",
+          "tags": [
+            { "name": "Greeting", "region": "HoldingRegisters", "address": 100, "dataType": "String" }
+          ]
+        }
+        """;
+        var ex = Should.Throw<InvalidOperationException>(
+            () => ModbusDriverFactoryExtensions.CreateInstance("modbus-1", json));
+        ex.Message.ShouldContain("StringLength");
+    }
+
+    [Fact]
+    public void Factory_accepts_String_tag_with_StringLength_one()
+    {
+        const string json = """
+        {
+          "host": "10.0.0.10",
+          "tags": [
+            { "name": "Greeting", "region": "HoldingRegisters", "address": 100, "dataType": "String", "stringLength": 1 }
+          ]
+        }
+        """;
+        Should.NotThrow(() => ModbusDriverFactoryExtensions.CreateInstance("modbus-1", json));
+    }
+
+    [Fact]
+    public void Factory_accepts_non_String_tag_with_StringLength_zero()
+    {
+        // The validation only kicks in for String tags — Int16 tags with StringLength=0 are normal.
+        const string json = """
+        {
+          "host": "10.0.0.10",
+          "tags": [
+            { "name": "Level", "region": "HoldingRegisters", "address": 100, "dataType": "Int16" }
+          ]
+        }
+        """;
+        Should.NotThrow(() => ModbusDriverFactoryExtensions.CreateInstance("modbus-1", json));
+    }
+
+    [Theory]
+    [InlineData(0, 1)]       // zero clamps up to 1
+    [InlineData(500, 1)]     // 500 ms rounds up to 1
+    [InlineData(999, 1)]     // just under 1s rounds up to 1
+    [InlineData(1_000, 1)]   // exactly 1s passes through
+    [InlineData(1_500, 2)]   // 1.5s rounds up to 2
+    [InlineData(30_000, 30)] // historical PR 53 default — unchanged
+    [InlineData(60_000, 60)]
+    public void ClampToWholeSeconds_rounds_up_to_at_least_one_second(int ms, int expected)
+    {
+        ModbusTcpTransport.ClampToWholeSeconds(TimeSpan.FromMilliseconds(ms)).ShouldBe(expected);
+    }
+
+    [Fact]
+    public void ClampToWholeSeconds_treats_negative_TimeSpan_as_one_second()
+    {
+        // Defensive — operators occasionally configure a negative TimeSpan thinking it disables
+        // the feature. The OS would reject the negative int — clamping to 1 keeps the socket
+        // valid until the operator fixes the config.
+        ModbusTcpTransport.ClampToWholeSeconds(TimeSpan.FromSeconds(-5)).ShouldBe(1);
+    }
+}