feat(redundancy): manual failover service — graceful Leave of the driver Primary

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-22 06:40:58 -04:00
parent 983310edbb
commit 69b697bc3e
4 changed files with 416 additions and 0 deletions
@@ -0,0 +1,54 @@
+namespace ZB.MOM.WW.OtOpcUa.ControlPlane.Redundancy;
+
+/// <summary>
+/// A read-only view of the cluster's driver membership, as the manual-failover control sees it.
+/// </summary>
+/// <param name="PrimaryAddress">
+/// The current driver Primary — the oldest Up <c>driver</c> member, the same node
+/// <see cref="RedundancyStateActor.SelectDriverPrimary"/> names — or <see langword="null"/> when
+/// there is no Up driver member at all.
+/// </param>
+/// <param name="DriverAddresses">
+/// Every Up <c>driver</c> member, oldest first. A manual failover needs at least two: with one
+/// there is nothing to fail over to.
+/// </param>
+public sealed record ManualFailoverSnapshot(string? PrimaryAddress, IReadOnlyList<string> DriverAddresses)
+{
+    /// <summary>Whether a failover can be performed — i.e. a peer exists to take over.</summary>
+    public bool CanFailOver => DriverAddresses.Count >= 2;
+}
+
+/// <summary>
+/// Operator-initiated, graceful swap of the driver Primary.
+/// </summary>
+/// <remarks>
+///     <para>
+///         The mechanism is a cluster <b>Leave</b> of the current Primary, never a <c>Down</c>. The
+///         leaving node hands its singletons over through the normal cluster-leave phases,
+///         <c>CoordinatedShutdown</c> runs, <c>ActorSystemTerminationWatchdog</c> exits the process,
+///         the service supervisor restarts it, and it rejoins as the youngest member — so the
+///         survivor becomes the oldest Up driver member and therefore Primary. ServiceLevel 250
+///         moves with it and OPC UA clients re-select.
+///     </para>
+///     <para>
+///         <b>Mesh-scope caveat.</b> Until the per-cluster mesh work lands
+///         (<c>docs/plans/2026-07-21-per-cluster-mesh-design.md</c>) the Primary is elected once per
+///         Akka mesh, not per application <c>Cluster</c> row. On a fleet running several application
+///         clusters in one mesh this acts on the whole mesh's Primary. The UI says so.
+///     </para>
+/// </remarks>
+public interface IManualFailoverService
+{
+    /// <summary>Reads the current driver membership from live cluster state.</summary>
+    ManualFailoverSnapshot GetSnapshot();
+
+    /// <summary>
+    /// Gracefully removes the current driver Primary from the cluster so its peer takes over.
+    /// </summary>
+    /// <param name="actor">The authenticated identity performing the failover; recorded in the audit event.</param>
+    /// <returns>
+    /// The address of the node asked to leave, or <see langword="null"/> when the failover was
+    /// refused because no driver peer exists (in which case nothing was changed and nothing audited).
+    /// </returns>
+    Task<string?> FailOverDriverPrimaryAsync(string actor);
+}