feat(runtime): ActorNodeWriteGateway — Asks RouteNodeWrite, returns NodeWriteOutcome

2026-06-14 01:23:43 -04:00
parent 0f7c47a559
commit 526ddb6a57
2 changed files with 158 additions and 0 deletions
@@ -0,0 +1,69 @@
+using Akka.Actor;
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.Runtime.Drivers;
+
+/// <summary>
+///     Akka adapter for the Commons <see cref="IOpcUaNodeWriteGateway"/>: routes an inbound OPC UA
+///     operator write to the local <see cref="DriverHostActor"/> by Asking it a
+///     <see cref="DriverHostActor.RouteNodeWrite"/> and translating the reply
+///     <see cref="DriverHostActor.NodeWriteResult"/> into a <see cref="NodeWriteOutcome"/>.
+///
+///     <para>
+///         The node manager calls <see cref="WriteAsync"/> fire-and-forget from its OnWriteValue handler,
+///         which runs under the node-manager Lock, so the method does no blocking work before its first
+///         await — resolving the actor and building the Ask returns a Task promptly. The
+///         <see cref="DriverHostActor"/> reference is resolved <em>lazily per write</em> via
+///         <c>resolveDriverHost</c>: the host wires this gateway during StartAsync, before the Akka
+///         <see cref="DriverHostActor"/> registers, so a one-shot resolve at construction would always miss
+///         and leave every write unavailable. By write time (long after startup) the registry has it.
+///     </para>
+/// </summary>
+public sealed class ActorNodeWriteGateway : IOpcUaNodeWriteGateway
+{
+    /// <summary>Default Ask timeout — matches the legacy inline lambda in the hosted service.</summary>
+    private static readonly TimeSpan DefaultAskTimeout = TimeSpan.FromSeconds(10);
+
+    private readonly Func<IActorRef?> _resolveDriverHost;
+    private readonly TimeSpan _askTimeout;
+    private readonly ILogger _logger;
+
+    /// <summary>Creates the gateway.</summary>
+    /// <param name="resolveDriverHost">Lazy per-write resolver for the local <see cref="DriverHostActor"/>;
+    /// returns null until the actor has registered (StartAsync ordering — the actor registers AFTER the host
+    /// wires this gateway).</param>
+    /// <param name="logger">Logger for dropped/rejected/timed-out writes.</param>
+    /// <param name="askTimeout">Ask timeout; defaults to 10s (the legacy lambda's value).</param>
+    public ActorNodeWriteGateway(Func<IActorRef?> resolveDriverHost, ILogger logger, TimeSpan? askTimeout = null)
+    {
+        _resolveDriverHost = resolveDriverHost ?? throw new ArgumentNullException(nameof(resolveDriverHost));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _askTimeout = askTimeout ?? DefaultAskTimeout;
+    }
+
+    /// <inheritdoc />
+    public async Task<NodeWriteOutcome> WriteAsync(string nodeId, object? value, CancellationToken ct)
+    {
+        var driverHost = _resolveDriverHost();
+        if (driverHost is null)
+        {
+            _logger.LogWarning("Inbound write to {NodeId} dropped: no DriverHostActor registered", nodeId);
+            return new NodeWriteOutcome(false, "writes unavailable");
+        }
+
+        try
+        {
+            var result = await driverHost.Ask<DriverHostActor.NodeWriteResult>(
+                new DriverHostActor.RouteNodeWrite(nodeId, value), _askTimeout, ct).ConfigureAwait(false);
+            if (!result.Success)
+                _logger.LogWarning("Operator write to {NodeId} rejected: {Reason}", nodeId, result.Reason);
+            return new NodeWriteOutcome(result.Success, result.Reason);
+        }
+        catch (Exception ex) // AskTimeoutException, actor faults, cancellation
+        {
+            _logger.LogWarning(ex, "Operator write to {NodeId} failed or timed out", nodeId);
+            return new NodeWriteOutcome(false, "write timeout");
+        }
+    }
+}