826312befe
Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns, normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping the rationale they annotated. Comment-only: comment-stripped sources are identical to the parent commit.
196 lines
9.8 KiB
C#
196 lines
9.8 KiB
C#
using Microsoft.Extensions.Configuration;
|
|
|
|
namespace ZB.MOM.WW.OtOpcUa.Cluster;
|
|
|
|
/// <summary>Which of the two role sources <see cref="EffectiveRoles"/> resolved from.</summary>
|
|
public enum RoleSource
|
|
{
|
|
/// <summary>Neither source named any role.</summary>
|
|
None,
|
|
|
|
/// <summary><c>Cluster:Roles</c> was non-empty and won outright.</summary>
|
|
Configured,
|
|
|
|
/// <summary><c>Cluster:Roles</c> was empty; <c>OTOPCUA_ROLES</c> supplied the roles.</summary>
|
|
Environment,
|
|
}
|
|
|
|
/// <summary>The node's effective cluster roles — the SINGLE authority for "what is this node".
|
|
/// Resolved once, from one documented precedence, and consumed by BOTH the Host's conditional
|
|
/// wiring and the Akka role list, so the two cannot disagree (archreview 01/S-12 = 03/C5).</summary>
|
|
/// <remarks>
|
|
/// <para><b>Precedence:</b> <c>Cluster:Roles</c> when non-empty, else <c>OTOPCUA_ROLES</c>,
|
|
/// else empty. Unchanged from <see cref="RoleParser.ResolveEffectiveRoles(IReadOnlyList{string}?, string?)"/>
|
|
/// — what changed is that <c>Program.cs</c> now obeys it too, instead of reading the environment
|
|
/// directly.</para>
|
|
/// <para><b>Normalization is two-layer, on purpose.</b> <see cref="Gossiped"/> lower-cases plain
|
|
/// roles (Akka matches gossiped role names ORDINALLY, and every consumer compares against a
|
|
/// lowercase constant) but keeps a cluster role's ClusterId suffix VERBATIM — lower-casing that
|
|
/// would rename <c>cluster-SITE-A</c> on a running fleet, and a rolling pair upgrade would gossip
|
|
/// two different role names mid-window. Lower-casing a plain role changes the wire only for a
|
|
/// node that is already broken (archreview 01/S-12 = 03/C5, 01/C-9).</para>
|
|
/// <para><b>Validation runs on BOTH sources.</b> The environment path was always validated by
|
|
/// <see cref="RoleParser.Parse"/>; the configured path previously accepted anything verbatim
|
|
/// (<c>Cluster:Roles: ["Drivr"]</c> silently gossiped a role that matched nothing). Both now fail
|
|
/// fast, naming the offending key, on an unknown role — a miscased but KNOWN role still
|
|
/// normalizes silently rather than failing, or an operator's <c>Driver</c> would brick the node
|
|
/// at the exact moment they upgrade.</para>
|
|
/// </remarks>
|
|
public sealed class EffectiveRoles
|
|
{
|
|
private EffectiveRoles(IReadOnlyList<string> gossiped, RoleSource source, string? disagreementWarning)
|
|
{
|
|
Gossiped = gossiped;
|
|
Source = source;
|
|
DisagreementWarning = disagreementWarning;
|
|
ClusterRole = RoleParser.ClusterRoleFromRoles(gossiped);
|
|
ClusterId = ClusterRole is null ? null : RoleParser.ClusterIdFromRole(ClusterRole);
|
|
}
|
|
|
|
/// <summary>The configuration key <see cref="Resolve(IConfiguration)"/> reads for the configured
|
|
/// side of the precedence.</summary>
|
|
public const string ConfiguredRolesKey = "Cluster:Roles";
|
|
|
|
/// <summary>The roles as they are handed to Akka — <see cref="AkkaClusterOptions.Roles"/> becomes
|
|
/// this list, unmodified.</summary>
|
|
public IReadOnlyList<string> Gossiped { get; }
|
|
|
|
/// <summary>Which source resolved these roles.</summary>
|
|
public RoleSource Source { get; }
|
|
|
|
/// <summary>True when <see cref="RoleParser.Admin"/> is among <see cref="Gossiped"/> (case-insensitive).</summary>
|
|
public bool HasAdmin => Has(RoleParser.Admin);
|
|
|
|
/// <summary>True when <see cref="RoleParser.Driver"/> is among <see cref="Gossiped"/> (case-insensitive).</summary>
|
|
public bool HasDriver => Has(RoleParser.Driver);
|
|
|
|
/// <summary>True when <see cref="RoleParser.Dev"/> is among <see cref="Gossiped"/> (case-insensitive).</summary>
|
|
public bool HasDev => Has(RoleParser.Dev);
|
|
|
|
/// <summary>True when <paramref name="role"/> is among <see cref="Gossiped"/>, compared case-insensitively.</summary>
|
|
/// <param name="role">The role to test for.</param>
|
|
/// <returns><see langword="true"/> when the role is present; otherwise <see langword="false"/>.</returns>
|
|
public bool Has(string role) =>
|
|
Gossiped.Any(r => string.Equals(r, role, StringComparison.OrdinalIgnoreCase));
|
|
|
|
/// <summary>The first cluster-scoped role in <see cref="Gossiped"/>, original spelling preserved,
|
|
/// or null when this node carries none.</summary>
|
|
public string? ClusterRole { get; }
|
|
|
|
/// <summary>The ClusterId this node belongs to (the suffix of <see cref="ClusterRole"/>), or null
|
|
/// for a legacy / single-mesh node.</summary>
|
|
public string? ClusterId { get; }
|
|
|
|
/// <summary>Non-null when BOTH <c>Cluster:Roles</c> and <c>OTOPCUA_ROLES</c> were set and their
|
|
/// normalized role sets differ — the <c>Cluster:Roles</c>-wins case an operator almost certainly
|
|
/// did not intend (choice 5). Observability only: <see cref="Gossiped"/> still resolves from
|
|
/// <c>Cluster:Roles</c> exactly as usual. Returned rather than logged from this static factory —
|
|
/// the caller (<c>Program.cs</c>) logs it once Serilog is configured.</summary>
|
|
public string? DisagreementWarning { get; }
|
|
|
|
/// <summary>The one factory: resolves the effective roles off <paramref name="configuration"/>'s
|
|
/// <c>Cluster:Roles</c> and the process's <c>OTOPCUA_ROLES</c> environment variable.</summary>
|
|
/// <param name="configuration">The application configuration.</param>
|
|
/// <returns>The resolved <see cref="EffectiveRoles"/>.</returns>
|
|
/// <exception cref="ArgumentException">Either source names an unknown role.</exception>
|
|
public static EffectiveRoles Resolve(IConfiguration configuration)
|
|
{
|
|
ArgumentNullException.ThrowIfNull(configuration);
|
|
|
|
var configured = configuration.GetSection(ConfiguredRolesKey).Get<string[]>();
|
|
var envRoles = Environment.GetEnvironmentVariable(RoleParser.RolesEnvVar);
|
|
return Resolve(configured, envRoles);
|
|
}
|
|
|
|
/// <summary>Resolves the effective roles from explicit values — the overload
|
|
/// <see cref="Resolve(IConfiguration)"/> delegates to.</summary>
|
|
/// <param name="configured">The bound <c>Cluster:Roles</c> value.</param>
|
|
/// <param name="envRoles">The raw <c>OTOPCUA_ROLES</c> value.</param>
|
|
/// <returns>The resolved <see cref="EffectiveRoles"/>.</returns>
|
|
/// <exception cref="ArgumentException">Either source names an unknown role.</exception>
|
|
public static EffectiveRoles Resolve(IReadOnlyList<string>? configured, string? envRoles)
|
|
{
|
|
var configuredNormalized = configured is { Count: > 0 }
|
|
? NormalizeAndValidateConfigured(configured)
|
|
: null;
|
|
|
|
// RoleParser.Parse already trims, lower-cases (fully — including a cluster suffix, which is
|
|
// intentionally different from the configured path; see ClusterIdFromRole's remarks), dedupes
|
|
// and validates.
|
|
var envNormalized = !string.IsNullOrWhiteSpace(envRoles)
|
|
? RoleParser.Parse(envRoles)
|
|
: null;
|
|
|
|
var warning = BuildDisagreementWarning(configuredNormalized, envNormalized);
|
|
|
|
if (configuredNormalized is not null)
|
|
return new EffectiveRoles(configuredNormalized, RoleSource.Configured, warning);
|
|
|
|
if (envNormalized is not null)
|
|
return new EffectiveRoles(envNormalized, RoleSource.Environment, warning);
|
|
|
|
return new EffectiveRoles(Array.Empty<string>(), RoleSource.None, null);
|
|
}
|
|
|
|
/// <summary>Choice 5: a Warning (not an error) when both sources are set and their normalized
|
|
/// role sets differ — this cannot fire when only one source is set, so it is always <see
|
|
/// langword="null"/> in that case regardless of the other source's absence.</summary>
|
|
private static string? BuildDisagreementWarning(string[]? configuredNormalized, string[]? envNormalized)
|
|
{
|
|
if (configuredNormalized is null || envNormalized is null) return null;
|
|
|
|
var configuredSet = new HashSet<string>(configuredNormalized, StringComparer.OrdinalIgnoreCase);
|
|
var envSet = new HashSet<string>(envNormalized, StringComparer.OrdinalIgnoreCase);
|
|
if (configuredSet.SetEquals(envSet)) return null;
|
|
|
|
return $"{ConfiguredRolesKey} ([{string.Join(",", configuredNormalized)}]) and "
|
|
+ $"{RoleParser.RolesEnvVar} ([{string.Join(",", envNormalized)}]) disagree; "
|
|
+ $"{ConfiguredRolesKey} wins outright.";
|
|
}
|
|
|
|
/// <summary>Normalizes and validates the <c>Cluster:Roles</c> entries: a plain role is trimmed and
|
|
/// lower-cased; a cluster role keeps its ClusterId suffix verbatim but gets a normalized
|
|
/// (lower-case) <c>cluster-</c> prefix. Throws naming the offending index and value on anything
|
|
/// that is neither.</summary>
|
|
private static string[] NormalizeAndValidateConfigured(IReadOnlyList<string> configured)
|
|
{
|
|
var result = new string[configured.Count];
|
|
for (var i = 0; i < configured.Count; i++)
|
|
{
|
|
var raw = configured[i];
|
|
var trimmed = raw?.Trim() ?? string.Empty;
|
|
|
|
if (trimmed.Length == 0)
|
|
{
|
|
throw Unknown(i, raw);
|
|
}
|
|
|
|
if (RoleParser.IsClusterRole(trimmed))
|
|
{
|
|
var clusterId = RoleParser.ClusterIdFromRole(trimmed);
|
|
if (clusterId.Length == 0)
|
|
{
|
|
throw Unknown(i, raw);
|
|
}
|
|
|
|
result[i] = RoleParser.ClusterRolePrefix + clusterId;
|
|
continue;
|
|
}
|
|
|
|
var lowered = trimmed.ToLowerInvariant();
|
|
if (lowered is not (RoleParser.Admin or RoleParser.Driver or RoleParser.Dev))
|
|
{
|
|
throw Unknown(i, raw);
|
|
}
|
|
|
|
result[i] = lowered;
|
|
}
|
|
|
|
return result;
|
|
}
|
|
|
|
private static ArgumentException Unknown(int index, string? raw) =>
|
|
new($"{ConfiguredRolesKey}[{index}] = '{raw}' is not a known role. Allowed: {RoleParser.Admin}, "
|
|
+ $"{RoleParser.Driver}, {RoleParser.Dev}, or '{RoleParser.ClusterRolePrefix}<ClusterId>'.");
|
|
}
|