Files
lmxopcua/src/Core/ZB.MOM.WW.OtOpcUa.Cluster/EffectiveRoles.cs
T
Joseph Doherty 826312befe docs: fill missing XML docs and strip tracking IDs from src comments
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.
2026-10-15 06:14:58 -04:00

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>'.");
}