ScadaBridge/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/NotificationForwarder.cs

using System.Text.Json;
using Akka.Actor;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification;

namespace ZB.MOM.WW.ScadaBridge.StoreAndForward;

/// <summary>
/// Notification Outbox: the site Store-and-Forward delivery handler for the
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.StoreAndForwardCategory.Notification"/>
/// category.
///
/// In the outbox design the site no longer sends notification email itself.
/// "Delivering" a buffered notification means forwarding it to the central cluster
/// and treating central's <see cref="NotificationSubmitAck"/> as the outcome:
/// <list type="bullet">
///   <item><description>ack <c>Accepted</c> → <see cref="DeliverAsync"/> returns
///   <c>true</c>; the S&amp;F engine removes the message from the buffer.</description></item>
///   <item><description>ack not <c>Accepted</c>, or the Ask times out / fails →
///   <see cref="DeliverAsync"/> throws; the S&amp;F engine treats any thrown
///   exception as transient and retries the forward at the fixed interval.</description></item>
/// </list>
///
/// The forward travels over the ClusterClient command/control transport: the handler
/// <see cref="ActorRefImplicitSenderExtensions.Ask{T}(ICanTell, object, TimeSpan?)">Asks</see>
/// the site communication actor, which wraps the message in a
/// <c>ClusterClient.Send("/user/central-communication", …)</c> and routes central's
/// reply straight back to this Ask.
/// </summary>
public sealed class NotificationForwarder
{
    private readonly IActorRef _siteCommunicationActor;
    private readonly string _sourceSiteId;
    private readonly TimeSpan _forwardTimeout;
    private readonly ILogger<NotificationForwarder> _logger;

    /// <summary>
    /// Initializes a new <see cref="NotificationForwarder"/> that forwards buffered
    /// notifications to the central cluster via the site communication actor.
    /// </summary>
    /// <param name="siteCommunicationActor">
    /// The site communication actor. It forwards a <see cref="NotificationSubmit"/> to
    /// central via the registered ClusterClient and replies with the
    /// <see cref="NotificationSubmitAck"/>.
    /// </param>
    /// <param name="sourceSiteId">This site's identifier, stamped on every submit.</param>
    /// <param name="forwardTimeout">
    /// How long to wait for central's ack before treating the forward as a transient
    /// failure. Sourced from host configuration.
    /// </param>
    /// <param name="logger">
    /// Optional logger. StoreAndForward-018: a corrupt buffered payload is logged at
    /// Warning before being discarded so an operator has a forensic trail of the row
    /// that vanished from the buffer.
    /// </param>
    public NotificationForwarder(
        IActorRef siteCommunicationActor,
        string sourceSiteId,
        TimeSpan forwardTimeout,
        ILogger<NotificationForwarder>? logger = null)
    {
        _siteCommunicationActor = siteCommunicationActor;
        _sourceSiteId = sourceSiteId;
        _forwardTimeout = forwardTimeout;
        _logger = logger ?? NullLogger<NotificationForwarder>.Instance;
    }

    /// <summary>
    /// Store-and-Forward delivery handler entry point — matches the
    /// <c>Func&lt;StoreAndForwardMessage, Task&lt;bool&gt;&gt;</c> handler contract.
    /// Returns <c>true</c> when central accepts the notification; throws on a
    /// non-accepted ack or an Ask timeout/failure so the engine retries.
    /// </summary>
    /// <param name="message">The buffered store-and-forward message to deliver to central.</param>
    /// <returns>A task that resolves to <c>true</c> when central accepts (or the payload is corrupt and discarded); throws on a transient forward failure so the engine retries.</returns>
    public async Task<bool> DeliverAsync(StoreAndForwardMessage message)
    {
        // StoreAndForward-018: an unreadable payload cannot be fixed by retrying.
        // The design doc explicitly forbids parking notifications ("notifications do
        // not park — they are retried at the fixed forward interval until central
        // acks"; Component-StoreAndForward.md). The earlier behaviour returned false
        // here, which the S&F engine interprets as a permanent failure and parks
        // the row — contradicting the invariant and surfacing the row in the
        // central UI's parked-message list. The correct outcome for a corrupt-payload
        // notification is to DISCARD: log a Warning with the buffered row id +
        // payload preview for forensics, then return true so the engine clears the
        // buffer via its standard success-path cleanup. The buffered row is
        // unrecoverable; retrying or parking would both make the queue worse, not
        // better.
        if (!TryBuildSubmit(message, out var submit))
        {
            _logger.LogWarning(
                "Discarding corrupt buffered notification {NotificationId} (payload is not deserialisable as NotificationSubmit). " +
                "Payload preview: {PayloadPreview}",
                message.Id,
                PreviewPayload(message.PayloadJson));
            return true;
        }

        // The reply may legitimately be a non-accepted ack, so it is not requested as
        // a status-failing Ask: ask for the bare NotificationSubmitAck and classify it
        // here. An Ask timeout surfaces as a TimeoutException, which — like any other
        // thrown exception — the S&F engine treats as transient.
        var ack = await _siteCommunicationActor
            .Ask<NotificationSubmitAck>(submit, _forwardTimeout)
            .ConfigureAwait(false);

        if (ack.Accepted)
        {
            return true;
        }

        // A non-accepted ack is a transient failure: central could not persist the
        // notification right now. Throw so the engine keeps buffering and retries.
        throw new NotificationForwardException(
            $"Central rejected notification {submit.NotificationId}: {ack.Error ?? "no detail"}");
    }

