fix(ablegacy): libplctag refuses MicroLogix function files locally instead of a comms fault (#592)
v2-ci / unit-tests (push) Has been cancelled

libplctag 2.6.0 cannot parse RTC/HSC/... names; tag creation failed with
PLCTAG_ERR_BAD_PARAM, which the status translation reported as BadConnection:
evicted handle, degraded health, counted toward marking a healthy device down.
The libplctag runtime now refuses function-file addresses before creating a
native tag (Unsupported -> BadNotSupported, health untouched), matching native.
Docs: function files are unsupported on both transports, not "unverified".

Claude-Session: https://claude.ai/code/session_01GT67AD99zQQqpLCVm3p7xk
This commit is contained in:
Joseph Doherty
2026-11-13 01:00:47 -05:00
parent 422ed50b9c
commit eec87d3f74
7 changed files with 136 additions and 19 deletions
@@ -1641,9 +1641,11 @@ public sealed partial class AbLegacyDriver : IDriver, IReadable, IWritable, ITag
&& (IsDeviceRefusal(ate.Status) || ate is AbDeviceReplyException { Status: AbStatus.Unsupported });
/// <summary>
/// Initializes a freshly created runtime. A NATIVE runtime whose init (one read) is refused locally is
/// still KEPT: the refusal is deterministic and per-operation, so caching it avoids re-creating — and
/// Initializes a freshly created runtime. A runtime whose init is refused locally is still KEPT: the
/// refusal is deterministic and per-operation, so caching it avoids re-creating — and, for NATIVE,
/// re-leasing the pooled device connection — on every poll. Any other failure disposes it, as before.
/// (A libplctag runtime refuses only before creating its native tag — e.g. a MicroLogix function file —
/// so keeping it holds no native handle.)
/// </summary>
private static async Task InitializeOrKeepRefusedAsync(IAbLegacyTagRuntime runtime, Action keep, CancellationToken ct)
{
@@ -1651,7 +1653,8 @@ public sealed partial class AbLegacyDriver : IDriver, IReadable, IWritable, ITag
{
await runtime.InitializeAsync(ct).ConfigureAwait(false);
}
catch (Exception ex) when (IsLocalRefusal(ex) && runtime is NativeAbLegacyTagRuntime)
catch (Exception ex) when (IsLocalRefusal(ex)
&& runtime is NativeAbLegacyTagRuntime or LibplctagLegacyTagRuntime { IsRefused: true })
{
keep();
throw;
@@ -5,9 +5,9 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy;
/// <summary>
/// MicroLogix 1100/1400 function-file sub-element catalogue: the driver-surface type of
/// <c>RTC:0.HR</c>, <c>HSC:0.ACC</c>, ... Covers the commonly-addressed members per file — not exhaustive
/// (Rockwell defines 30+ on RTC alone). <b>Unverified on the wire:</b> the layouts are transcribed from the
/// MicroLogix instruction-set reference; neither transport has been captured against these files and the
/// native transport has no encoding for them at all.
/// (Rockwell defines 30+ on RTC alone). <b>Not readable today:</b> the layouts are transcribed from the
/// MicroLogix instruction-set reference; the native transport has no encoding for these files and libplctag
/// cannot parse their names, so both refuse them before the wire (<c>BadNotSupported</c>, #592).
/// </summary>
public static class AbLegacyFunctionFile
{
@@ -21,6 +21,9 @@ internal sealed class LibplctagLegacyTagRuntime : IAbLegacyTagRuntime
/// <summary>Why a write to this tag is refused before the wire (<see cref="WriteRefusal"/>), else null.</summary>
private readonly string? _writeRefusal;
/// <summary>Why EVERY operation on this tag is refused before the wire (<see cref="Refusal"/>), else null.</summary>
private readonly string? _refusal;
/// <summary>
/// The status the native tag held when a failed initialisation destroyed it (see
/// <see cref="LibplctagOrphanRelease"/>); null while the wrapper's own handle is authoritative.
@@ -37,6 +40,7 @@ internal sealed class LibplctagLegacyTagRuntime : IAbLegacyTagRuntime
_tag = BuildTag(p);
_count = Math.Max(1, p.ElementCount);
_writeRefusal = WriteRefusal(p);
_refusal = Refusal(p);
}
/// <summary>Builds the (uninitialized) libplctag tag for <paramref name="p"/>.</summary>
@@ -60,12 +64,16 @@ internal sealed class LibplctagLegacyTagRuntime : IAbLegacyTagRuntime
/// <inheritdoc />
public Task InitializeAsync(CancellationToken cancellationToken) =>
RunReleasingOrphanAsync(() => _tag.InitializeAsync(cancellationToken));
_refusal is { } refusal
? Task.FromException(new AbTransportException(AbStatus.Unsupported, refusal))
: RunReleasingOrphanAsync(() => _tag.InitializeAsync(cancellationToken));
// libplctag initialises an uninitialised tag on its first read, so this path can orphan one too.
/// <inheritdoc />
public Task ReadAsync(CancellationToken cancellationToken) =>
RunReleasingOrphanAsync(() => _tag.ReadAsync(cancellationToken));
_refusal is { } refusal
? Task.FromException(new AbTransportException(AbStatus.Unsupported, refusal))
: RunReleasingOrphanAsync(() => _tag.ReadAsync(cancellationToken));
// Throws the WriteRefusal refusal (Unsupported) before anything is sent — defence in depth;
// the driver asks the factory first and never creates a runtime for a refused write.
@@ -88,8 +96,24 @@ internal sealed class LibplctagLegacyTagRuntime : IAbLegacyTagRuntime
/// <param name="p">The tag's create parameters.</param>
/// <returns>The refusal reason, or <see langword="null"/>.</returns>
internal static string? WriteRefusal(AbLegacyTagCreateParams p) =>
LibplctagLegacyName.IsTranslated(p.TagName)
Refusal(p) ?? (LibplctagLegacyName.IsTranslated(p.TagName)
? $"Writes to '{p.TagName}' are not supported on the libplctag transport (its name is translated for libplctag; reads only)."
: null);
/// <summary>
/// The addresses libplctag cannot address at all, refused before a native tag is created: MicroLogix function
/// files (<c>RTC:0.HR</c>, <c>HSC:0.ACC</c>, ...). libplctag 2.6.0's <c>parse_pccc_file_type</c> has no function-file
/// letters (<c>RTC</c> reads as an R file followed by a non-digit, <c>HSC</c> falls to the default case), so tag
/// creation fails locally with <c>PLCTAG_ERR_BAD_PARAM</c> — which the status translation has no case for and so
/// reported as <see cref="AbStatus.BadConnection"/>: a comms fault that evicted the handle, degraded health and
/// counted toward marking a healthy device down. Refusing it as <see cref="AbStatus.Unsupported"/> answers
/// <c>BadNotSupported</c> with health untouched — the same answer the native transport gives (#592, 2026-11-13).
/// </summary>
/// <param name="p">The tag's create parameters.</param>
/// <returns>The refusal reason, or <see langword="null"/>.</returns>
internal static string? Refusal(AbLegacyTagCreateParams p) =>
NativeAbLegacyTagRuntime.IsFunctionFileName(p.TagName)
? $"'{p.TagName}' is a MicroLogix function file; the libplctag transport cannot address function files."
: null;
/// <summary>
@@ -121,6 +145,9 @@ internal sealed class LibplctagLegacyTagRuntime : IAbLegacyTagRuntime
/// (0 if none was created). Tests only.</summary>
internal int NativeHandle => _releasedHandle != 0 ? _releasedHandle : LibplctagOrphanRelease.HandleOf(_tag);
/// <summary>True when every operation is refused before the wire (<see cref="Refusal"/>); no native tag is ever created.</summary>
internal bool IsRefused => _refusal is not null;
/// <summary>The handle the libplctag wrapper itself still holds (0 once a release cleared it). Tests only.</summary>
internal int WrapperHandle => LibplctagOrphanRelease.HandleOf(_tag);
@@ -168,7 +168,10 @@ internal sealed class NativeAbLegacyTagRuntime : IAbLegacyTagRuntime
}
}
private static bool IsFunctionFileName(string tagName)
/// <summary>True when <paramref name="tagName"/> names a MicroLogix function file (<c>RTC:0.HR</c>, <c>HSC:0.ACC</c>, ...).</summary>
/// <param name="tagName">The canonical tag name.</param>
/// <returns><see langword="true"/> for a function-file address.</returns>
internal static bool IsFunctionFileName(string tagName)
{
var colon = tagName.IndexOf(':');
return colon > 0 && AbLegacyAddress.IsFunctionFileLetter(tagName[..colon].ToUpperInvariant());