ScadaBridge/tests/ZB.MOM.WW.ScadaBridge.InboundAPI.Tests/RouteHelperTraceTests.cs

using NSubstitute;
using ZB.MOM.WW.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.InboundApi;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Debugging;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;

namespace ZB.MOM.WW.ScadaBridge.InboundAPI.Tests;

/// <summary>
/// Flow Debugger (design 2026-09-05 §5.1/§5.2/§7.1): <see cref="RouteTarget.Call"/> writes an
/// ALWAYS-ON <c>ScriptTrace.RouteCall</c> row (traced or not), propagates <c>Trace</c> on both
/// route requests, and feeds the row plus the reply's inline site events to the trace sink.
/// </summary>
public class RouteHelperTraceTests
{
    private readonly IInstanceLocator _locator = Substitute.For<IInstanceLocator>();
    private readonly IInstanceRouter _router = Substitute.For<IInstanceRouter>();
    private readonly List<AuditEvent> _written = new();
    private readonly ICentralAuditWriter _writer = Substitute.For<ICentralAuditWriter>();
    private readonly INodeIdentityProvider _node = Substitute.For<INodeIdentityProvider>();

    /// <summary>Wires the instance locator and audit writer doubles.</summary>
    public RouteHelperTraceTests()
    {
        _locator.GetSiteIdForInstanceAsync("inst-1", Arg.Any<CancellationToken>()).Returns("SiteA");
        _writer.WriteAsync(Arg.Do<AuditEvent>(e => _written.Add(e)), Arg.Any<CancellationToken>()).Returns(Task.CompletedTask);
        _node.NodeName.Returns("central-a");
    }

    private RouteHelper Helper() => new(_locator, _router, _writer, _node);

    private static AuditEvent SiteEvent(Guid exec) => ScadaBridgeAuditEventFactory.Create(
        AuditChannel.ScriptTrace, AuditKind.ScriptRun, AuditStatus.Delivered, executionId: exec, target: "doWork");