    /// <summary>
    /// Maps a buffered S&amp;F notification message onto the <see cref="NotificationSubmit"/>
    /// forwarded to central, returning <c>false</c> if the payload is unreadable.
    ///
    /// The buffered payload IS a serialized <see cref="NotificationSubmit"/> written by
    /// the site <c>Notify.Send</c> enqueue path (Task 19). Its
    /// <see cref="NotificationSubmit.NotificationId"/> is the central idempotency key —
    /// it was generated by the script, equals the buffered row's
    /// <see cref="StoreAndForwardMessage.Id"/>, and is stable across every retry. The
    /// forwarder forwards the payload as-is except that it re-stamps the fields it
    /// authoritatively owns: <see cref="NotificationSubmit.SourceSiteId"/> (this site's
    /// id) and <see cref="NotificationSubmit.SourceInstanceId"/> (the buffered row's
    /// origin instance), and it falls the list name back to the S&amp;F
    /// <see cref="StoreAndForwardMessage.Target"/> when the payload list name is blank.
    /// </summary>
    private bool TryBuildSubmit(StoreAndForwardMessage message, out NotificationSubmit submit)
    {
        submit = null!;

        NotificationSubmit? payload;
        try
        {
            payload = JsonSerializer.Deserialize<NotificationSubmit>(message.PayloadJson);
        }
        catch (JsonException)
        {
            return false;
        }

        if (payload == null)
        {
            return false;
        }

        submit = payload with
        {
            // The NotificationId is the script-generated idempotency key carried in the
            // payload. Defend against a payload missing it by falling back to the
            // buffered row id, which the enqueue path pins to the same value.
            NotificationId = string.IsNullOrEmpty(payload.NotificationId)
                ? message.Id
                : payload.NotificationId,
            // A null OR empty/blank ListName falls back to the S&F Target — so an empty
            // list name is never forwarded to central.
            ListName = string.IsNullOrEmpty(payload.ListName) ? message.Target : payload.ListName,
            // SourceSiteId/SourceInstanceId are authoritatively owned by the site: the
            // forwarder knows the real site id, and the buffered row records the origin
            // instance even after the instance is deleted.
            SourceSiteId = _sourceSiteId,
            SourceInstanceId = message.OriginInstanceName,
        };
        return true;
    }

    private const int CorruptPayloadPreviewMaxLength = 200;

    /// <summary>
    /// Returns a length-capped preview of a corrupt buffered payload for the Warning
    /// log line emitted on discard. The full payload may be megabytes and is not
    /// suitable for the structured log; the preview retains the leading characters,
    /// which is what an operator typically uses to identify the producing script.
    /// </summary>
    private static string PreviewPayload(string? payloadJson)
    {
        if (string.IsNullOrEmpty(payloadJson))
        {
            return "<empty>";
        }
        return payloadJson.Length <= CorruptPayloadPreviewMaxLength
            ? payloadJson
            : payloadJson.Substring(0, CorruptPayloadPreviewMaxLength) + "…";
    }
}

/// <summary>
/// Raised by <see cref="NotificationForwarder"/> on a transient forward failure —
/// a non-accepted central ack. The Store-and-Forward engine treats any thrown
/// exception as transient and retries the forward at the fixed interval.
/// </summary>
public sealed class NotificationForwardException : Exception
{
    /// <summary>
    /// Initializes a new exception with the specified message.
    /// </summary>
    /// <param name="message">Message describing the forward failure.</param>
    public NotificationForwardException(string message) : base(message)
    {
    }
}