dohertj2/lmxopcua
1
0
Fork 0
Code Issues 32 Pull Requests Actions Packages Projects Releases Wiki Activity

fix(cluster): T7's post-overlay guard was structurally unreachable — compare live Cluster:Roles, not the PostConfigured options.Roles (review finding, R3-04)

Browse Source 
options.Roles is unconditionally overwritten by AddOtOpcUaCluster's PostConfigure to equal
EffectiveRoles.Gossiped (T2's own structural-identity fix), so comparing options.Roles against
Gossiped could never observe a divergence — an overlay setting Cluster:Roles was silently
ignored, not fail-start. The validator now injects IConfiguration and re-reads the raw
Cluster:Roles section LIVE (reflecting any overlay applied after EffectiveRoles was first
resolved), normalized through EffectiveRoles.Resolve for reuse of its own validation.

AddOtOpcUaCluster now TryAddSingleton(configuration) so a bare ServiceCollection test harness
(not just WebApplicationBuilder) can supply IConfiguration to the validator.

Both guard tests rewritten to go through the real AddOtOpcUaCluster + PostConfigure pipeline
over a live ConfigurationManager, simulating an overlay as a second provider added AFTER
EffectiveRoles was resolved off the same object — exactly Program.cs's own sequencing. Confirmed
red beforehand: the "changes" test failed to throw against the pre-fix validator.
This commit is contained in:
Joseph Doherty
2026-08-20 11:01:33 -04:00
parent 3648d3c129
commit af39e61638
3 changed files with 181 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Core/ZB.MOM.WW.OtOpcUa.Cluster/AkkaClusterOptionsValidator.cs
+78 -15
View File
@@ -1,4 +1,5 @@
using Akka.Actor;
using Microsoft.Extensions.Configuration;
using ZB.MOM.WW.Configuration;
namespace ZB.MOM.WW.OtOpcUa.Cluster;
@@ -37,18 +38,27 @@ namespace ZB.MOM.WW.OtOpcUa.Cluster;
public sealed class AkkaClusterOptionsValidator : OptionsValidatorBase<AkkaClusterOptions>
{
private readonly EffectiveRoles? _effectiveRoles;
private readonly IConfiguration? _configuration;
/// <summary>
/// DI-constructed by <c>AddValidatedOptions</c> (a plain <c>AddSingleton</c>), so a
/// constructor dependency is safe here. <paramref name="effectiveRoles"/> is optional (default
/// <see langword="null"/>) so a caller with no role-authority instance to hand — including
/// every test in this file that pre-dates R3-04 — keeps constructing this validator
/// parameterlessly; the post-overlay guard below (choice 4) is simply skipped when it is null.
/// DI-constructed by <c>AddValidatedOptions</c> (a plain <c>AddSingleton</c>), so constructor
/// dependencies are safe here. Both <paramref name="effectiveRoles"/> and
/// <paramref name="configuration"/> are optional (default <see langword="null"/>) so a caller
/// with neither to hand — including every test in this file that pre-dates R3-04 — keeps
/// constructing this validator parameterlessly; the post-overlay guard below (choice 4) is
/// simply skipped when either is null.
/// </summary>
/// <param name="effectiveRoles">The registered role authority, or null to skip the post-overlay guard.</param>
public AkkaClusterOptionsValidator(EffectiveRoles? effectiveRoles = null)
/// <param name="configuration">
/// The live application configuration — deliberately NOT read through
/// <paramref name="effectiveRoles"/>'s own snapshot (review finding, 2026-08-20): the guard
/// needs to see a role overlay applied AFTER <paramref name="effectiveRoles"/> was resolved,
/// and only a fresh read off the live <see cref="IConfiguration"/> can observe that.
/// </param>
public AkkaClusterOptionsValidator(EffectiveRoles? effectiveRoles = null, IConfiguration? configuration = null)
{
_effectiveRoles = effectiveRoles;
_configuration = configuration;
}
/// <inheritdoc />
@@ -109,25 +119,78 @@ public sealed class AkkaClusterOptionsValidator : OptionsValidatorBase<AkkaClust
/// R3-04 (choice 4, the residual divergence surface): <c>Program.cs</c> resolves
/// <see cref="EffectiveRoles"/> BEFORE the per-role appsettings overlay loads (the overlay's
/// filename depends on the answer), so if a role overlay — or a <c>${secret:}</c> expansion —
/// ever set <c>Cluster:Roles</c> itself, the bound <paramref name="options"/>.Roles (which
/// sees the FULL, post-overlay configuration) would silently disagree with the
/// <see cref="EffectiveRoles"/> instance every other consumer holds. Compares as SETS
/// (case-insensitively) rather than sequence, because ordering carries no meaning here and a
/// re-ordering is not the hazard this rule exists to catch — a genuinely different role set
/// is. A no-op today: none of the four shipped overlays carries a <c>Cluster</c> section.
/// ever set <c>Cluster:Roles</c> itself, that value would silently disagree with the
/// <see cref="EffectiveRoles"/> instance every other consumer holds.
/// </summary>
/// <remarks>
/// <para>
/// ⚠️ <b>Review finding (2026-08-20): deliberately NOT <paramref name="options"/>.Roles.</b>
/// <see cref="ServiceCollectionExtensions.AddOtOpcUaCluster"/>'s <c>PostConfigure</c>
/// unconditionally sets <c>options.Roles = [.. effectiveRoles.Gossiped]</c> — the very
/// structural-identity fix T2 landed — so <paramref name="options"/>.Roles and
/// <see cref="_effectiveRoles"/>.Gossiped are EQUAL BY CONSTRUCTION on every real host.
/// Comparing them here would make this guard structurally unreachable: it could never
/// observe a divergence no matter what an overlay did, because the same PostConfigure step
/// that a later overlay's Cluster:Roles bind feeds into is exactly what overwrites the
/// difference away before this validator ever runs. Caught by
/// <c>An_overlay_that_changes_Cluster_Roles_after_resolution_fails_naming_both_views</c>,
/// which failed (no throw) against the options.Roles-comparing version of this method.
/// </para>
/// <para>
/// Instead this re-reads the RAW <c>Cluster:Roles</c> section directly off the live
/// <see cref="_configuration"/>, which — being the same mutable object
/// <c>Program.cs</c>'s <c>builder.Configuration</c> is — reflects every provider added up
/// to the point something first resolves <c>IOptions&lt;AkkaClusterOptions&gt;</c>,
/// INCLUDING a role overlay applied after <see cref="_effectiveRoles"/> was captured.
/// Skipped when that raw value is empty — the ordinary shape for every
/// <c>OTOPCUA_ROLES</c>-only node, where nothing meaningful lives under the
/// <c>Cluster:Roles</c> key either before OR after an overlay, and comparing an empty
/// array against a non-empty <c>Gossiped</c> list would be a permanent false positive for
/// every env-only deployment (which CLAUDE.md notes is most of production).
/// </para>
/// <para>
/// Compares as SETS (case-insensitively) rather than sequence, because ordering carries no
/// meaning here and a re-ordering is not the hazard this rule exists to catch — a
/// genuinely different role set is. A no-op today for the "nothing changed" case: none of
/// the four shipped overlays carries a <c>Cluster</c> section.
/// </para>
/// </remarks>
private void ValidateAgainstEffectiveRoles(ValidationBuilder builder, AkkaClusterOptions options)
{
if (_effectiveRoles is null) return;
_ = options; // intentionally unused — see remarks: comparing against it would be vacuous.
if (_effectiveRoles is null || _configuration is null) return;
var bound = new HashSet<string>(options.Roles ?? Array.Empty<string>(), StringComparer.OrdinalIgnoreCase);
var postOverlayRaw = _configuration.GetSection(EffectiveRoles.ConfiguredRolesKey).Get<string[]>();
if (postOverlayRaw is not { Length: > 0 })
{
// Cluster:Roles is empty post-overlay too -> nothing to compare. Correct for every
// OTOPCUA_ROLES-only node, not merely "no data yet".
return;
}
string[] normalized;
try
{
// Reuses EffectiveRoles' own configured-path normalization/validation rather than
// re-implementing it (archreview theme 4 — one rule, stated once).
normalized = [.. EffectiveRoles.Resolve(postOverlayRaw, envRoles: null).Gossiped];
}
catch (ArgumentException ex)
{
builder.Add(
"Cluster:Roles was changed by a configuration layer applied after role resolution to "
+ $"an invalid value ({ex.Message}). A per-role appsettings overlay may not set Cluster:Roles.");
return;
}
var bound = new HashSet<string>(normalized, StringComparer.OrdinalIgnoreCase);
var registered = new HashSet<string>(_effectiveRoles.Gossiped, StringComparer.OrdinalIgnoreCase);
if (bound.SetEquals(registered)) return;
builder.Add(
"Cluster:Roles was changed by a configuration layer applied after role resolution "
+ $"(host view: [{string.Join(",", _effectiveRoles.Gossiped)}], bound: "
+ $"[{string.Join(",", options.Roles ?? Array.Empty<string>())}]). A per-role appsettings "
+ $"[{string.Join(",", normalized)}]). A per-role appsettings "
+ "overlay may not set Cluster:Roles.");
}
src/Core/ZB.MOM.WW.OtOpcUa.Cluster/ServiceCollectionExtensions.cs
+9
View File
@@ -45,6 +45,15 @@ public static class ServiceCollectionExtensions
// TryAddSingleton keeps this usable from a harness that registers its own EffectiveRoles first.
services.TryAddSingleton(_ => EffectiveRoles.Resolve(configuration));
// Review finding (2026-08-20): AkkaClusterOptionsValidator's post-overlay guard needs to
// re-read Cluster:Roles LIVE, off the current (possibly overlay-mutated) configuration — not
// off the pre-overlay EffectiveRoles snapshot above, and not off the bound AkkaClusterOptions
// (the PostConfigure two lines below makes that equal to the snapshot BY CONSTRUCTION, so
// comparing the guard against it could never observe a divergence). A bare ServiceCollection
// (unlike WebApplicationBuilder, which auto-registers IConfiguration) never registers this
// otherwise; TryAddSingleton is a no-op on a real host, where it is already registered.
services.TryAddSingleton(configuration);
// Gitea #532 (superseded by R3-04): apply the OTOPCUA_ROLES fallback the Roles property has
// always DOCUMENTED, in the one place every consumer reads through. Before this, a node
// configured only through the env var — the knob that drives all of Program.cs's role wiring —