fix(drivers): wire PollGroupEngine onError->health + 30s poll backoff (05/STAB-9) [modbus,abcip,ablegacy]

archreview/plans/R2-09-driver-fleet-batch-plan.md.tasks.json

@@ -79,7 +79,7 @@
     {
       "id": "B3.3",
       "subject": "B3: wire onError->health + 30s backoffCap into Modbus/AbCip/AbLegacy engine ctors (tests first per driver) \u2014 STAB-9",
-      "status": "pending",
+      "status": "completed",
       "blockedBy": [
         "B3.2"
       ]

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriver.cs

@@ -133,10 +133,29 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
         _poll = new PollGroupEngine(
             reader: ReadAsync,
             onChange: (handle, tagRef, snapshot) =>
-                OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)));
+                OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)),
+            onError: HandlePollError,
+            backoffCap: PollBackoffCap);
         _alarmProjection = new AbCipAlarmProjection(this, _options.AlarmPollInterval, _logger);
     }
 
+    /// <summary>Upper bound on the poll-loop failure backoff — adopts the S7-proven 30 s cap fleet-wide (05/STAB-8).</summary>
+    private static readonly TimeSpan PollBackoffCap = TimeSpan.FromSeconds(30);
+
+    /// <summary>
+    ///     05/STAB-9 — routes a poll-loop reader failure to the driver health surface: logs it and
+    ///     degrades to <see cref="DriverState.Degraded"/> preserving <c>LastSuccessfulRead</c>.
+    ///     Never downgrades a <see cref="DriverState.Faulted"/> state (a stronger, config-level signal).
+    /// </summary>
+    /// <param name="ex">The exception caught by the poll engine.</param>
+    internal void HandlePollError(Exception ex)
+    {
+        _logger.LogWarning(ex, "AbCip poll reader failed. Driver={DriverInstanceId}", _driverInstanceId);
+        var current = _health;
+        if (current.State != DriverState.Faulted)
+            _health = new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message);
+    }
+
     /// <summary>
     ///     Fetch + cache the shape of a Logix UDT by template instance id. First call reads
     ///     the Template Object off the controller; subsequent calls for the same

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs

@@ -65,7 +65,26 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         _poll = new PollGroupEngine(
             reader: ReadAsync,
             onChange: (handle, tagRef, snapshot) =>
-                OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)));
+                OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)),
+            onError: HandlePollError,
+            backoffCap: PollBackoffCap);
+    }
+
+    /// <summary>Upper bound on the poll-loop failure backoff — adopts the S7-proven 30 s cap fleet-wide (05/STAB-8).</summary>
+    private static readonly TimeSpan PollBackoffCap = TimeSpan.FromSeconds(30);
+
+    /// <summary>
+    ///     05/STAB-9 — routes a poll-loop reader failure to the driver health surface: logs it and
+    ///     degrades to <see cref="DriverState.Degraded"/> preserving <c>LastSuccessfulRead</c>.
+    ///     Never downgrades a <see cref="DriverState.Faulted"/> state (a stronger, config-level signal).
+    /// </summary>
+    /// <param name="ex">The exception caught by the poll engine.</param>
+    internal void HandlePollError(Exception ex)
+    {
+        _logger.LogWarning(ex, "AbLegacy poll reader failed. Driver={DriverInstanceId}", _driverInstanceId);
+        var current = _health;
+        if (current.State != DriverState.Faulted)
+            _health = new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message);
     }
 
     /// <inheritdoc />

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriver.cs

@@ -118,7 +118,26 @@ public sealed class ModbusDriver
             {
                 if (!ShouldPublish(tagRef, snapshot)) return;
                 OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot));
