dohertj2/lmxopcua
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Joseph Doherty
2026-07-13 11:59:49 -04:00
parent 9213c037b0
commit b494d09d9b
5 changed files with 161 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
archreview/plans/R2-09-driver-fleet-batch-plan.md.tasks.json
+1 -1
View File
@@ -87,7 +87,7 @@
{
"id": "B3.4",
"subject": "B3: wire onError->health + 30s backoffCap into TwinCAT/FOCAS engine ctors (tests first per driver) \u2014 STAB-9",
"status": "pending",
"status": "completed",
"blockedBy": [
"B3.2"
]
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs
+21 -1
View File
@@ -72,7 +72,27 @@ public sealed class FocasDriver : 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);
}
/// <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, "FOCAS poll reader failed. Driver={DriverInstanceId}", _driverInstanceId);
var current = Volatile.Read(ref _health);
if (current.State != DriverState.Faulted)
Volatile.Write(ref _health,
new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message));
}
/// <inheritdoc />
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs
+20 -1
View File
@@ -69,7 +69,26 @@ public sealed class TwinCATDriver : 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);
}
/// <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, "TwinCAT poll reader failed. Driver={DriverInstanceId}", _driverInstanceId);
var current = _health;
if (current.State != DriverState.Faulted)
_health = new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message);
}
/// <inheritdoc />
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasPollErrorHealthTests.cs
+58
View File
@@ -0,0 +1,58 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.FOCAS;
namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.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 FocasPollErrorHealthTests
{
/// <summary>A poll reader failure degrades health, preserving the last successful read timestamp.</summary>
[Fact]
public async Task PollReaderFailure_DegradesHealth_PreservesLastSuccessfulRead()
{
var drv = new FocasDriver(new FocasDriverOptions
{
Devices = [new FocasDeviceOptions("focas://10.0.0.5:8193")],
Probe = new FocasProbeOptions { Enabled = false },
}, "focas-1", new FakeFocasClientFactory());
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 drv = new FocasDriver(new FocasDriverOptions
{
Devices = [new FocasDeviceOptions("focas://10.0.0.5:8193")],
Tags = [new FocasTagDefinition("X", "focas://10.0.0.5:9999", "R100", FocasDataType.Byte)],
Probe = new FocasProbeOptions { Enabled = false },
}, "focas-1", new FakeFocasClientFactory());
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.TwinCAT.Tests/TwinCATPollErrorHealthTests.cs
+61
View File
@@ -0,0 +1,61 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.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 TwinCATPollErrorHealthTests
{
private const string Host = "ads://5.23.91.23.1.1:851";
/// <summary>A poll reader failure degrades health, preserving the last successful read timestamp.</summary>
[Fact]
public async Task PollReaderFailure_DegradesHealth_PreservesLastSuccessfulRead()
{
var drv = new TwinCATDriver(new TwinCATDriverOptions
{
Devices = [new TwinCATDeviceOptions(Host)],
Probe = new TwinCATProbeOptions { Enabled = false },
EnableControllerBrowse = false,
}, "twincat-1", new FakeTwinCATClientFactory());
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 drv = new TwinCATDriver(new TwinCATDriverOptions
{
Devices = [new TwinCATDeviceOptions("not-a-valid-address")],
Probe = new TwinCATProbeOptions { Enabled = false },
EnableControllerBrowse = false,
}, "twincat-1", new FakeTwinCATClientFactory());
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);
}
}