using System.Globalization; using Microsoft.Extensions.Configuration; using ZB.MOM.WW.OtOpcUa.Core.Abstractions; using ZB.MOM.WW.OtOpcUa.Core.Resilience; using ZB.MOM.WW.OtOpcUa.Runtime.Drivers; namespace ZB.MOM.WW.OtOpcUa.Host.Configuration; /// /// Binds DriverWrites:Timeout into and checks it against the resilience /// tiers' Write timeouts (lmxopcua#777). One place, so Program.cs and its unit test bind the same way. /// /// /// Matches : a bad value is clamped to a safe one and reported as a startup /// Warning, never a boot failure. No setting here can make a write outlive an Ask — every Ask is derived from the /// timeout — so an inconsistency only means a configured bound does not take effect, which is worth saying loudly /// but not worth an outage. /// public static class DriverWriteBoundsBinding { /// The configuration key of the write timeout. public const string TimeoutKey = DriverWriteBounds.SectionName + ":Timeout"; /// Binds, clamps and validates the write timeout. /// The host configuration. /// One line per clamped value or tier inconsistency, for the caller to log as a Warning. /// The write bounds; when the key is absent. public static DriverWriteBounds Bind(IConfiguration configuration, out IReadOnlyList warnings) { ArgumentNullException.ThrowIfNull(configuration); var found = new List(); var timeout = DriverWriteBounds.DefaultTimeout; var raw = configuration[TimeoutKey]; if (!string.IsNullOrWhiteSpace(raw)) { if (!TimeSpan.TryParse(raw, CultureInfo.InvariantCulture, out var parsed)) { found.Add($"{TimeoutKey} '{raw}' is not a TimeSpan (e.g. 00:00:10); using the default {Format(timeout)}."); } else if (parsed <= TimeSpan.Zero) { found.Add($"{TimeoutKey} {parsed} is not positive; using the default {Format(timeout)}."); } else if (parsed > DriverWriteBounds.MaxTimeout) { timeout = DriverWriteBounds.MaxTimeout; found.Add($"{TimeoutKey} {parsed} exceeds the max {Format(timeout)}; clamped."); } else { timeout = parsed; } } var bounds = new DriverWriteBounds(timeout); found.AddRange(CheckTierDefaults(bounds)); warnings = found; return bounds; } /// /// Reports every resilience tier whose DEFAULT Write timeout exceeds ' timeout. The /// actor cancels a write at that timeout, so such a tier's Write policy never takes effect: its drivers' /// writes are cut off sooner than their tier says. (Per-instance ResilienceConfig overrides arrive /// with a deployment, not at startup; checks those at spawn.) /// /// The write bounds in force. /// One warning per inconsistent tier; empty when every tier fits. public static IReadOnlyList CheckTierDefaults(DriverWriteBounds bounds) { ArgumentNullException.ThrowIfNull(bounds); var found = new List(); foreach (var tier in Enum.GetValues()) { var write = DriverResilienceOptions.GetTierDefaults(tier)[DriverCapability.Write]; if (TimeSpan.FromSeconds(write.TimeoutSeconds) > bounds.Timeout) { found.Add( $"Tier {tier} drivers' Write timeout ({write.TimeoutSeconds}s) exceeds {TimeoutKey} " + $"({Format(bounds.Timeout)}): their writes are cancelled at {Format(bounds.Timeout)}, so the tier " + $"policy never takes effect. Raise {TimeoutKey} to at least {write.TimeoutSeconds}s."); } } return found; } /// One line naming every derived bound, for the startup log. /// The write bounds in force. /// The description. public static string Describe(DriverWriteBounds bounds) { ArgumentNullException.ThrowIfNull(bounds); return $"write timeout {Format(bounds.Timeout)}, token-ignoring writes abandoned at {Format(bounds.RunBound)}, " + $"queue budget {Format(bounds.QueueBudget)}, driver-host Ask {Format(bounds.HostAsk)}, " + $"inbound-write gateway Ask {Format(bounds.GatewayAsk)}"; } private static string Format(TimeSpan value) => value.TotalSeconds.ToString("0.###", CultureInfo.InvariantCulture) + "s"; }