-            });
+            },
+            onError: HandlePollError,
+            backoffCap: PollBackoffCap);
+    }
+
+    /// <summary>Upper bound on the poll-loop failure backoff — adopts the S7-proven 30 s cap fleet-wide (05/STAB-8).</summary>
+    private static readonly TimeSpan PollBackoffCap = TimeSpan.FromSeconds(30);
+
+    /// <summary>
+    ///     05/STAB-9 — routes a poll-loop reader failure to the driver health surface: logs it and
+    ///     degrades to <see cref="DriverState.Degraded"/> preserving <c>LastSuccessfulRead</c>.
+    ///     Never downgrades a <see cref="DriverState.Faulted"/> state (a stronger, config-level signal).
+    /// </summary>
+    /// <param name="ex">The exception caught by the poll engine.</param>
+    internal void HandlePollError(Exception ex)
+    {
+        _logger.LogWarning(ex, "Modbus poll reader failed. Driver={DriverInstanceId}", _driverInstanceId);
+        var current = ReadHealth();
+        if (current.State != DriverState.Faulted)
+            WriteHealth(new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message));
     }
 
     /// <inheritdoc />

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests/AbCipPollErrorHealthTests.cs

@@ -0,0 +1,59 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests;
+
+/// <summary>
+///     05/STAB-9 — the poll engine's <c>onError</c> sink must be wired to the driver health
+///     surface: a poll-loop reader failure degrades health while preserving
+///     <see cref="DriverHealth.LastSuccessfulRead"/>, and must never downgrade a pre-existing
+///     <see cref="DriverState.Faulted"/>.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class AbCipPollErrorHealthTests
+{
+    /// <summary>A poll reader failure degrades health, preserving the last successful read timestamp.</summary>
+    [Fact]
+    public async Task PollReaderFailure_DegradesHealth_PreservesLastSuccessfulRead()
+    {
+        var opts = new AbCipDriverOptions
+        {
+            Devices = [new AbCipDeviceOptions("ab://10.0.0.5/1,0")],
+            Probe = new AbCipProbeOptions { Enabled = false },
+        };
+        var drv = new AbCipDriver(opts, "abcip-1", new FakeAbCipTagFactory());
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        var before = drv.GetHealth();
+        before.State.ShouldBe(DriverState.Healthy);
+        before.LastSuccessfulRead.ShouldNotBeNull();
+
+        drv.HandlePollError(new InvalidOperationException("poll boom"));
+
+        var after = drv.GetHealth();
+        after.State.ShouldBe(DriverState.Degraded);
+        after.LastSuccessfulRead.ShouldBe(before.LastSuccessfulRead);
+        after.LastError.ShouldContain("poll boom");
+    }
+
+    /// <summary>A poll reader failure never downgrades a pre-existing Faulted state.</summary>
+    [Fact]
+    public async Task PollReaderFailure_NeverDowngradesFaulted()
+    {
+        var opts = new AbCipDriverOptions
+        {
+            Devices = [new AbCipDeviceOptions("not-a-valid-address")],
+            Probe = new AbCipProbeOptions { Enabled = false },
+        };
+        var drv = new AbCipDriver(opts, "abcip-1", new FakeAbCipTagFactory());
+
+        await Should.ThrowAsync<Exception>(() => drv.InitializeAsync("{}", CancellationToken.None));
+        drv.GetHealth().State.ShouldBe(DriverState.Faulted);
+
+        drv.HandlePollError(new InvalidOperationException("poll boom"));
+
+        drv.GetHealth().State.ShouldBe(DriverState.Faulted);
+    }
+}

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/AbLegacyPollErrorHealthTests.cs

