dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(siteruntime): emit NotifySend(Submitted) on site-side Notify.To().Send (#23 M4)

Browse Source 
Audit Log #23 M4 Bundle C — Task C1: every script-initiated
Notify.To(list).Send(...) now emits exactly one
Notification/NotifySend audit row via the IAuditWriter wired through
ScriptRuntimeContext. The row carries Status=Submitted,
Target=list name, RequestSummary={subject,body} JSON (M5 will redact),
CorrelationId=NotificationId (parsed as Guid), provenance from context,
ForwardState=Pending.

Emission is best-effort per alog.md §7: a thrown audit writer is logged
and swallowed inside the helper; the original NotificationId still flows
back to the script and the underlying S&F enqueue still happened.

Mirrors the M2 Bundle F ExternalSystem.Call wrapper pattern.

Tests: 7 new tests in NotifySendAuditEmissionTests covering submitted-
status, list-name target, request-summary JSON shape, writer-throws
fail-safe, provenance, NotificationId/CorrelationId round-trip, and the
null-writer degrade path.
This commit is contained in:
Joseph Doherty
2026-05-20 16:18:46 -04:00
parent 6de377a39e
commit 855df759b5
2 changed files with 392 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
src/ScadaLink.SiteRuntime/Scripts/ScriptRuntimeContext.cs
View File

@@ -272,8 +272,16 @@ public class ScriptRuntimeContext
/// for central delivery and returns its <c>NotificationId</c>;
/// <c>Notify.Status(id)</c> queries the delivery status of that notification.
/// </summary>
/// <remarks>
/// Audit Log #23 (M4 Bundle C): the <see cref="IAuditWriter"/> is threaded
/// through so <c>Notify.To(list).Send(...)</c> emits one
/// <c>Notification</c>/<c>NotifySend</c> audit row per accepted submission.
/// Best-effort per alog.md §7 — a thrown writer never aborts the script's
/// <c>Send</c>.
/// </remarks>
public NotifyHelper Notify => new(
_storeAndForward, _siteCommunicationActor, _siteId, _instanceName, _sourceScript, _askTimeout, _logger);
_storeAndForward, _siteCommunicationActor, _siteId, _instanceName, _sourceScript, _askTimeout, _logger,
_auditWriter);
/// <summary>
/// Audit Log #23 (M3): site-local tracking-status API for cached operations.
@@ -1090,6 +1098,16 @@ public class ScriptRuntimeContext
private readonly TimeSpan _askTimeout;
private readonly ILogger _logger;
/// <summary>
/// Audit Log #23 (M4 Bundle C): best-effort emitter for the
/// <c>Notification</c>/<c>NotifySend</c> row produced when the script
/// calls <c>Notify.To(list).Send(...)</c>. Optional — when null the
/// <see cref="NotifyTarget"/> degrades to a no-op audit path so tests
/// / minimal hosts that don't wire AddAuditLog still work (mirrors the
/// M2 Bundle F <c>IExternalSystemClient</c> wrapper).
/// </summary>
private readonly IAuditWriter? _auditWriter;
internal NotifyHelper(
StoreAndForwardService? storeAndForward,
ICanTell? siteCommunicationActor,
@@ -1097,7 +1115,8 @@ public class ScriptRuntimeContext
string instanceName,
string? sourceScript,
TimeSpan askTimeout,
ILogger logger)
ILogger logger,
IAuditWriter? auditWriter = null)
{
_storeAndForward = storeAndForward;
_siteCommunicationActor = siteCommunicationActor;
@@ -1106,6 +1125,7 @@ public class ScriptRuntimeContext
_sourceScript = sourceScript;
_askTimeout = askTimeout;
_logger = logger;
_auditWriter = auditWriter;
}
/// <summary>
@@ -1114,7 +1134,10 @@ public class ScriptRuntimeContext
public NotifyTarget To(string listName)
{
return new NotifyTarget(
listName, _storeAndForward, _siteId, _instanceName, _sourceScript, _logger);
listName, _storeAndForward, _siteId, _instanceName, _sourceScript, _logger,
// Audit Log #23 (M4 Bundle C): forward the writer so Send()
// can emit one NotifySend(Submitted) row per accepted submission.
_auditWriter);
}
/// <summary>
@@ -1189,13 +1212,22 @@ public class ScriptRuntimeContext
private readonly string? _sourceScript;
private readonly ILogger _logger;
/// <summary>
/// Audit Log #23 (M4 Bundle C): best-effort emitter for the
/// <c>Notification</c>/<c>NotifySend</c> row written immediately after
/// the underlying S&amp;F enqueue accepts the submission. Optional —
/// when null no audit row is emitted (no-op path).
/// </summary>
private readonly IAuditWriter? _auditWriter;
internal NotifyTarget(
string listName,
StoreAndForwardService? storeAndForward,
string siteId,
string instanceName,
string? sourceScript,
ILogger logger)
ILogger logger,
IAuditWriter? auditWriter = null)
{
_listName = listName;
_storeAndForward = storeAndForward;
@@ -1203,6 +1235,7 @@ public class ScriptRuntimeContext
_instanceName = instanceName;
_sourceScript = sourceScript;
_logger = logger;
_auditWriter = auditWriter;
}
/// <summary>
@@ -1251,6 +1284,7 @@ public class ScriptRuntimeContext
// The S&F engine assigns its own GUID to the message; pin the message id to
// the NotificationId so the buffer can be queried by it (Notify.Status) and
// the forwarder's idempotency key matches the buffered row.
var occurredAtUtc = DateTime.UtcNow;
await _storeAndForward.EnqueueAsync(
StoreAndForwardCategory.Notification,
target: _listName,
@@ -1262,8 +1296,125 @@ public class ScriptRuntimeContext
"Notify enqueued notification {NotificationId} to list '{List}' for central delivery",
notificationId, _listName);
// Audit Log #23 (M4 Bundle C): emit one Notification/NotifySend
// (Submitted) row per accepted submission. The emission is wired
// AFTER the EnqueueAsync returns so we only audit submissions the
// S&F engine accepted — a failed enqueue throws, never produces an
// audit row (mirrors ESG: audit fires after the boundary call
// returned a result, never speculatively). Best-effort per alog.md
// §7 — the audit write is wrapped in try/catch and any failure is
// logged + swallowed so the script's Send call still returns the
// NotificationId.
EmitNotifySendAudit(notificationId, subject, message, occurredAtUtc);
return notificationId;
}
/// <summary>
/// Best-effort emission of one <c>Notification</c>/<c>NotifySend</c>
/// (Status <c>Submitted</c>) audit row. Any exception thrown by the
/// writer is logged and swallowed — audit-write failures must never
/// abort the user-facing <c>Notify.Send</c> call (alog.md §7).
/// </summary>
private void EmitNotifySendAudit(
string notificationId,
string subject,
string body,
DateTime occurredAtUtc)
{
if (_auditWriter == null)
{
return;
}
AuditEvent evt;
try
{
// CorrelationId is the NotificationId parsed as a Guid. Notify
// mints the id via Guid.NewGuid().ToString("N") so the parse
// is expected to succeed; on the off-chance the format
// changes / a caller injects an unparseable value, leave it
// null per Bundle B's pattern rather than fail the emission.
Guid? correlationId = Guid.TryParse(notificationId, out var parsed) ? parsed : (Guid?)null;
// M4 captures the request summary verbatim — {"subject": "...", "body": "..."}.
// M5 will layer redaction / payload-cap enforcement on top.
var requestSummary = JsonSerializer.Serialize(new
{
subject = subject,
body = body,
});
evt = new AuditEvent
{
EventId = Guid.NewGuid(),
OccurredAtUtc = DateTime.SpecifyKind(occurredAtUtc, DateTimeKind.Utc),
Channel = AuditChannel.Notification,
Kind = AuditKind.NotifySend,
CorrelationId = correlationId,
SourceSiteId = string.IsNullOrEmpty(_siteId) ? null : _siteId,
SourceInstanceId = _instanceName,
SourceScript = _sourceScript,
Actor = null,
Target = _listName,
Status = AuditStatus.Submitted,
HttpStatus = null,
// Send is fire-and-forget from the script's perspective —
// the dispatcher (NotificationOutboxActor) times each
// delivery attempt and stamps DurationMs on its
// NotifyDeliver(Attempted) rows.
DurationMs = null,
ErrorMessage = null,
ErrorDetail = null,
RequestSummary = requestSummary,
ResponseSummary = null,
PayloadTruncated = false,
Extra = null,
ForwardState = AuditForwardState.Pending,
};
}
catch (Exception buildEx)
{
// Defensive: building the event itself must never propagate.
_logger.LogWarning(buildEx,
"Failed to build Audit Log #23 NotifySend event for NotificationId {NotificationId} list '{List}' — skipping emission",
notificationId, _listName);
return;
}
try
{
// Fire-and-forget (mirrors ExternalSystemHelper.EmitCallAudit)
// so the script is never blocked on the audit writer; we observe
// failures via ContinueWith so a thrown writer is logged rather
// than going to the unobserved-task firehose.
var writeTask = _auditWriter.WriteAsync(evt, CancellationToken.None);
if (!writeTask.IsCompleted)
{
writeTask.ContinueWith(
t => _logger.LogWarning(t.Exception,
"Audit Log #23 write failed for EventId {EventId} (NotifySend NotificationId {NotificationId})",
evt.EventId, notificationId),
CancellationToken.None,
TaskContinuationOptions.OnlyOnFaulted | TaskContinuationOptions.ExecuteSynchronously,
TaskScheduler.Default);
}
else if (writeTask.IsFaulted)
{
_logger.LogWarning(writeTask.Exception,
"Audit Log #23 write failed for EventId {EventId} (NotifySend NotificationId {NotificationId})",
evt.EventId, notificationId);
}
}
catch (Exception writeEx)
{
// Synchronous throw from WriteAsync (e.g. ArgumentNullException
// before the writer's own try/catch). Swallow + log per alog.md §7.
_logger.LogWarning(writeEx,
"Audit Log #23 write threw synchronously for EventId {EventId} (NotifySend NotificationId {NotificationId})",
evt.EventId, notificationId);
}
}
}
/// <summary>