    /// <summary>Verifies that a route failure does not persist an echoed secret when body capture is disabled.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task EI2_RouteFailureWithBodyCaptureDisabled_DoesNotPersistEchoedSecret()
    {
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, false, null, "bad payload SECRET123", DateTimeOffset.UtcNow));
        await Assert.ThrowsAsync<InvalidOperationException>(() => Helper().WithBodyCapture(false).To("inst-1").Call("doWork", new { secret = "SECRET123" }));
        var row = Assert.Single(_written).AsRow();
        Assert.Equal(AuditStatus.Failed, row.Status);
        Assert.DoesNotContain("SECRET123", System.Text.Json.JsonSerializer.Serialize(row));
    }

    /// <summary>Verifies that a call writes a route-call row using the parent as execution id and the child id from the reply.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Call_WritesRouteCallRow_WithParentAsExecutionId_AndChildFromReply()
    {
        var parent = Guid.NewGuid();
        var child = Guid.NewGuid();
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, 99, null,
                DateTimeOffset.UtcNow, child, null));

        var result = await Helper().WithParentExecutionId(parent).To("inst-1").Call("doWork", new { x = 1 });

        Assert.Equal(99, result);
        var evt = Assert.Single(_written);
        var row = evt.AsRow();
        Assert.Equal("ScriptTrace.RouteCall", evt.Action);
        Assert.Equal("inbound-api", evt.Actor);
        Assert.Equal("inst-1.doWork", evt.Target);
        Assert.Equal("central-a", evt.SourceNode);
        Assert.Equal(parent, row.ExecutionId);
        Assert.Null(row.ParentExecutionId);
        Assert.Equal(AuditStatus.Delivered, row.Status);
        Assert.Equal(child, ScriptTraceExtra.TryParse(row.Extra)!.ChildExecutionId);
        Assert.Contains("\"x\":1", row.RequestSummary);
        Assert.Equal("99", row.ResponseSummary);
    }

    /// <summary>Verifies that the route-call row is always written, even when the run is not traced, and the request carries trace false.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Call_IsAlwaysOn_EvenWhenNotTraced_AndTraceFalseOnRequest()
    {
        RouteToCallRequest? captured = null;
        _router.RouteToCallAsync("SiteA", Arg.Do<RouteToCallRequest>(r => captured = r), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, null, null, DateTimeOffset.UtcNow));

        await Helper().To("inst-1").Call("doWork");

        Assert.False(captured!.Trace);
        Assert.Single(_written);
    }

    /// <summary>Verifies that enabling tracing propagates the trace flag to both the call and the set-attributes request.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task WithTrace_PropagatesOnCallAndSetAttributes()
    {
        RouteToCallRequest? call = null;
        RouteToSetAttributesRequest? set = null;
        _router.RouteToCallAsync("SiteA", Arg.Do<RouteToCallRequest>(r => call = r), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, null, null, DateTimeOffset.UtcNow));
        _router.RouteToSetAttributesAsync("SiteA", Arg.Do<RouteToSetAttributesRequest>(r => set = r), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToSetAttributesResponse(((RouteToSetAttributesRequest)ci[1]).CorrelationId, true, null, DateTimeOffset.UtcNow));

        var traced = Helper().WithTrace(true).WithDeadline(CancellationToken.None).To("inst-1");
        await traced.Call("doWork");
        await traced.SetAttributes(new Dictionary<string, string> { ["A"] = "1" });

        Assert.True(call!.Trace);
        Assert.True(set!.Trace);
    }

    /// <summary>Verifies that the sink receives the route-call row followed by the reply's trace events, in order.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Sink_ReceivesRouteCallRow_ThenTheReplysTraceEvents_InOrder()
    {
        var child = Guid.NewGuid();
        var siteEvents = new[] { SiteEvent(child), SiteEvent(child) };
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, null, null,
                DateTimeOffset.UtcNow, child, siteEvents));
        var sunk = new List<AuditEvent>();

        await Helper().WithTrace(true).WithTraceSink(sunk.Add).To("inst-1").Call("doWork");

        Assert.Equal(3, sunk.Count);
        Assert.Equal("ScriptTrace.RouteCall", sunk[0].Action);
        Assert.Same(siteEvents[0], sunk[1]);
        Assert.Same(siteEvents[1], sunk[2]);
    }

    /// <summary>
    /// Gitea #54: a routed reply carrying the site collector's truncation flags is forwarded to the
    /// truncation sink, and the sink survives the helper's clone chain (WithDeadline et al.).
    /// </summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task TruncationSink_ReceivesTheReplysSiteTruncationFlags_ThroughClones()
    {
        var child = Guid.NewGuid();
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, null, null,
                DateTimeOffset.UtcNow, child, [SiteEvent(child)], Truncated: false, LogsTruncated: true));
        var reports = new List<(bool, bool)>();

        await Helper()
            .WithTraceSink(_ => { }, (t, lt) => reports.Add((t, lt)))
            .WithTrace(true)
            .WithDeadline(CancellationToken.None)
            .WithSiteScope(null)
            .To("inst-1").Call("doWork");

        Assert.Equal([(false, true)], reports);
    }

    /// <summary>Gitea #54 control: an untruncated reply does not call the truncation sink.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task TruncationSink_IsNotCalled_ForAnUntruncatedReply()
    {
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, null, null,
                DateTimeOffset.UtcNow));
        var calls = 0;

        await Helper().WithTraceSink(_ => { }, (_, _) => calls++).To("inst-1").Call("doWork");

        Assert.Equal(0, calls);
    }

    /// <summary>Verifies that a routing failure writes a failed row and still throws.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Failure_WritesFailedRow_AndStillThrows()
    {
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, false, null, "script faulted", DateTimeOffset.UtcNow));

        await Assert.ThrowsAsync<InvalidOperationException>(() => Helper().To("inst-1").Call("doWork"));

        var row = Assert.Single(_written).AsRow();
        Assert.Equal(AuditStatus.Failed, row.Status);
        Assert.Equal("script faulted", row.ErrorMessage);
    }

    /// <summary>Verifies that with no writer and no sink nothing is written and no exception is thrown.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task NoWriterAndNoSink_WritesNothing_AndNeverThrows()
    {
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, 1, null, DateTimeOffset.UtcNow));

        var result = await new RouteHelper(_locator, _router).WithTrace(true).To("inst-1").Call("doWork");

        Assert.Equal(1, result);
        Assert.Empty(_written);
    }

    /// <summary>Verifies that a faulting audit writer does not fail the call.</summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task FaultingWriter_DoesNotFailTheCall()
    {
        var badWriter = Substitute.For<ICentralAuditWriter>();
        badWriter.WriteAsync(Arg.Any<AuditEvent>(), Arg.Any<CancellationToken>()).Returns(Task.FromException(new IOException("disk")));
        _router.RouteToCallAsync("SiteA", Arg.Any<RouteToCallRequest>(), Arg.Any<CancellationToken>())
            .Returns(ci => new RouteToCallResponse(((RouteToCallRequest)ci[1]).CorrelationId, true, 5, null, DateTimeOffset.UtcNow));

        var result = await new RouteHelper(_locator, _router, badWriter, null).To("inst-1").Call("doWork");
        Assert.Equal(5, result);
    }
}