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

fix(ab): a refused operation is BadNotSupported, not a comms fault (Task 22 review r1; closes #571)

Browse Source 
Native is the default, so a locally refused write must not look like a comms fault.

- AbLegacy: an AbTransportException with AbStatus.Unsupported (status-bit sub-element writes, PLC-5
  non-N reads, all PLC-5 writes; libplctag's ErrorUnsupported maps here too) now returns
  BadNotSupported on both the read and the write path (incl. the bit-RMW path). The tag handle is
  not evicted and driver health is not touched. A native runtime whose init read is refused locally
  is CACHED rather than disposed, so a poll of a refused tag does not re-create (and re-lease the
  pooled connection) every cycle.
- AbCip: the same mapping on the write path and both read paths (single + whole-UDT).
- Uses the existing named BadNotSupported constants (StatusCodeParityTests guard).
- Tests (falsified by disabling the mapping, and separately the keep-on-refusal): status-bit
  writes and PLC-5 read/write through the driver over the native runtime — BadNotSupported, zero
  wire requests, one create, health unchanged; AbCip refused read/write via a refusing fake plus a
  control that a non-refusal failure still evicts and degrades.
- Docs/CLAUDE.md: BadNotSupported; #571 known-gap wording removed.

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
This commit is contained in:
Joseph Doherty
2026-10-07 21:12:08 -04:00
parent 1806af54f0
commit 39ae286cd7
7 changed files with 279 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests/AbCipLocalRefusalTests.cs
+107
View File
@@ -0,0 +1,107 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.Ab.Transport;
namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests;
/// <summary>
/// Task 22 review r1: a runtime that refuses an operation with <see cref="AbStatus.Unsupported"/> (the native
/// transport does this before the wire, e.g. a write it cannot type) reaches the client as BadNotSupported —
/// NOT as a comms fault. The handle is kept (one create, never disposed) and driver health is untouched.
/// </summary>
[Trait("Category", "Unit")]
public sealed class AbCipLocalRefusalTests
{
private const string Host = "ab://10.0.0.5/1,0";
private sealed class RefusingTag(AbCipTagCreateParams p, bool refuseRead, bool refuseWrite) : FakeAbCipTag(p)
{
public override Task ReadAsync(CancellationToken cancellationToken) =>
refuseRead
? Task.FromException(new AbTransportException(AbStatus.Unsupported, "refused read"))
: base.ReadAsync(cancellationToken);
public override Task WriteAsync(CancellationToken cancellationToken) =>
refuseWrite
? Task.FromException(new AbTransportException(AbStatus.Unsupported, "refused write"))
: base.WriteAsync(cancellationToken);
}
private static async Task<(AbCipDriver Driver, FakeAbCipTagFactory Factory, Func<int> Creates)> NewAsync(
bool refuseRead, bool refuseWrite, AbCipDataType type = AbCipDataType.DInt)
{
var creates = 0;
var factory = new FakeAbCipTagFactory
{
Customise = p => { Interlocked.Increment(ref creates); return new RefusingTag(p, refuseRead, refuseWrite) { Value = 1 }; },
};
var drv = new AbCipDriver(new AbCipDriverOptions
{
Devices = [new AbCipDeviceOptions(Host)],
RawTags = AbCipRawTags.From(new AbCipTagDefinition("T", Host, "T", type)),
Probe = new AbCipProbeOptions { Enabled = false },
}, "drv-1", factory);
await drv.InitializeAsync("{}", CancellationToken.None);
return (drv, factory, () => Volatile.Read(ref creates));
}
#pragma warning disable OTOPCUA0001 // the driver's own status mapping is under test, not resilience wrapping
[Fact]
public async Task A_refused_write_is_BadNotSupported_keeps_the_handle_and_leaves_health_alone()
{
var (drv, factory, creates) = await NewAsync(refuseRead: false, refuseWrite: true);
(await drv.ReadAsync(["T"], CancellationToken.None)).Single().StatusCode.ShouldBe(AbCipStatusMapper.Good);
var health = drv.GetHealth();
(await drv.WriteAsync([new WriteRequest("T", 5)], CancellationToken.None)).Single().StatusCode
.ShouldBe(AbCipStatusMapper.BadNotSupported);
drv.GetHealth().ShouldBe(health);
factory.Tags["T"].Disposed.ShouldBeFalse();
(await drv.ReadAsync(["T"], CancellationToken.None)).Single().StatusCode.ShouldBe(AbCipStatusMapper.Good);
creates().ShouldBe(1);
}
[Fact]
public async Task A_refused_read_is_BadNotSupported_keeps_the_handle_and_leaves_health_alone()
{
var (drv, factory, creates) = await NewAsync(refuseRead: true, refuseWrite: false);
var health = drv.GetHealth();
for (var n = 0; n < 2; n++)
(await drv.ReadAsync(["T"], CancellationToken.None)).Single().StatusCode
.ShouldBe(AbCipStatusMapper.BadNotSupported);
drv.GetHealth().ShouldBe(health);
factory.Tags["T"].Disposed.ShouldBeFalse();
creates().ShouldBe(1);
}
/// <summary>Control: any OTHER transport failure is still a comms fault (evicted, Degraded).</summary>
[Fact]
public async Task A_non_refusal_write_failure_still_evicts_and_degrades()
{
var factory = new FakeAbCipTagFactory();
factory.Customise = p => new ThrowingWriteTag(p) { Value = 1 };
var drv = new AbCipDriver(new AbCipDriverOptions
{
Devices = [new AbCipDeviceOptions(Host)],
RawTags = AbCipRawTags.From(new AbCipTagDefinition("T", Host, "T", AbCipDataType.DInt)),
Probe = new AbCipProbeOptions { Enabled = false },
}, "drv-1", factory);
await drv.InitializeAsync("{}", CancellationToken.None);
(await drv.WriteAsync([new WriteRequest("T", 5)], CancellationToken.None)).Single().StatusCode
.ShouldBe(AbCipStatusMapper.BadCommunicationError);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
factory.Tags["T"].Disposed.ShouldBeTrue();
}
#pragma warning restore OTOPCUA0001
private sealed class ThrowingWriteTag(AbCipTagCreateParams p) : FakeAbCipTag(p)
{
public override Task WriteAsync(CancellationToken cancellationToken) =>
Task.FromException(new AbTransportException(AbStatus.BadConnection, "socket closed"));
}
}
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/NativeAbLegacyTagRuntimeTests.cs
+93 -33
View File
@@ -382,61 +382,121 @@ public sealed class NativeAbLegacyTagRuntimeTests
h.Channel.SentCount.ShouldBe(0);
}
// These two tests call the driver's WriteAsync directly to pin its OWN status mapping; resilience wrapping
// (CapabilityInvoker) is out of scope and would retry/mask the very status under test.
// These tests call the driver's WriteAsync/ReadAsync directly to pin its OWN status mapping; resilience
// wrapping (CapabilityInvoker) is out of scope and would retry/mask the very status under test.
#pragma warning disable OTOPCUA0001
/// <summary>Native runtimes over the harness channel; counts creates so a test can prove a handle was KEPT.</summary>
private sealed class HarnessFactory(Harness h) : IAbLegacyTagFactory
{
public IAbLegacyTagRuntime Create(AbLegacyTagCreateParams p) =>
new NativeAbLegacyTagRuntime(p, h.Scheduler, Vendor, Serial);
public int Creates;
public IAbLegacyTagRuntime Create(AbLegacyTagCreateParams p)
{
Interlocked.Increment(ref Creates);
return new NativeAbLegacyTagRuntime(p, h.Scheduler, Vendor, Serial);
}
}
private const string Host = "ab://10.0.0.1:44818/1,0";
private static async Task<AbLegacyDriver> DriverAsync(
HarnessFactory factory, AbLegacyPlcFamily family, AbLegacyTagDefinition tag)
{
var driver = new AbLegacyDriver(new AbLegacyDriverOptions
{
Devices = [new AbLegacyDeviceOptions(Host, family)],
RawTags = AbLegacyRawTags.Entries([tag]),
Probe = new AbLegacyProbeOptions { Enabled = false },
}, "drv-sb", factory);
await driver.InitializeAsync("{}", CancellationToken.None);
return driver;
}
/// <summary>
/// Pins the CLIENT-VISIBLE status of the native status-bit write refusal, through the driver (Task 22
/// review r1 I2 — the release note states it). The runtime throws AbTransportException(Unsupported);
/// the driver's write path does not special-case it, so the client sees the generic transport
/// status, and nothing reaches the wire.
/// Task 22 review r1 / #571: a native status-bit sub-element write is refused locally and reaches the
/// client as BadNotSupported — NOT a comms fault: nothing on the wire, the tag handle is kept (no
/// re-create), and driver health is untouched. The tag is read first so its handle exists and the
/// wire count isolates the write.
/// </summary>
[Theory]
[InlineData("T4:0.DN")]
[InlineData("C5:0.CU")]
[InlineData("R6:0.EN")]
public async Task A_status_bit_write_through_the_driver_reports_the_documented_status(string address)
public async Task A_status_bit_write_is_BadNotSupported_without_wire_eviction_or_degraded_health(string address)
{
await using var h = new Harness("slc500", "N7:0").Replies(Words(0));
const string host = "ab://10.0.0.1:44818/1,0";
var driver = new AbLegacyDriver(new AbLegacyDriverOptions
{
Devices = [new AbLegacyDeviceOptions(host, AbLegacyPlcFamily.Slc500)],
RawTags = AbLegacyRawTags.Entries([new AbLegacyTagDefinition("Bit", host, address, AbLegacyDataType.Bit)]),
Probe = new AbLegacyProbeOptions { Enabled = false },
}, "drv-sb", new HarnessFactory(h));
await driver.InitializeAsync("{}", CancellationToken.None);
var factory = new HarnessFactory(h);
var driver = await DriverAsync(factory, AbLegacyPlcFamily.Slc500,
new AbLegacyTagDefinition("Bit", Host, address, AbLegacyDataType.Bit));
(await driver.ReadAsync(["Bit"], CancellationToken.None)).Single().StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
var health = driver.GetHealth();
var sent = h.Channel.SentCount;
var results = await driver.WriteAsync([new WriteRequest("Bit", true)], CancellationToken.None);
// BadCommunicationError, NOT BadNotSupported: the driver's catch-all maps any runtime exception to
// it (same as the PLC-5 write refusal, #571), evicts the handle and marks health Degraded.
results.Single().StatusCode.ShouldBe(AbLegacyStatusMapper.BadCommunicationError);
driver.GetHealth().LastError.ShouldNotBeNull().ShouldContain("status-bit sub-element");
// Refused before the wire: the lazy runtime's init read may go out, but never a write (fnc 0xAA).
lock (h.Channel.Sent) h.Channel.Sent.ShouldNotContain(r => FncOf(r) == 0xAA);
results.Single().StatusCode.ShouldBe(AbLegacyStatusMapper.BadNotSupported);
h.Channel.SentCount.ShouldBe(sent); // zero wire requests for the refused write
driver.GetHealth().ShouldBe(health); // health unchanged (not Degraded)
(await driver.ReadAsync(["Bit"], CancellationToken.None)).Single().StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
factory.Creates.ShouldBe(1); // handle kept: the read after reused it
await driver.ShutdownAsync(CancellationToken.None);
}
/// <summary>Positive control for the "no 0xAA on the wire" assertion above: the same driver path for a WORD
/// sub-element does send a typed write, so the detector can see one.</summary>
/// <summary>
/// #571, read side: a native PLC-5 non-N read is refused locally — BadNotSupported, nothing on the wire,
/// health unchanged, and the refused handle is KEPT (one create across repeated reads, so a poll does
/// not re-lease the device connection every cycle).
/// </summary>
[Fact]
public async Task A_PLC5_non_N_read_is_BadNotSupported_without_wire_eviction_or_degraded_health()
{
await using var h = new Harness("plc5", "N7:0").Replies(Words(0));
var factory = new HarnessFactory(h);
var driver = await DriverAsync(factory, AbLegacyPlcFamily.Plc5,
new AbLegacyTagDefinition("F", Host, "F8:0", AbLegacyDataType.Float));
var health = driver.GetHealth();
for (var n = 0; n < 3; n++)
(await driver.ReadAsync(["F"], CancellationToken.None)).Single().StatusCode
.ShouldBe(AbLegacyStatusMapper.BadNotSupported);
h.Channel.SentCount.ShouldBe(0);
driver.GetHealth().ShouldBe(health);
factory.Creates.ShouldBe(1);
await driver.ShutdownAsync(CancellationToken.None);
}
/// <summary>#571, write side: a native PLC-5 write is refused locally — BadNotSupported, no write on the wire,
/// handle kept, health unchanged.</summary>
[Fact]
public async Task A_PLC5_write_is_BadNotSupported_without_wire_eviction_or_degraded_health()
{
await using var h = new Harness("plc5", "N7:0").Replies(Words(0));
var factory = new HarnessFactory(h);
var driver = await DriverAsync(factory, AbLegacyPlcFamily.Plc5,
new AbLegacyTagDefinition("N", Host, "N7:0", AbLegacyDataType.Int));
(await driver.ReadAsync(["N"], CancellationToken.None)).Single().StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
var health = driver.GetHealth();
var sent = h.Channel.SentCount;
(await driver.WriteAsync([new WriteRequest("N", (short)5)], CancellationToken.None)).Single().StatusCode
.ShouldBe(AbLegacyStatusMapper.BadNotSupported);
h.Channel.SentCount.ShouldBe(sent);
driver.GetHealth().ShouldBe(health);
(await driver.ReadAsync(["N"], CancellationToken.None)).Single().StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
factory.Creates.ShouldBe(1);
await driver.ShutdownAsync(CancellationToken.None);
}
/// <summary>Positive control for the wire-count assertions above: the same driver path for a WORD sub-element
/// does send a typed write (fnc 0xAA), so the harness can see one.</summary>
[Fact]
public async Task A_word_sub_element_write_through_the_driver_sends_a_typed_write()
{
await using var h = new Harness("slc500", "N7:0").Replies(Words(0));
const string host = "ab://10.0.0.1:44818/1,0";
var driver = new AbLegacyDriver(new AbLegacyDriverOptions
{
Devices = [new AbLegacyDeviceOptions(host, AbLegacyPlcFamily.Slc500)],
RawTags = AbLegacyRawTags.Entries([new AbLegacyTagDefinition("Pre", host, "T4:0.PRE", AbLegacyDataType.Int)]),
Probe = new AbLegacyProbeOptions { Enabled = false },
}, "drv-sb", new HarnessFactory(h));
await driver.InitializeAsync("{}", CancellationToken.None);
var driver = await DriverAsync(new HarnessFactory(h), AbLegacyPlcFamily.Slc500,
new AbLegacyTagDefinition("Pre", Host, "T4:0.PRE", AbLegacyDataType.Int));
var results = await driver.WriteAsync([new WriteRequest("Pre", (short)5)], CancellationToken.None);