237
tests/ScadaLink.SiteRuntime.Tests/Scripts/NotifySendAuditEmissionTests.cs Normal file
View File

@@ -0,0 +1,237 @@
using System.Text.Json;
using Akka.Actor;
using Akka.TestKit.Xunit2;
using Microsoft.Data.Sqlite;
using Microsoft.Extensions.Logging.Abstractions;
using ScadaLink.Commons.Entities.Audit;
using ScadaLink.Commons.Interfaces.Services;
using ScadaLink.Commons.Types.Enums;
using ScadaLink.SiteRuntime.Scripts;
using ScadaLink.StoreAndForward;
namespace ScadaLink.SiteRuntime.Tests.Scripts;
/// <summary>
/// Audit Log #23 — M4 Bundle C (Task C1): every script-initiated
/// <c>Notify.To("list").Send(...)</c> emits exactly one
/// <c>Notification</c>/<c>NotifySend</c> audit event via the wrapper inside
/// <see cref="ScriptRuntimeContext.NotifyTarget"/>. The audit emission is
/// best-effort: a thrown <see cref="IAuditWriter.WriteAsync"/> must never
/// abort the script's <c>Send</c> — the original <c>NotificationId</c> must
/// still flow back to the caller and the underlying S&amp;F enqueue must still
/// have happened.
/// </summary>
public class NotifySendAuditEmissionTests : TestKit, IAsyncLifetime, IDisposable
{
/// <summary>
/// In-memory <see cref="IAuditWriter"/> that records every event passed to
/// <see cref="WriteAsync"/>. Optionally configurable to throw, simulating a
/// catastrophic audit-writer failure that the wrapper must swallow per
/// alog.md §7.
/// </summary>
private sealed class CapturingAuditWriter : IAuditWriter
{
public List<AuditEvent> Events { get; } = new();
public Exception? ThrowOnWrite { get; set; }
public Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
{
if (ThrowOnWrite != null)
{
return Task.FromException(ThrowOnWrite);
}
Events.Add(evt);
return Task.CompletedTask;
}
}
private const string SiteId = "site-7";
private const string InstanceName = "Plant.Pump3";
private const string SourceScript = "ScriptActor:CheckPressure";
private const string ListName = "Operators";
private const string Subject = "Pump alarm";
private const string Body = "Pump 3 tripped";
private readonly SqliteConnection _keepAlive;
private readonly StoreAndForwardStorage _storage;
private readonly StoreAndForwardService _saf;
public NotifySendAuditEmissionTests()
{
var dbName = $"NotifySendAudit_{Guid.NewGuid():N}";
var connStr = $"Data Source={dbName};Mode=Memory;Cache=Shared";
_keepAlive = new SqliteConnection(connStr);
_keepAlive.Open();
_storage = new StoreAndForwardStorage(connStr, NullLogger<StoreAndForwardStorage>.Instance);
var options = new StoreAndForwardOptions
{
DefaultRetryInterval = TimeSpan.Zero,
DefaultMaxRetries = 3,
RetryTimerInterval = TimeSpan.FromMinutes(10)
};
_saf = new StoreAndForwardService(_storage, options, NullLogger<StoreAndForwardService>.Instance);
}
public async Task InitializeAsync() => await _storage.InitializeAsync();
public Task DisposeAsync() => Task.CompletedTask;
protected override void Dispose(bool disposing)
{
if (disposing)
{
_keepAlive.Dispose();
}
base.Dispose(disposing);
}
private ScriptRuntimeContext.NotifyHelper CreateHelper(
IAuditWriter? auditWriter,
string? sourceScript = SourceScript)
{
// siteCommunicationActor is unused by Send — pass a probe so the helper
// is fully constructed.
var probe = CreateTestProbe();
return new ScriptRuntimeContext.NotifyHelper(
_saf,
probe.Ref,
SiteId,
InstanceName,
sourceScript,
TimeSpan.FromSeconds(3),
NullLogger.Instance,
auditWriter);
}
[Fact]
public async Task Send_Success_EmitsOneEvent_KindNotifySend_StatusSubmitted()
{
var writer = new CapturingAuditWriter();
var notify = CreateHelper(writer);
var notificationId = await notify.To(ListName).Send(Subject, Body);
Assert.False(string.IsNullOrEmpty(notificationId));
Assert.Single(writer.Events);
var evt = writer.Events[0];
Assert.Equal(AuditChannel.Notification, evt.Channel);
Assert.Equal(AuditKind.NotifySend, evt.Kind);
Assert.Equal(AuditStatus.Submitted, evt.Status);
Assert.Equal(AuditForwardState.Pending, evt.ForwardState);
Assert.Equal(DateTimeKind.Utc, evt.OccurredAtUtc.Kind);
Assert.NotEqual(Guid.Empty, evt.EventId);
Assert.False(evt.PayloadTruncated);
Assert.Null(evt.DurationMs);
Assert.Null(evt.HttpStatus);
Assert.Null(evt.ErrorMessage);
Assert.Null(evt.ErrorDetail);
Assert.Null(evt.Actor);
}
[Fact]
public async Task Send_PopulatesTarget_AsListName()
{
var writer = new CapturingAuditWriter();
var notify = CreateHelper(writer);
await notify.To(ListName).Send(Subject, Body);
var evt = writer.Events[0];
Assert.Equal(ListName, evt.Target);
}
[Fact]
public async Task Send_PopulatesRequestSummary_AsSubjectBodyJson()
{
var writer = new CapturingAuditWriter();
var notify = CreateHelper(writer);
await notify.To(ListName).Send(Subject, Body);
var evt = writer.Events[0];
Assert.NotNull(evt.RequestSummary);
// Round-trip the JSON to assert the exact shape, not raw text — the
// contract is "JSON of {subject, body}", which downstream redaction
// (M5) can reshape; M4 captures verbatim.
using var doc = JsonDocument.Parse(evt.RequestSummary!);
var root = doc.RootElement;
Assert.Equal(JsonValueKind.Object, root.ValueKind);
Assert.Equal(Subject, root.GetProperty("subject").GetString());
Assert.Equal(Body, root.GetProperty("body").GetString());
}
[Fact]
public async Task Send_AuditWriter_Throws_OriginalSendStillReturns()
{
var writer = new CapturingAuditWriter
{
ThrowOnWrite = new InvalidOperationException("audit writer down")
};
var notify = CreateHelper(writer);
// The Send call must NOT bubble the audit-writer failure: the script
// contract is that the notification is buffered and the id is returned
// even when the audit pipeline is sick.
var notificationId = await notify.To(ListName).Send(Subject, Body);
Assert.False(string.IsNullOrEmpty(notificationId));
// And the underlying S&F enqueue must still have happened — audit is
// purely additive, never aborts the user-facing action.
var buffered = await _saf.GetMessageByIdAsync(notificationId);
Assert.NotNull(buffered);
Assert.Equal(notificationId, buffered!.Id);
Assert.Empty(writer.Events);
}
[Fact]
public async Task Send_Provenance_PopulatedFromContext()
{
var writer = new CapturingAuditWriter();
var notify = CreateHelper(writer);
await notify.To(ListName).Send(Subject, Body);
var evt = writer.Events[0];
Assert.Equal(SiteId, evt.SourceSiteId);
Assert.Equal(InstanceName, evt.SourceInstanceId);
Assert.Equal(SourceScript, evt.SourceScript);
Assert.Null(evt.Actor);
}
[Fact]
public async Task Send_NotificationIdParsed_AsCorrelationId()
{
var writer = new CapturingAuditWriter();
var notify = CreateHelper(writer);
var notificationId = await notify.To(ListName).Send(Subject, Body);
// NotificationId is minted as Guid.NewGuid().ToString("N") — the 32-char
// hex form, which Guid.TryParse accepts. The audit row's CorrelationId
// must round-trip back to the same Guid value.
Assert.True(Guid.TryParse(notificationId, out var expected),
$"NotificationId '{notificationId}' should be a parseable Guid");
var evt = writer.Events[0];
Assert.NotNull(evt.CorrelationId);
Assert.Equal(expected, evt.CorrelationId);
}
[Fact]
public async Task Send_WithoutAuditWriter_StillReturnsNotificationId_AndEnqueues()
{
// Audit is opt-in (mirrors M2 Bundle F behaviour): a null writer must
// degrade to a no-op audit path so tests / minimal hosts that don't
// wire AddAuditLog still work.
var notify = CreateHelper(auditWriter: null);
var notificationId = await notify.To(ListName).Send(Subject, Body);
Assert.False(string.IsNullOrEmpty(notificationId));
var buffered = await _saf.GetMessageByIdAsync(notificationId);
Assert.NotNull(buffered);
}
}