feat(wire): attribute updates carry source_execution_id/trace; PullTraceEvents RPC + site read-by-execution-ids

Flow Debugger (design 2026-09-05 §5.3/§5.4): AttributeValueUpdate fields 7/8 stamped by StreamRelayActor and parsed by SiteStreamGrpcClient (older frames => null/false). New PullTraceEvents unary RPC on SiteStreamService (same PSK-gated prefix as PullAuditEvents): a point read of the site audit SQLite by ExecutionId OR ParentExecutionId (ISiteAuditQueue.ReadByExecutionIdsAsync, json_extract on the codec's camelCase keys, new IX_audit_event_occurred index, 64-id / 2000-row caps) that moves no cursor and flips no ForwardState. Central IPullTraceEventsClient/GrpcPullTraceEventsClient mirror the audit pull client (endpoint resolution, NodeB failover, fault => empty) and register beside it. Claude-Session: https://claude.ai/code/session_01GSLkkHKz9JrAtmJjmQK3cP
2026-09-05 23:52:50 -04:00
parent f15d0db0ad
commit 7e61552d82
15 changed files with 1458 additions and 80 deletions
@@ -127,6 +127,10 @@ public class SiteAuditRetentionServiceTests
    /// <summary>Stub queue that records purge cutoffs and can throw on the first tick.</summary>
    private sealed class RecordingSiteAuditQueue : ISiteAuditQueue
    {
+        public Task<IReadOnlyList<AuditEvent>> ReadByExecutionIdsAsync(
+            IReadOnlyCollection<Guid> executionIds, DateTime sinceUtc, int limit, CancellationToken ct = default)
+            => throw new NotSupportedException("not exercised by the retention service");
+
        private readonly ConcurrentQueue<DateTime> _purgeCalls = new();
        private int _calls;

@@ -0,0 +1,83 @@
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.ScadaBridge.AuditLog.Site;
+using ZB.MOM.WW.ScadaBridge.AuditLog.Tests.TestSupport;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
+
+namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Site;
+
+/// <summary>
+/// Flow Debugger (design 2026-09-05 §5.4): <see cref="SqliteAuditWriter.ReadByExecutionIdsAsync"/>
+/// matches on ExecutionId OR ParentExecutionId, honours the since bound, orders by
+/// (OccurredAtUtc, EventId), caps the row count, and is independent of forwarding state.
+/// </summary>
+public class SqliteAuditWriterReadByExecutionTests : IDisposable
+{
+    private readonly string _dbPath = Path.Combine(Path.GetTempPath(), $"audit-readbyexec-{Guid.NewGuid():N}.db");
+    private static readonly DateTime T0 = new(2026, 9, 5, 12, 0, 0, DateTimeKind.Utc);
+
+    public void Dispose()
+    {
+        if (File.Exists(_dbPath)) { try { File.Delete(_dbPath); } catch { /* best-effort */ } }
+    }
+
+    private SqliteAuditWriter CreateWriter() => new(
+        Options.Create(new SqliteAuditWriterOptions { DatabasePath = _dbPath }),
+        NullLogger<SqliteAuditWriter>.Instance,
+        new FakeNodeIdentityProvider());
+
+    private static AuditEvent Row(DateTime at, Guid? exec, Guid? parent, AuditKind kind = AuditKind.ScriptRun) =>
+        ScadaBridgeAuditEventFactory.Create(AuditChannel.ScriptTrace, kind, AuditStatus.Delivered,
+            occurredAtUtc: at, executionId: exec, parentExecutionId: parent, sourceSiteId: "site-a");
+
+    [Fact]
+    public async Task MatchesExecutionId_OrParentExecutionId_OrderedAndBounded()
+    {
+        var root = Guid.NewGuid();
+        var child = Guid.NewGuid();
+        var unrelated = Guid.NewGuid();
+        var rows = new[]
+        {
+            Row(T0.AddSeconds(3), child, root, AuditKind.AttributeWrite),   // parent match
+            Row(T0.AddSeconds(1), root, null),                               // exec match
+            Row(T0.AddSeconds(2), child, root),                              // parent match
+            Row(T0.AddSeconds(4), unrelated, null),                          // no match
+            Row(T0.AddSeconds(-60), root, null),                             // before since
+        };
+
+        await using (var writer = CreateWriter())
+        {
+            foreach (var r in rows) await writer.WriteAsync(r);
+
+            var hits = await writer.ReadByExecutionIdsAsync([root], T0, limit: 100);
+            Assert.Equal(3, hits.Count);
+            Assert.Equal(rows[1].EventId, hits[0].EventId);
+            Assert.Equal(rows[2].EventId, hits[1].EventId);
+            Assert.Equal(rows[0].EventId, hits[2].EventId);
+            Assert.Equal(rows[1], hits[0]);
+
+            // Bounded.
+            var two = await writer.ReadByExecutionIdsAsync([root], T0, limit: 2);
+            Assert.Equal(2, two.Count);
+
+            // Forwarding state is irrelevant: mark everything Reconciled, still served.
+            await writer.MarkReconciledAsync(rows.Select(r => r.EventId).ToList());
+            Assert.Equal(3, (await writer.ReadByExecutionIdsAsync([root], T0, limit: 100)).Count);
+
+            // Empty id set → empty; multiple ids union.
+            Assert.Empty(await writer.ReadByExecutionIdsAsync(Array.Empty<Guid>(), T0, 10));
+            Assert.Equal(4, (await writer.ReadByExecutionIdsAsync([root, unrelated], T0, 100)).Count);
+        }
+    }
+
+    [Fact]
+    public async Task Guards_LimitAndIdCap()
+    {
+        await using var writer = CreateWriter();
+        await Assert.ThrowsAsync<ArgumentOutOfRangeException>(() => writer.ReadByExecutionIdsAsync([Guid.NewGuid()], T0, 0));
+        var tooMany = Enumerable.Range(0, SqliteAuditWriter.MaxExecutionIdsPerRead + 1).Select(_ => Guid.NewGuid()).ToList();
+        await Assert.ThrowsAsync<ArgumentOutOfRangeException>(() => writer.ReadByExecutionIdsAsync(tooMany, T0, 10));
+    }
+}
@@ -0,0 +1,125 @@
+using Akka.TestKit.Xunit2;
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using Microsoft.Extensions.Logging.Abstractions;
+using NSubstitute;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
+using ZB.MOM.WW.ScadaBridge.Communication.Grpc;
+
+namespace ZB.MOM.WW.ScadaBridge.Communication.Tests;
+
+/// <summary>
+/// Flow Debugger (design 2026-09-05 §5.4): <see cref="SiteStreamGrpcServer.PullTraceEvents"/>
+/// — request validation, the queue point-read, DTO projection, and the guarantee that it is
+/// NOT a reconciliation path (no cursor flip). Also pins that the RPC sits under the
+/// PSK-gated <c>/sitestream.SiteStreamService/</c> prefix.
+/// </summary>
+public class SiteStreamPullTraceEventsTests : TestKit
+{
+    private readonly ISiteStreamSubscriber _subscriber = Substitute.For<ISiteStreamSubscriber>();
+
+    private SiteStreamGrpcServer CreateServer() => new(_subscriber, NullLogger<SiteStreamGrpcServer>.Instance);
+
+    private static ServerCallContext NewContext()
+    {
+        var context = Substitute.For<ServerCallContext>();
+        context.CancellationToken.Returns(CancellationToken.None);
+        return context;
+    }
+
+    private static AuditEvent Row(Guid executionId) => ScadaBridgeAuditEventFactory.Create(
+        AuditChannel.ScriptTrace, AuditKind.ScriptRun, AuditStatus.Delivered,
+        occurredAtUtc: new DateTime(2026, 9, 5, 12, 0, 0, DateTimeKind.Utc), executionId: executionId, sourceSiteId: "site-a");
+
+    [Fact]
+    public void PullTraceEvents_IsUnderThePskGatedServicePrefix()
+    {
+        var method = SiteStreamService.Descriptor.FindMethodByName("PullTraceEvents");
+        Assert.NotNull(method);
+        Assert.Equal("sitestream.SiteStreamService", SiteStreamService.Descriptor.FullName);
+    }
+
+    [Fact]
+    public async Task NoQueueWired_ReturnsEmpty()
+    {
+        var response = await CreateServer().PullTraceEvents(new PullTraceEventsRequest
+        {
+            ExecutionIds = { Guid.NewGuid().ToString("D") }, MaxEvents = 10,
+        }, NewContext());
+        Assert.Empty(response.Events);
+    }
+
+    [Fact]
+    public async Task ReadsByIds_ProjectsDtos_AndNeverFlipsState()
+    {
+        var queue = Substitute.For<ISiteAuditQueue>();
+        var id = Guid.NewGuid();
+        var rows = new List<AuditEvent> { Row(id), Row(id) };
+        IReadOnlyCollection<Guid>? seenIds = null;
+        DateTime seenSince = default;
+        int seenLimit = 0;
+        queue.ReadByExecutionIdsAsync(
+                Arg.Do<IReadOnlyCollection<Guid>>(x => seenIds = x), Arg.Do<DateTime>(x => seenSince = x),
+                Arg.Do<int>(x => seenLimit = x), Arg.Any<CancellationToken>())
+            .Returns((IReadOnlyList<AuditEvent>)rows);
+        var server = CreateServer();
+        server.SetSiteAuditQueue(queue);
+        var since = new DateTime(2026, 9, 5, 11, 0, 0, DateTimeKind.Utc);
+
+        var response = await server.PullTraceEvents(new PullTraceEventsRequest
+        {
+            ExecutionIds = { id.ToString("D") }, SinceUtc = Timestamp.FromDateTime(since), MaxEvents = 500,
+        }, NewContext());
+
+        Assert.Equal(2, response.Events.Count);
+        Assert.Equal(rows[0].EventId.ToString(), response.Events[0].EventId);
+        Assert.Equal(new[] { id }, seenIds);
+        Assert.Equal(since, seenSince);
+        Assert.Equal(500, seenLimit);
+        await queue.DidNotReceiveWithAnyArgs().MarkReconciledUpToAsync(default, default, default);
+        await queue.DidNotReceiveWithAnyArgs().MarkReconciledAsync(default!, default);
+    }
+
+    [Theory]
+    [InlineData(0, 1)]
+    [InlineData(2001, 1)]
+    [InlineData(10, 0)]
+    [InlineData(10, 65)]
+    public async Task InvalidArguments_AreRejected(int maxEvents, int idCount)
+    {
+        var server = CreateServer();
+        server.SetSiteAuditQueue(Substitute.For<ISiteAuditQueue>());
+        var request = new PullTraceEventsRequest { MaxEvents = maxEvents };
+        for (var i = 0; i < idCount; i++) request.ExecutionIds.Add(Guid.NewGuid().ToString("D"));
+
+        var ex = await Assert.ThrowsAsync<RpcException>(() => server.PullTraceEvents(request, NewContext()));
+        Assert.Equal(StatusCode.InvalidArgument, ex.StatusCode);
+    }
+
+    [Fact]
+    public async Task NonGuidId_IsRejected()
+    {
+        var server = CreateServer();
+        server.SetSiteAuditQueue(Substitute.For<ISiteAuditQueue>());
+        var ex = await Assert.ThrowsAsync<RpcException>(() => server.PullTraceEvents(
+            new PullTraceEventsRequest { ExecutionIds = { "nope" }, MaxEvents = 10 }, NewContext()));
+        Assert.Equal(StatusCode.InvalidArgument, ex.StatusCode);
+    }
+
+    [Fact]
+    public async Task QueueFault_CollapsesToEmpty()
+    {
+        var queue = Substitute.For<ISiteAuditQueue>();
+        queue.ReadByExecutionIdsAsync(default!, default, default, default)
+            .ReturnsForAnyArgs<IReadOnlyList<AuditEvent>>(_ => throw new InvalidOperationException("boom"));
+        var server = CreateServer();
+        server.SetSiteAuditQueue(queue);
+
+        var response = await server.PullTraceEvents(
+            new PullTraceEventsRequest { ExecutionIds = { Guid.NewGuid().ToString("D") }, MaxEvents = 10 }, NewContext());
+        Assert.Empty(response.Events);
+    }
+}
@@ -0,0 +1,76 @@
+using System.Threading.Channels;
+using Akka.Actor;
+using Akka.TestKit.Xunit2;
+using Google.Protobuf.WellKnownTypes;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming;
+using ZB.MOM.WW.ScadaBridge.Communication.Actors;
+using ZB.MOM.WW.ScadaBridge.Communication.Grpc;
+
+namespace ZB.MOM.WW.ScadaBridge.Communication.Tests;
+
+/// <summary>
+/// Flow Debugger (design 2026-09-05 §5.3/§5.4): <c>AttributeValueUpdate</c> fields 7/8 —
+/// <see cref="StreamRelayActor"/> stamps <c>source_execution_id</c>/<c>trace</c> on the way
+/// out and <see cref="SiteStreamGrpcClient"/> parses them back; an unstamped change (and an
+/// older site's frame) round-trips to null/false.
+/// </summary>
+public class StreamRelayTraceStampTests : TestKit
+{
+    private static SiteStreamEvent Relay(AttributeValueChanged change, ActorSystem sys)
+    {
+        var channel = Channel.CreateUnbounded<SiteStreamEvent>();
+        var actor = sys.ActorOf(Props.Create(() => new StreamRelayActor("corr", channel.Writer)));
+        actor.Tell(change);
+        SiteStreamEvent? evt = null;
+        for (var i = 0; i < 40 && !channel.Reader.TryRead(out evt); i++) Thread.Sleep(50);
+        Assert.NotNull(evt);
+        return evt!;
+    }
+
+    [Fact]
+    public void TracedChange_IsStampedOnTheWire_AndParsedBack()
+    {
+        var source = Guid.NewGuid();
+        var now = new DateTimeOffset(2026, 9, 5, 12, 0, 0, TimeSpan.Zero);
+        var change = new AttributeValueChanged("P1", "Status", "Status", "Running", "Good", now, SourceExecutionId: source, Trace: true);
+
+        var evt = Relay(change, Sys);
+        Assert.Equal(source.ToString("D"), evt.AttributeChanged.SourceExecutionId);
+        Assert.True(evt.AttributeChanged.Trace);
+
+        var back = Assert.IsType<AttributeValueChanged>(SiteStreamGrpcClient.ConvertToDomainEvent(evt));
+        Assert.Equal(source, back.SourceExecutionId);
+        Assert.True(back.Trace);
+    }
+
+    [Fact]
+    public void UnstampedChange_RoundTripsToNullAndFalse()
+    {
+        var change = new AttributeValueChanged("P1", "Status", "Status", "Idle", "Good", DateTimeOffset.UtcNow);
+
+        var evt = Relay(change, Sys);
+        Assert.Equal(string.Empty, evt.AttributeChanged.SourceExecutionId);
+        Assert.False(evt.AttributeChanged.Trace);
+
+        var back = Assert.IsType<AttributeValueChanged>(SiteStreamGrpcClient.ConvertToDomainEvent(evt));
+        Assert.Null(back.SourceExecutionId);
+        Assert.False(back.Trace);
+    }
+
+    [Fact]
+    public void OlderSiteFrame_WithoutTheFields_ParsesToNullAndFalse()
+    {
+        var evt = new SiteStreamEvent
+        {
+            CorrelationId = "c",
+            AttributeChanged = new AttributeValueUpdate
+            {
+                InstanceUniqueName = "P1", AttributePath = "A", AttributeName = "A", Value = "1",
+                Quality = Quality.Good, Timestamp = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+            },
+        };
+        var back = Assert.IsType<AttributeValueChanged>(SiteStreamGrpcClient.ConvertToDomainEvent(evt));
+        Assert.Null(back.SourceExecutionId);
+        Assert.False(back.Trace);
+    }
+}