fix(s7): a CPU refusal is per-tag Bad and counts as answered (R07:H4)

A deterministic PLC refusal (object does not exist, address out of range,
type inconsistent...) degraded driver health, and an all-refused driver (a
wrong DB number) sat Degraded with LastSuccessfulRead frozen, so the 90 s
comms-loss watchdog reconnected it forever against a reachable PLC.

- IsRefusal / IsAccessDenied classify over the whole exception chain. Live
  probe on the snap7 fixture: S7.Net's READ paths raise the item error as a
  BARE Exception ("Received error from PLC: ..."), its write paths as
  PlcException(WriteData). The old PlcException-only match missed the read
  shape entirely, so a real read access-denied was BadCommunicationError +
  Degraded instead of the Faulted PUT/GET alert; the Test Connect probe had
  the same blind spot.
- A refusal (read or write) is BadDeviceFailure with a once-per-tag Warning,
  no health write and no reopen; it counts as answered, so it advances
  LastSuccessfulRead and restores Healthy after a comms fault. An undecodable
  buffer (S7ValueRangeException) also counts as answered.
- A write batch the CPU answered without a failure advances
  LastSuccessfulRead and retires a Degraded the write side itself published.
- Tests that used ReadData as their generic "device fault" now use SendData
  so their Degraded leg is still exercised.

