feat(cluster): simultaneous-cold-start split-brain guard (#33)

Port OtOpcUa's bootstrap guard (lmxopcua d1dac87f) to ScadaBridge's BuildHocon bootstrap. Both pair nodes are self-first seeds, so a true simultaneous cold start (shared site power event) races FirstSeedNodeProcess on both and forms two 1-node clusters that never merge. Opt-in dark switch ScadaBridge:Cluster:BootstrapGuard:Enabled (default off, guard-off behavior byte-identical). When on: BuildHocon emits an empty seed list so Akka does not auto-join, and ClusterBootstrapCoordinator (IHostedService, registered in both the Central and Site composition roots) picks the join order from ClusterBootstrapGuard's pure decision core — the lower canonical host:port is the founder (self-first, forms immediately); the higher node TCP-probes the founder up to PartnerProbeSeconds and joins peer-first if reachable, else self-first (cold-start-alone preserved). Decides before a single JoinSeedNodes, never re-forms mid-handshake. Review notes carried over: case-insensitive founder tie-break; fail-fast validation of probe timings when enabled; higher-node-cold-start-alone covered by a real-ActorSystem test. 21 unit + 5 real-cluster tests (incl. the headline both-cold-start-together-form-one-cluster).
2026-07-24 08:55:48 -04:00
parent bb138d5254
commit 248676ed16
10 changed files with 895 additions and 2 deletions
@@ -215,4 +215,68 @@ public class ClusterOptionsValidatorTests
        Assert.Contains("StableAfter", result.FailureMessage);
        Assert.Contains("HeartbeatInterval", result.FailureMessage);
    }
+
+    // ---- BootstrapGuard timing validation (Gitea #33) ----
+
+    [Fact]
+    public void BootstrapGuard_disabled_with_zero_timings_passes_validation()
+    {
+        // The knobs are inert when the guard is off, so a disabled guard must never block a boot —
+        // even if the timing values are nonsense (0 here).
+        var options = ValidOptions();
+        options.BootstrapGuard = new ClusterBootstrapGuardOptions
+        {
+            Enabled = false,
+            PartnerProbeSeconds = 0,
+            PartnerProbeIntervalMs = 0,
+            ProbeConnectTimeoutMs = 0,
+        };
+
+        var result = new ClusterOptionsValidator().Validate(null, options);
+
+        Assert.True(result.Succeeded, result.FailureMessage);
+    }
+
+    [Fact]
+    public void BootstrapGuard_enabled_with_default_timings_passes_validation()
+    {
+        var options = ValidOptions();
+        options.BootstrapGuard = new ClusterBootstrapGuardOptions { Enabled = true };
+
+        var result = new ClusterOptionsValidator().Validate(null, options);
+
+        Assert.True(result.Succeeded, result.FailureMessage);
+    }
+
+    [Fact]
+    public void BootstrapGuard_enabled_with_nonpositive_probe_seconds_fails_validation()
+    {
+        // A zero PartnerProbeSeconds silently degrades the guard to "never wait, always conclude the
+        // partner is dead" — the higher node forms alone immediately and re-opens the split. Reject it.
+        var options = ValidOptions();
+        options.BootstrapGuard = new ClusterBootstrapGuardOptions { Enabled = true, PartnerProbeSeconds = 0 };
+
+        var result = new ClusterOptionsValidator().Validate(null, options);
+
+        Assert.True(result.Failed);
+        Assert.Contains("PartnerProbeSeconds", result.FailureMessage);
+    }
+
+    [Fact]
+    public void BootstrapGuard_enabled_with_nonpositive_interval_or_timeout_fails_validation()
+    {
+        var options = ValidOptions();
+        options.BootstrapGuard = new ClusterBootstrapGuardOptions
+        {
+            Enabled = true,
+            PartnerProbeIntervalMs = 0,
+            ProbeConnectTimeoutMs = -1,
+        };
+
+        var result = new ClusterOptionsValidator().Validate(null, options);
+
+        Assert.True(result.Failed);
+        Assert.Contains("PartnerProbeIntervalMs", result.FailureMessage);
+        Assert.Contains("ProbeConnectTimeoutMs", result.FailureMessage);
+    }
 }