refactor: rename ScadaLink → ZB.MOM.WW.ScadaBridge (code + projects + namespaces)

Solution + 23 src projects + 26 test projects renamed; folders, csproj, namespaces, and ScadaLinkDbContext/ScadaBridgeDbContext class updated. ActorSystem "scadalink" → "scadabridge", Akka seed-node URLs migrated. SQL roles/logins, LDAP domains, CLI command name, and CLI config dir (~/.scadalink → ~/.scadabridge) also renamed. Build green; 5 Host.Tests fail awaiting SQL login rename in next commit. Pre-existing StaleTagMonitor timing flakes unchanged. Rename script committed at tools/rename-to-scadabridge.sh.
2026-05-28 09:37:45 -04:00
parent 6d87ee3c3b
commit 7b0b9c7365
1531 changed files with 11180 additions and 11054 deletions
@@ -0,0 +1,79 @@
+namespace ZB.MOM.WW.ScadaBridge.ClusterInfrastructure;
+
+/// <summary>
+/// Cluster configuration model, bound from the <c>ScadaBridge:Cluster</c> section
+/// of <c>appsettings.json</c> via the Options pattern.
+/// <para>
+/// This project owns the cluster <em>configuration contract</em>. The actual
+/// Akka.NET bootstrap — building the HOCON from these values, starting the
+/// <c>ActorSystem</c>, configuring the split-brain resolver and wiring
+/// <c>CoordinatedShutdown</c> — lives in <c>ZB.MOM.WW.ScadaBridge.Host</c>
+/// (see <c>Component-ClusterInfrastructure.md</c> → "Implementation Note — Code Placement").
+/// </para>
+/// <para>
+/// Node-identity settings (remoting hostname/port, cluster role, site identifier,
+/// gRPC port) are deliberately <em>not</em> here — they are owned by
+/// <c>ZB.MOM.WW.ScadaBridge.Host.NodeOptions</c> (<c>ScadaBridge:Node</c> section). Local SQLite
+/// storage paths are owned by the database / store-and-forward options. This class
+/// holds only the cluster-formation and failure-detection settings shared by every node.
+/// </para>
+/// </summary>
+public class ClusterOptions
+{
+    // ClusterInfra-011: the previous `public const string SectionName = "ScadaBridge:Cluster";`
+    // was documented as "single source of truth so binding sites do not hard-code the
+    // magic string" but no caller ever read it — the Host's SiteServiceRegistration and
+    // StartupValidator both hard-code the literal directly. Wiring those binding sites
+    // to reference the constant lives in the Host's edit scope (a separate code-review
+    // task); rather than carry a public constant whose guarantee the code does not
+    // deliver, the constant is removed and the literal stays in the Host until the
+    // Host-side wiring is done. If a future Host change wants the constant back, add it
+    // when the binding sites can be updated in the same commit.
+
+    /// <summary>
+    /// Akka.NET cluster seed nodes. Both nodes are seed nodes — each node lists
+    /// itself and its partner — so either can start first and form the cluster.
+    /// Must contain at least one entry.
+    /// </summary>
+    public List<string> SeedNodes { get; set; } = new();
+
+    /// <summary>
+    /// Split-brain resolver strategy. Must be <c>keep-oldest</c> for the two-node
+    /// clusters ScadaBridge uses: quorum strategies (<c>keep-majority</c>,
+    /// <c>static-quorum</c>) cannot distinguish a crash from a partition with only
+    /// two nodes and would shut down the whole cluster.
+    /// </summary>
+    public string SplitBrainResolverStrategy { get; set; } = "keep-oldest";
+
+    /// <summary>
+    /// Time the cluster membership must remain stable before the split-brain
+    /// resolver acts to down unreachable nodes. Must be positive. Default 15s.
+    /// </summary>
+    public TimeSpan StableAfter { get; set; } = TimeSpan.FromSeconds(15);
+
+    /// <summary>
+    /// Frequency of cluster failure-detector heartbeat messages between nodes.
+    /// Must be well below <see cref="FailureDetectionThreshold"/>. Default 2s.
+    /// </summary>
+    public TimeSpan HeartbeatInterval { get; set; } = TimeSpan.FromSeconds(2);
+
+    /// <summary>
+    /// Time without a heartbeat before a node is considered unreachable
+    /// (Akka's <c>acceptable-heartbeat-pause</c>). Default 10s.
+    /// </summary>
+    public TimeSpan FailureDetectionThreshold { get; set; } = TimeSpan.FromSeconds(10);
+
+    /// <summary>
+    /// Akka's <c>min-nr-of-members</c>. Must be <c>1</c>: after failover only one
+    /// node runs, and a value of <c>2</c> blocks the cluster singleton (Site Runtime
+    /// Deployment Manager) — and therefore all data collection — indefinitely.
+    /// </summary>
+    public int MinNrOfMembers { get; set; } = 1;
+
+    /// <summary>
+    /// The keep-oldest resolver's <c>down-if-alone</c> flag. When <c>true</c> (the
+    /// design-doc requirement), the oldest node downs itself if it finds it has no
+    /// other reachable members, rather than running as an isolated single-node cluster.
+    /// </summary>
+    public bool DownIfAlone { get; set; } = true;
+}
@@ -0,0 +1,95 @@
+using Microsoft.Extensions.Options;
+
+namespace ZB.MOM.WW.ScadaBridge.ClusterInfrastructure;
+
+/// <summary>
+/// CI-004: Validates <see cref="ClusterOptions"/> at startup. The values it
+/// guards carry cluster-wide consequences — the design doc
+/// (<c>Component-ClusterInfrastructure.md</c>) is emphatic that misconfiguring
+/// them produces a total cluster shutdown or an indefinitely blocked singleton.
+/// Registered with <c>ValidateOnStart()</c> so a bad <c>appsettings.json</c>
+/// fails fast at boot rather than failing far from the cause.
+/// </summary>
+public sealed class ClusterOptionsValidator : IValidateOptions<ClusterOptions>
+{
+    /// <summary>Split-brain resolver strategies safe for ScadaBridge's two-node clusters.</summary>
+    private static readonly HashSet<string> AllowedStrategies = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "keep-oldest"
+    };
+
+    /// <summary>
+    /// Validates the cluster options, returning a failure result if any critical settings are misconfigured.
+    /// </summary>
+    /// <param name="name">Named options instance name (unused; all instances are validated identically).</param>
+    /// <param name="options">The cluster options to validate.</param>
+    public ValidateOptionsResult Validate(string? name, ClusterOptions options)
+    {
+        var failures = new List<string>();
+
+        if (options.SeedNodes is null || options.SeedNodes.Count < 2)
+        {
+            // CI-012: design doc states "both nodes are seed nodes — each node lists
+            // both itself and its partner" so a properly-configured deployment lists
+            // two. Accepting a single-seed configuration silently defeats the
+            // "no startup ordering dependency" guarantee called out by
+            // Component-ClusterInfrastructure.md (Node Configuration).
+            failures.Add(
+                "ClusterOptions.SeedNodes must contain at least 2 seed nodes "
+                + "(Component-ClusterInfrastructure.md → Node Configuration: "
+                + "both nodes are seed nodes); a single-seed configuration defeats "
+                + "the no-startup-ordering-dependency guarantee.");
+        }
+
+        if (string.IsNullOrWhiteSpace(options.SplitBrainResolverStrategy)
+            || !AllowedStrategies.Contains(options.SplitBrainResolverStrategy))
+        {
+            failures.Add(
+                $"ClusterOptions.SplitBrainResolverStrategy must be 'keep-oldest' for a two-node cluster; " +
+                $"'{options.SplitBrainResolverStrategy}' would risk a total cluster shutdown on a partition.");
+        }
+
+        if (options.MinNrOfMembers != 1)
+        {
+            failures.Add(
+                $"ClusterOptions.MinNrOfMembers must be 1 (was {options.MinNrOfMembers}); " +
+                "any other value blocks the cluster singleton after failover and halts all data collection.");
+        }
+
+        if (options.StableAfter <= TimeSpan.Zero)
+        {
+            failures.Add("ClusterOptions.StableAfter must be a positive duration.");
+        }
+
+        if (options.HeartbeatInterval <= TimeSpan.Zero)
+        {
+            failures.Add("ClusterOptions.HeartbeatInterval must be a positive duration.");
+        }
+
+        if (options.FailureDetectionThreshold <= TimeSpan.Zero)
+        {
+            failures.Add("ClusterOptions.FailureDetectionThreshold must be a positive duration.");
+        }
+
+        if (options.HeartbeatInterval >= options.FailureDetectionThreshold)
+        {
+            failures.Add(
+                $"ClusterOptions.HeartbeatInterval ({options.HeartbeatInterval}) must be well below " +
+                $"FailureDetectionThreshold ({options.FailureDetectionThreshold}); otherwise nodes are " +
+                "declared unreachable before a heartbeat can arrive.");
+        }
+
+        if (!options.DownIfAlone)
+        {
+            failures.Add(
+                "ClusterOptions.DownIfAlone must be true for the keep-oldest resolver "
+                + "(Component-ClusterInfrastructure.md → Split-Brain Resolution); with it false the "
+                + "oldest node can run as an isolated single-node cluster during a partition while the "
+                + "younger node forms its own, producing two live clusters.");
+        }
+
+        return failures.Count > 0
+            ? ValidateOptionsResult.Fail(failures)
+            : ValidateOptionsResult.Success;
+    }
+}
@@ -0,0 +1,46 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
+
+namespace ZB.MOM.WW.ScadaBridge.ClusterInfrastructure;
+
+/// <summary>
+/// DI registration for the Cluster Infrastructure component.
+/// </summary>
+public static class ServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers the Cluster Infrastructure services. This component owns the
+    /// cluster <em>configuration contract</em> (<see cref="ClusterOptions"/>); the
+    /// Akka.NET bootstrap itself lives in <c>ZB.MOM.WW.ScadaBridge.Host</c>
+    /// (see <c>Component-ClusterInfrastructure.md</c>).
+    /// <para>
+    /// Registering the <see cref="ClusterOptionsValidator"/> means a misconfigured
+    /// <c>ScadaBridge:Cluster</c> section (e.g. <c>MinNrOfMembers: 2</c> or a quorum
+    /// split-brain strategy) throws an <see cref="OptionsValidationException"/> the
+    /// first time <see cref="IOptions{TOptions}"/> is resolved, rather than booting
+    /// into a broken cluster.
+    /// </para>
+    /// </summary>
+    /// <param name="services">The service collection to register into.</param>
+    public static IServiceCollection AddClusterInfrastructure(this IServiceCollection services)
+    {
+        services.TryAddEnumerable(
+            ServiceDescriptor.Singleton<IValidateOptions<ClusterOptions>, ClusterOptionsValidator>());
+        return services;
+    }
+
+    // ClusterInfra-014: the previous `AddClusterInfrastructureActors` extension
+    // was dead surface — its XML doc told callers "do not call", its body
+    // unconditionally threw `NotImplementedException`, and no production caller
+    // existed anywhere in the solution (verified by grep). The CI-002
+    // "throw loudly" decision was made while CI-001's ownership question was
+    // still open; that question is now permanently settled by the
+    // "Implementation Note — Code Placement" section of
+    // Component-ClusterInfrastructure.md, which records that all actor wiring
+    // lives in ZB.MOM.WW.ScadaBridge.Host (AkkaHostedService). Keeping a public extension
+    // method that exists only to throw was API-surface noise that an IDE would
+    // still suggest via auto-complete, so the method and its companion
+    // `AddClusterInfrastructureActors_ThrowsRatherThanSilentlySucceeding` test
+    // were both removed.
+}
@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+    <PackageReference Include="Microsoft.Extensions.Options" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../ZB.MOM.WW.ScadaBridge.Commons/ZB.MOM.WW.ScadaBridge.Commons.csproj" />
+  </ItemGroup>
+
+</Project>