Refs #742
Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
This commit is contained in:
Joseph Doherty
2026-10-22 15:20:51 -04:00
parent ecf1e86464
commit a1f20e78f9
8 changed files with 515 additions and 49 deletions
@@ -208,6 +208,19 @@ public sealed class S7Driver
/// Guarded by <see cref="_gate"/>.
/// </summary>
private (DriverState State, string Message)? _writeFault;
/// <summary>
/// The message of the last Degraded the WRITE side published, or null. A clean write batch
/// retires a Degraded carrying exactly this message (a good write proves the comms fault it
/// reported is gone) and leaves any other Degraded to the read pass. Guarded by <see cref="_gate"/>.
/// </summary>
private string? _writeOwnedError;
/// <summary>
/// Tags whose refusal has already been logged this generation — the once-per-tag Warning. Cleared
/// by every initialize publish.
/// </summary>
private readonly ConcurrentDictionary<string, byte> _refusalWarned = new(StringComparer.Ordinal);
private bool _disposed;
/// <inheritdoc />
@@ -797,7 +810,7 @@ public sealed class S7Driver
}
catch (Exception ex)
{
results[i] = new DataValueSnapshot(null, RecordReadFailure(ex, outcome), null, now);
results[i] = new DataValueSnapshot(null, RecordReadFailure(ex, outcome, [resolved[i]!.Name]), null, now);
}
}
}
@@ -903,6 +916,13 @@ public sealed class S7Driver
/// <summary>Records that one tag read successfully.</summary>
public void RecordSuccess() => AnySuccess = true;
/// <summary>
/// Records that the CPU answered for one tag without serving it (a refusal, an undecodable
/// buffer). Not a failure — it ranks nothing — but it IS proof of a live device, so it
/// advances <c>LastSuccessfulRead</c> exactly like a success.
/// </summary>
public void RecordAnswered() => AnySuccess = true;
/// <summary>
/// Records one failed tag, keeping the worst state and the message that explains it.
/// </summary>
@@ -1098,7 +1118,7 @@ public sealed class S7Driver
{
// Decoding is pure and synchronous — no cancellation can surface here, so there
// is deliberately no OperationCanceledException arm to shadow the request one.
results[index] = new DataValueSnapshot(null, RecordReadFailure(ex, outcome), null, now);
results[index] = new DataValueSnapshot(null, RecordReadFailure(ex, outcome, [tag.Name]), null, now);
}
}
}
@@ -1195,7 +1215,7 @@ public sealed class S7Driver
}
catch (Exception ex)
{
var status = RecordReadFailure(ex, outcome);
var status = RecordReadFailure(ex, outcome, span.Members.Select(m => m.Tag.Name));
foreach (var member in span.Members)
results[member.OriginalIndex] = new DataValueSnapshot(null, status, null, now);
return;
@@ -1214,7 +1234,7 @@ public sealed class S7Driver
// Decoding is pure and synchronous — no cancellation can surface here, so there is
// deliberately no OperationCanceledException arm to shadow the block-read one above.
results[member.OriginalIndex] =
new DataValueSnapshot(null, RecordReadFailure(ex, outcome), null, now);
new DataValueSnapshot(null, RecordReadFailure(ex, outcome, [member.Tag.Name]), null, now);
}
}
}
@@ -1289,8 +1309,10 @@ public sealed class S7Driver
/// </remarks>
/// <param name="ex">The exception observed on a read.</param>
/// <param name="outcome">The pass's outcome accumulator this failure is recorded into.</param>
/// <param name="tagNames">The tags the failure belongs to (every member of a failed span), for the
/// once-per-tag refusal Warning.</param>
/// <returns>The OPC UA status code every affected tag must be stamped with.</returns>
private uint RecordReadFailure(Exception ex, ReadPassOutcome outcome)
private uint RecordReadFailure(Exception ex, ReadPassOutcome outcome, IEnumerable<string> tagNames)
{
switch (ex)
{
@@ -1299,19 +1321,33 @@ public sealed class S7Driver
case S7ValueRangeException:
// A PLC buffer the type codec refuses (uninitialised DTL, non-BCD S5TIME…) is a data
// problem, not a transport fault — no health change, no connection teardown.
// problem, not a transport fault — no health change, no connection teardown. The
// bytes came off the wire, so the CPU answered.
outcome.RecordAnswered();
return StatusBadOutOfRange;
case PlcException pex when IsAccessDenied(pex):
case var _ when IsAccessDenied(ex):
// PUT/GET-disabled (S7-1200/1500) / access-protection — a permanent configuration
// fault, NOT a transient one. Blind retry is wasted effort, so map it to
// BadNotSupported and flag the driver as a config alert (Faulted) rather than
// Degraded — per driver-specs.md §5.
// Degraded — per driver-specs.md §5. Matched over the whole chain: S7.Net's READ
// paths raise the CPU's item error as a bare Exception, not a PlcException.
outcome.RecordFailure(DriverState.Faulted,
"S7 access denied — enable PUT/GET communication in TIA Portal " +
$"(Protection & Security) for this CPU. PLC reported: {pex.Message}");
$"(Protection & Security) for this CPU. PLC reported: {ex.Message}");
return StatusBadNotSupported;
case var _ when IsRefusal(ex):
// The CPU answered and refused the item (object does not exist, address out of
// range, type inconsistent...) — deterministic, so a retry, a reopen or a Degraded
// would all be wrong: per-tag Bad, a once-per-tag Warning, no health write, and it
// counts as answered so LastSuccessfulRead advances (R07:H4). An all-refused driver
// (wrong DB number) used to sit Degraded with a frozen timestamp and trip the
// comms-loss watchdog every 90 s against a reachable PLC.
outcome.RecordAnswered();
foreach (var name in tagNames) WarnRefusalOnce(name, "read", ex);
return StatusBadDeviceFailure;
case PlcException pex:
// A genuine device-layer fault (CPU error, hardware fault) — transient enough to
// keep retrying; report BadDeviceFailure and degrade health. A connection-fatal
@@ -1969,7 +2005,7 @@ public sealed class S7Driver
// Client-supplied value of the wrong shape — not a device or comms fault.
results[i] = new WriteResult(StatusBadTypeMismatch);
}
catch (PlcException pex) when (IsAccessDenied(pex))
catch (Exception ex) when (IsAccessDenied(ex))
{
// PUT/GET-disabled / access-protection on write — same permanent
// configuration fault as on read. BadNotSupported +
@@ -1977,7 +2013,15 @@ public sealed class S7Driver
results[i] = new WriteResult(StatusBadNotSupported);
outcome.RecordFailure(DriverState.Faulted,
"S7 access denied — enable PUT/GET communication in TIA Portal " +
$"(Protection & Security) for this CPU. PLC reported: {pex.Message}");
$"(Protection & Security) for this CPU. PLC reported: {ex.Message}");
}
catch (Exception ex) when (IsRefusal(ex))
{
// The CPU answered and refused the item — per-tag Bad, once-per-tag Warning, no
// Degraded, and it counts as answered (R07:H4).
results[i] = new WriteResult(StatusBadDeviceFailure);
outcome.RecordAnswered();
WarnRefusalOnce(tag.Name, "write", ex);
}
catch (PlcException pex)
{
@@ -2029,16 +2073,24 @@ public sealed class S7Driver
else if (outcome.AnySuccess)
_writeFault = null; // a write got through — the protection fault is gone
var answeredAt = outcome.AnyAnswered ? DateTime.UtcNow : (DateTime?)null;
if (worst == DriverState.Healthy)
{
// Success-only batch: no health write, except to retire a Faulted that WE (the write
// side) were holding — a clean write is the only evidence the alert has cleared.
// Only a Faulted the write side owns: a read-side Faulted (e.g. access denied on another DB) is the
// read pass's to clear, and Health still carries the write fault's own message iff it is ours.
if (outcome.AnySuccess && _writeFault is null && priorWriteFault is { } owned)
TryUpdateHealth(gen, h => h.State == DriverState.Faulted && h.LastError == owned.Message
? new DriverHealth(DriverState.Healthy, h.LastSuccessfulRead, null)
: null);
// Clean batch (successes and/or refusals): the CPU answered, so LastSuccessfulRead
// advances, and a non-Healthy state the WRITE side owns is retired — a Faulted only by a
// real success (a refusal does not prove PUT/GET is enabled), a write-side comms Degraded
// by any answer. A state the read side owns (its own message) is the read pass's to clear.
var ownedFault = outcome.AnySuccess && _writeFault is null ? priorWriteFault?.Message : null;
var ownedDegraded = _writeOwnedError;
_writeOwnedError = null;
TryUpdateHealth(gen, h =>
{
var lsr = answeredAt ?? h.LastSuccessfulRead;
if ((h.State == DriverState.Faulted && ownedFault is not null && h.LastError == ownedFault)
|| (h.State == DriverState.Degraded && ownedDegraded is not null && h.LastError == ownedDegraded))
return new DriverHealth(DriverState.Healthy, lsr, null);
return lsr == h.LastSuccessfulRead ? null : h with { LastSuccessfulRead = lsr };
});
return;
}
@@ -2050,7 +2102,8 @@ public sealed class S7Driver
state = wf.State;
error = wf.Message;
}
TryUpdateHealth(gen, h => new DriverHealth(state, h.LastSuccessfulRead, error));
if (state == DriverState.Degraded) _writeOwnedError = error;
TryUpdateHealth(gen, h => new DriverHealth(state, answeredAt ?? h.LastSuccessfulRead, error));
}
/// <summary>
@@ -2068,10 +2121,18 @@ public sealed class S7Driver
public DriverState WorstFailure => _inner.WorstFailure;
/// <summary>The message explaining <see cref="WorstFailure"/>.</summary>
public string? WorstError => _inner.WorstError;
/// <summary>True once the batch observed a success or a failure.</summary>
public bool HasObservations => _inner.HasObservations;
/// <summary>True once the batch observed a success, a refusal or a failure.</summary>
public bool HasObservations => _inner.HasObservations || AnyAnswered;
/// <summary>True once the CPU answered any item (a success or a refusal) — proof of a live device.</summary>
public bool AnyAnswered { get; private set; }
/// <summary>Records one successful write.</summary>
public void RecordSuccess() => _inner.RecordSuccess();
public void RecordSuccess()
{
_inner.RecordSuccess();
AnyAnswered = true;
}
/// <summary>Records a write the CPU answered by refusing it: not a success, not a failure.</summary>
public void RecordAnswered() => AnyAnswered = true;
/// <summary>Records one failed write.</summary>
/// <param name="state">The state the failure would have stamped alone.</param>
/// <param name="message">The operator-facing message.</param>
@@ -2407,19 +2468,82 @@ public sealed class S7Driver
}
/// <summary>
/// Detects an S7 PUT/GET-disabled / access-protection fault inside an S7.Net
/// <see cref="PlcException"/>. S7.Net's read/write paths wrap every PLC-side error in a
/// <c>PlcException</c> with <see cref="ErrorCode.ReadData"/> / <see cref="ErrorCode.WriteData"/>;
/// the response-code validator throws a plain <see cref="Exception"/> for the S7
/// <c>AccessingObjectNotAllowed</c> status, which lands as the inner exception. There is
/// no typed error code for it, so the inner message is the only discriminator
/// S7.Net exposes.
/// True when <paramref name="ex"/> is a deterministic PLC REFUSAL of the item: the CPU answered
/// with an S7 item error (object does not exist, address out of range, data type inconsistent /
/// not supported, hardware fault, or an unknown status), or S7.Net raised a
/// <see cref="ErrorCode.ReadData"/> / <see cref="ErrorCode.WriteData"/> over a response it could
/// not use. Excludes the access-denied refusal (its own sticky Faulted config alert) and
/// anything carrying a socket / timeout / framing / cancellation fault in its chain — those
/// wrap a transport failure, not an answer.
/// </summary>
/// <param name="pex">The exception raised by S7.Net.</param>
/// <returns><see langword="true"/> when the PLC refused access to the object.</returns>
internal static bool IsAccessDenied(PlcException pex)
/// <remarks>
/// Live-probed against the snap7 fixture (2026-10-22): S7.Net's READ paths
/// (<c>ReadAsync(string)</c>, <c>ReadBytesAsync</c>) raise the item error as a BARE
/// <see cref="Exception"/> — "Received error from PLC: Object does not exist." — not wrapped in
/// a <see cref="PlcException"/>; its write paths wrap whatever they hit in a
/// <c>PlcException(WriteData)</c>. Both shapes are matched.
/// </remarks>
/// <param name="ex">The exception raised by S7.Net.</param>
/// <returns><see langword="true"/> when the CPU answered and refused.</returns>
internal static bool IsRefusal(Exception ex)
{
for (Exception? e = pex; e is not null; e = e.InnerException)
if (IsAccessDenied(ex) || IsS7ConnectionFatal(ex) || HasCancellationInChain(ex)) return false;
if (ex is PlcException { ErrorCode: ErrorCode.ReadData or ErrorCode.WriteData }) return true;
for (Exception? e = ex; e is not null; e = e.InnerException)
if (IsS7ItemError(e)) return true;
return false;
}
/// <summary>
/// True for the bare <see cref="Exception"/> S7.Net's response-code validator raises for an S7
/// item error ("Received error from PLC: …" / "Invalid response from PLC: statusCode=…").
/// Exact type only: a derived exception carrying similar words is not S7.Net's validator.
/// </summary>
/// <param name="e">One exception of a chain.</param>
/// <returns><see langword="true"/> for the validator's item-error shape.</returns>
private static bool IsS7ItemError(Exception e)
=> e.GetType() == typeof(Exception)
&& (e.Message.StartsWith("Received error from PLC", StringComparison.Ordinal)
|| e.Message.StartsWith("Invalid response from PLC", StringComparison.Ordinal));
/// <summary>True when a cancellation is buried in the exception chain (a half-read PDU, not a refusal).</summary>
/// <param name="ex">The exception to inspect.</param>
/// <returns><see langword="true"/> when any inner exception is an <see cref="OperationCanceledException"/>.</returns>
private static bool HasCancellationInChain(Exception ex)
{
for (var e = ex.InnerException; e is not null; e = e.InnerException)
if (e is OperationCanceledException) return true;
return false;
}
/// <summary>Logs a refusal once per tag per generation.</summary>
/// <param name="tagName">The refused tag.</param>
/// <param name="operation">"read" or "write".</param>
/// <param name="ex">The refusal.</param>
private void WarnRefusalOnce(string tagName, string operation, Exception ex)
{
if (!_refusalWarned.TryAdd(tagName, 0)) return;
_logger.LogWarning(
"S7 CPU refused the {Operation} of tag {Tag} ({Reason}); it reads Bad until the tag or the PLC program is fixed. " +
"Driver health is unaffected. Further refusals of this tag are not logged. Driver={DriverInstanceId}",
operation, tagName, ex.InnerException?.Message ?? ex.Message, _driverInstanceId);
}
/// <summary>
/// Detects an S7 PUT/GET-disabled / access-protection fault. S7.Net's response-code validator
/// throws a plain <see cref="Exception"/> for the S7 <c>AccessingObjectNotAllowed</c> status —
/// bare on the read paths, wrapped in a <see cref="PlcException"/> (<see cref="ErrorCode.WriteData"/>)
/// on the write paths. There is no typed error code for it, so the message is the only
/// discriminator S7.Net exposes. The top-level exception must be S7.Net-shaped (a
/// <see cref="PlcException"/> or the validator's bare item error), so an unrelated exception that
/// happens to say "not allowed" is not mistaken for it.
/// </summary>
/// <param name="ex">The exception raised by S7.Net.</param>
/// <returns><see langword="true"/> when the PLC refused access to the object.</returns>
internal static bool IsAccessDenied(Exception ex)
{
if (ex is not PlcException && !IsS7ItemError(ex)) return false;
for (Exception? e = ex; e is not null; e = e.InnerException)
{
if (e.Message.Contains("Accessing object not allowed", StringComparison.OrdinalIgnoreCase)
|| e.Message.Contains("not allowed", StringComparison.OrdinalIgnoreCase))
@@ -128,15 +128,17 @@ public sealed class S7DriverProbe : IDriverProbe
return null;
}
catch (OperationCanceledException) { throw; }
catch (PlcException pex) when (S7Driver.IsAccessDenied(pex))
// S7.Net's read paths raise the CPU's item error as a BARE Exception ("Received error from
// PLC: …"), not a PlcException, so both classifiers walk the whole chain (the driver's own).
catch (Exception ex) when (S7Driver.IsAccessDenied(ex))
{
return new(false,
"S7 connected but data access is denied — enable PUT/GET communication in TIA Portal " +
$"(Protection & Security) for this CPU. PLC reported: {pex.Message}", null);
$"(Protection & Security) for this CPU. PLC reported: {ex.Message}", null);
}
catch (PlcException pex) when (pex.ErrorCode == ErrorCode.ReadData)
catch (Exception ex) when (S7Driver.IsRefusal(ex))
{
return null; // address not available on this CPU — not a connection problem
return null; // address not available on this CPU — the CPU answered; not a connection problem
}
catch (Exception ex)
{