feat(host): CentralSingletonRegistrar — canonical singleton manager+proxy+drain helper

2026-07-08 15:59:01 -04:00
parent 7138d47630
commit c255ec31c9
2 changed files with 121 additions and 0 deletions
@@ -0,0 +1,61 @@
+using Akka.Actor;
+using Akka.Cluster.Tools.Singleton;
+using Microsoft.Extensions.Logging;
+
+namespace ZB.MOM.WW.ScadaBridge.Host.Actors;
+
+/// <summary>
+/// Registers a central cluster singleton with the canonical naming scheme
+/// (<c>{name}-singleton</c> / <c>{name}-proxy</c>), a PoisonPill termination
+/// message, and a PhaseClusterLeave drain task that GracefulStops the manager
+/// so in-flight EF work completes before handover. Extracted from five
+/// copy-pasted ~60-line blocks (review 01 [Low]) whose drift left the two
+/// busiest singletons (notification-outbox, audit-log-ingest) without drain
+/// tasks (review 01 [Medium]).
+/// </summary>
+internal static class CentralSingletonRegistrar
+{
+    internal sealed record Handle(IActorRef Manager, IActorRef Proxy);
+
+    internal static Handle Start(
+        ActorSystem system,
+        string name,
+        Props singletonProps,
+        ILogger logger,
+        TimeSpan? drainTimeout = null)
+    {
+        var manager = system.ActorOf(
+            ClusterSingletonManager.Props(
+                singletonProps,
+                PoisonPill.Instance,
+                ClusterSingletonManagerSettings.Create(system).WithSingletonName(name)),
+            $"{name}-singleton");
+
+        var timeout = drainTimeout ?? TimeSpan.FromSeconds(10);
+        Akka.Actor.CoordinatedShutdown.Get(system).AddTask(
+            Akka.Actor.CoordinatedShutdown.PhaseClusterLeave,
+            $"drain-{name}-singleton",
+            async () =>
+            {
+                try
+                {
+                    await manager.GracefulStop(timeout);
+                }
+                catch (Exception ex)
+                {
+                    logger.LogWarning(ex,
+                        "{Singleton} singleton did not drain within the graceful-stop timeout; "
+                        + "falling through to PoisonPill handover", name);
+                }
+                return Akka.Done.Instance;
+            });
+
+        var proxy = system.ActorOf(
+            ClusterSingletonProxy.Props(
+                $"/user/{name}-singleton",
+                ClusterSingletonProxySettings.Create(system).WithSingletonName(name)),
+            $"{name}-proxy");
+
+        return new Handle(manager, proxy);
+    }
+}