@@ -0,0 +1,59 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests;
+
+/// <summary>
+///     05/STAB-9 — the poll engine's <c>onError</c> sink must be wired to the driver health
+///     surface: a poll-loop reader failure degrades health while preserving
+///     <see cref="DriverHealth.LastSuccessfulRead"/>, and must never downgrade a pre-existing
+///     <see cref="DriverState.Faulted"/>.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class AbLegacyPollErrorHealthTests
+{
+    /// <summary>A poll reader failure degrades health, preserving the last successful read timestamp.</summary>
+    [Fact]
+    public async Task PollReaderFailure_DegradesHealth_PreservesLastSuccessfulRead()
+    {
+        var opts = new AbLegacyDriverOptions
+        {
+            Devices = [new AbLegacyDeviceOptions("ab://10.0.0.5/1,0")],
+            Probe = new AbLegacyProbeOptions { Enabled = false },
+        };
+        var drv = new AbLegacyDriver(opts, "ablegacy-1", new FakeAbLegacyTagFactory());
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        var before = drv.GetHealth();
+        before.State.ShouldBe(DriverState.Healthy);
+        before.LastSuccessfulRead.ShouldNotBeNull();
+
+        drv.HandlePollError(new InvalidOperationException("poll boom"));
+
+        var after = drv.GetHealth();
+        after.State.ShouldBe(DriverState.Degraded);
+        after.LastSuccessfulRead.ShouldBe(before.LastSuccessfulRead);
+        after.LastError.ShouldContain("poll boom");
+    }
+
+    /// <summary>A poll reader failure never downgrades a pre-existing Faulted state.</summary>
+    [Fact]
+    public async Task PollReaderFailure_NeverDowngradesFaulted()
+    {
+        var opts = new AbLegacyDriverOptions
+        {
+            Devices = [new AbLegacyDeviceOptions("not-a-valid-address")],
+            Probe = new AbLegacyProbeOptions { Enabled = false },
+        };
+        var drv = new AbLegacyDriver(opts, "ablegacy-1", new FakeAbLegacyTagFactory());
+
+        await Should.ThrowAsync<Exception>(() => drv.InitializeAsync("{}", CancellationToken.None));
+        drv.GetHealth().State.ShouldBe(DriverState.Faulted);
+
+        drv.HandlePollError(new InvalidOperationException("poll boom"));
+
+        drv.GetHealth().State.ShouldBe(DriverState.Faulted);
+    }
+}

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusPollErrorHealthTests.cs

@@ -0,0 +1,60 @@
+using System.Net.Sockets;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
+
+/// <summary>
+///     05/STAB-9 — the poll engine's <c>onError</c> sink must be wired to the driver health
+///     surface: a poll-loop reader failure degrades health while preserving
+///     <see cref="DriverHealth.LastSuccessfulRead"/>, and must never downgrade a pre-existing
+///     <see cref="DriverState.Faulted"/> (the S7 nuance ported fleet-wide).
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class ModbusPollErrorHealthTests
+{
+    private sealed class NoopTransport : IModbusTransport
+    {
+        public Task ConnectAsync(CancellationToken ct) => Task.CompletedTask;
+        public Task<byte[]> SendAsync(byte unitId, byte[] pdu, CancellationToken ct)
+            => Task.FromResult(new byte[] { 0x03, 0x00 });
+        public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+    }
+
+    /// <summary>A poll reader failure degrades health, preserving the last successful read timestamp.</summary>
+    [Fact]
+    public async Task PollReaderFailure_DegradesHealth_PreservesLastSuccessfulRead()
+    {
+        var opts = new ModbusDriverOptions { Host = "fake", Probe = new ModbusProbeOptions { Enabled = false } };
+        var drv = new ModbusDriver(opts, "modbus-1", _ => new NoopTransport());
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        var before = drv.GetHealth();
+        before.State.ShouldBe(DriverState.Healthy);
+        before.LastSuccessfulRead.ShouldNotBeNull();
+
+        drv.HandlePollError(new InvalidOperationException("poll boom"));
+
+        var after = drv.GetHealth();
+        after.State.ShouldBe(DriverState.Degraded);
+        after.LastSuccessfulRead.ShouldBe(before.LastSuccessfulRead);
+        after.LastError.ShouldContain("poll boom");
+    }
+
+    /// <summary>A poll reader failure never downgrades a pre-existing Faulted state.</summary>
+    [Fact]
+    public async Task PollReaderFailure_NeverDowngradesFaulted()
+    {
+        var opts = new ModbusDriverOptions { Host = "fake", Probe = new ModbusProbeOptions { Enabled = false } };
+        var drv = new ModbusDriver(opts, "modbus-1", _ => throw new SocketException());
+
+        // Init faults (the throwing factory) → Faulted, then rethrows.
+        await Should.ThrowAsync<Exception>(() => drv.InitializeAsync("{}", CancellationToken.None));
+        drv.GetHealth().State.ShouldBe(DriverState.Faulted);
+
+        drv.HandlePollError(new InvalidOperationException("poll boom"));
+
+        drv.GetHealth().State.ShouldBe(DriverState.Faulted);
+    }
+}