feat(abcip): final review I1 — node-level Drivers:AbCip:DefaultTransport

The old AdminUI cannot author the per-driver transport key (#576), so the 'pin before upgrading' recipe had no working path. A node-level appsetting (env Drivers__AbCip__DefaultTransport) now supplies the default for AbCip drivers with no key: explicit key > node default > compiled Native. Bound and validated unconditionally (bad value fails host start); the driver factory and the Test Connect probe both read it so they agree. AbCip.md upgrade recipe rewritten around the key; Configuration.md documents it. Also documents first-wins for AllowPacking/probe and host-alias throttles (final review M6) and moves the status-bit note out of AbCip.md (M5). Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-07 21:34:48 -04:00
parent b66972b6f5
commit b75e013d0a
13 changed files with 447 additions and 44 deletions
@@ -0,0 +1,58 @@
+using ZB.MOM.WW.Configuration;
+using ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     Node-level defaults for the AbCip driver (final review I1), bound from <c>Drivers:AbCip</c>. Lets an
+///     operator pin the transport an AbCip driver with NO <c>transport</c> key runs on — at upgrade time,
+///     without editing (or being able to edit, #576) every driver config. An explicit per-driver
+///     <c>transport</c> key still wins. Overridable by environment variable
+///     <c>Drivers__AbCip__DefaultTransport</c>.
+/// </summary>
+public sealed class AbCipDriverDefaultsOptions
+{
+    /// <summary>The configuration section path.</summary>
+    public const string SectionName = "Drivers:AbCip";
+
+    /// <summary>
+    ///     <c>Native</c> (the default) or <c>Libplctag</c>, case-insensitive. Blank/absent = <c>Native</c>.
+    ///     Any other value fails host start (<see cref="AbCipDriverDefaultsOptionsValidator"/>).
+    /// </summary>
+    public string? DefaultTransport { get; set; } = nameof(AbCipTransport.Native);
+
+    /// <summary>
+    ///     The parsed default: blank resolves to the compiled <see cref="AbCipTransportResolver.Default"/>.
+    ///     Throws on an unparseable value — unreachable at runtime because the validator fails host start first.
+    /// </summary>
+    /// <returns>The node-level default transport.</returns>
+    public AbCipTransport ResolveDefaultTransport()
+    {
+        if (string.IsNullOrWhiteSpace(DefaultTransport)) return AbCipTransportResolver.Default;
+        return AbCipTransportResolver.TryParse(DefaultTransport, out var t)
+            ? t
+            : throw new InvalidOperationException(AbCipDriverDefaultsOptionsValidator.Message(DefaultTransport));
+    }
+}
+
+/// <summary>Fail-fast startup validator for <see cref="AbCipDriverDefaultsOptions"/>.</summary>
+public sealed class AbCipDriverDefaultsOptionsValidator : OptionsValidatorBase<AbCipDriverDefaultsOptions>
+{
+    /// <summary>The operator-facing failure text for a bad value.</summary>
+    /// <param name="value">The rejected value.</param>
+    /// <returns>The message.</returns>
+    internal static string Message(string? value) =>
+        $"Drivers:AbCip:DefaultTransport is '{value}' — expected one of " +
+        $"{string.Join(", ", Enum.GetNames<AbCipTransport>())} (case-insensitive). It selects the transport an " +
+        "AbCip driver with no \"transport\" key runs on; set it via appsettings or the environment variable " +
+        "Drivers__AbCip__DefaultTransport.";
+
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, AbCipDriverDefaultsOptions options)
+    {
+        builder.RequireThat(
+            string.IsNullOrWhiteSpace(options.DefaultTransport)
+                || AbCipTransportResolver.TryParse(options.DefaultTransport, out _),
+            Message(options.DefaultTransport));
+    }
+}