scadalink-design/src/ScadaLink.StoreAndForward/NotificationForwarder.cs

using System.Text.Json;
using Akka.Actor;
using ScadaLink.Commons.Messages.Notification;

namespace ScadaLink.StoreAndForward;

/// <summary>
/// Notification Outbox: the site Store-and-Forward delivery handler for the
/// <see cref="ScadaLink.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;

    /// <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>
    public NotificationForwarder(
        IActorRef siteCommunicationActor,
        string sourceSiteId,
        TimeSpan forwardTimeout)
    {
        _siteCommunicationActor = siteCommunicationActor;
        _sourceSiteId = sourceSiteId;
        _forwardTimeout = forwardTimeout;
    }

    /// <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>
    public async Task<bool> DeliverAsync(StoreAndForwardMessage message)
    {
        // An unreadable payload cannot be fixed by retrying — park it (return false),
        // mirroring how the former SMTP handler treated a corrupt buffered payload.
        if (!TryBuildSubmit(message, out var submit))
        {
            return false;
        }

        // 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;
    }
}

/// <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
{
    public NotificationForwardException(string message) : base(message)
    {
    }
}