feat(mesh): MeshCommand envelope + generation-suffixed ClusterClient factory

Phase 2 Task 2. Two small pieces the comm actors are built on. MeshCommand carries a command plus the DPS topic it would have been published on, so the admin singletons stop knowing which transport is in force. Without it the dark switch would have to be threaded through five publish sites across two actors, each free to drift. Central-side only -- it never crosses the wire, so it carries no serialization contract. DefaultMeshClusterClientFactory appends a generation counter to the actor name. Context.Stop is asynchronous and the name stays reserved until termination completes, so recreating the same name inside one message handler throws InvalidActorNameException -- which is exactly what a contact-set change does (stop the old client, create the replacement, one handler). Ported from the sister project, where it was a shipped bug fix rather than foresight. Sabotage-verified: freezing the name to a constant reddens both name tests with InvalidActorNameException. Dropped a third test I had written -- it asserted ClusterClientSettings directly and never touched the factory, so it was coverage theatre. Replaced with a comment saying where contact propagation IS covered (the Task 8 boundary test, the only place it can actually fail). Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
2026-07-22 10:45:13 -04:00
parent 7b71a6a35d
commit 0d6669d5ff
3 changed files with 142 additions and 0 deletions
@@ -0,0 +1,47 @@
+using System.Collections.Immutable;
+using Akka.Actor;
+using Akka.Cluster.Tools.Client;
+
+namespace ZB.MOM.WW.OtOpcUa.ControlPlane.Communication;
+
+/// <summary>
+///     Creates the <c>ClusterClient</c> central uses to reach driver nodes. Exists as a seam so
+///     <c>CentralCommunicationActor</c> can be tested against a <c>TestProbe</c> without standing up
+///     a second cluster.
+/// </summary>
+public interface IMeshClusterClientFactory
+{
+    /// <summary>Creates a client for the given receptionist contact points.</summary>
+    /// <param name="system">The actor system to spawn the client in.</param>
+    /// <param name="contacts">Receptionist actor paths, one per reachable node.</param>
+    /// <returns>The new client's <see cref="IActorRef"/>.</returns>
+    IActorRef Create(ActorSystem system, ImmutableHashSet<ActorPath> contacts);
+}
+
+/// <inheritdoc />
+public sealed class DefaultMeshClusterClientFactory : IMeshClusterClientFactory
+{
+    /// <summary>
+    ///     Per-incarnation generation counter, appended to the actor name.
+    /// </summary>
+    /// <remarks>
+    ///     <c>Context.Stop</c> of the previous client is <b>asynchronous</b> — its actor name stays
+    ///     reserved until termination completes — so recreating the same name while handling a single
+    ///     message throws <see cref="InvalidActorNameException"/>. That is exactly what a contact-set
+    ///     change does: stop the old client, create the replacement, both in one handler. A
+    ///     generation suffix makes every incarnation's name unique by construction. Ported from the
+    ///     sister project, where it was a shipped bug fix rather than foresight.
+    /// </remarks>
+    private long _generation;
+
+    /// <inheritdoc />
+    public IActorRef Create(ActorSystem system, ImmutableHashSet<ActorPath> contacts)
+    {
+        ArgumentNullException.ThrowIfNull(system);
+        ArgumentNullException.ThrowIfNull(contacts);
+
+        var settings = ClusterClientSettings.Create(system).WithInitialContacts(contacts);
+        var name = $"mesh-client-{Interlocked.Increment(ref _generation)}";
+        return system.ActorOf(ClusterClient.Props(settings), name);
+    }
+}