lmxopcua/src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/ActorNodeWriteGateway.cs

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
{

    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 <see cref="DriverWriteBounds.GatewayAsk"/> of
    /// <see cref="DriverWriteBounds.Default"/>. Production passes the GatewayAsk of the node's configured write
    /// bounds, so this Ask always outlasts the host's (lmxopcua#777) — an outer Ask that fires first reports the
    /// write failed, and the node reverts, while the device may still take the 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 ?? DriverWriteBounds.Default.GatewayAsk;
    }

    /// <inheritdoc />
    public async Task<NodeWriteOutcome> WriteAsync(string nodeId, object? value, AddressSpaceRealm realm, 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, realm), _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 (OperationCanceledException ex)
        {
            _logger.LogWarning(ex, "Operator write to {NodeId} cancelled", nodeId);
            return new NodeWriteOutcome(false, "write cancelled");
        }
        catch (AskTimeoutException ex)
        {
            _logger.LogWarning(ex, "Operator write to {NodeId} timed out", nodeId);
            return new NodeWriteOutcome(false, "write timeout");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Operator write to {NodeId} failed unexpectedly", nodeId);
            return new NodeWriteOutcome(false, "write error");
        }
    }
}