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

feat(notif): emit NotifyDeliver(terminal) on terminal transitions (#23 M4)

Browse Source 
M4 Bundle B (B3) — NotificationOutboxActor emits a second NotifyDeliver
audit row carrying the terminal AuditStatus whenever a notification
transitions to a terminal state (Delivered, Parked, Discarded).

- Dispatcher: after the B2 Attempted row, a Delivered or Parked row is
  emitted when the post-outcome status is terminal. Discarded is never
  produced by the dispatcher — only by the manual discard path.
- Missing-adapter park: now emits both Attempted and terminal Parked,
  both carrying the same explanatory error.
- Manual discard (DiscardAsync): after the row update, emits a terminal
  Discarded NotifyDeliver row with no error message (operator-driven
  cancellation, not a delivery error).
- MapNotificationStatusToAuditStatus + IsTerminal helpers added; terminal
  emission shares BuildNotifyDeliverEvent with the B2 Attempted path so
  the two rows carry identical correlation/provenance fields.

Audit failure NEVER aborts the user-facing action: every emission is
wrapped in try/catch (defensive — the CentralAuditWriter itself swallows).
This commit is contained in:
Joseph Doherty
2026-05-20 16:12:44 -04:00
parent 1dfd67a90d
commit 6de377a39e
2 changed files with 374 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
src/ScadaLink.NotificationOutbox/NotificationOutboxActor.cs
View File

@@ -272,15 +272,17 @@ public class NotificationOutboxActor : ReceiveActor, IWithTimers
/// </summary>
/// <remarks>
/// <para>
/// M4 Bundle B2: a single
/// M4 Bundle B2 + B3: a single
/// <see cref="AuditChannel.Notification"/>/<see cref="AuditKind.NotifyDeliver"/>
/// row is emitted with <see cref="AuditStatus.Attempted"/> per attempt
/// (success, transient, permanent). The emission is wrapped in a
/// try/catch so a thrown audit writer NEVER aborts the user-facing
/// dispatch — the <see cref="CentralAuditWriter"/> itself swallows
/// internal failures, but the dispatcher wraps defensively per
/// alog.md §13. The missing-adapter park path also emits an Attempted
/// row because it IS an attempt from the dispatcher's point of view.
/// (success, transient, permanent); when the post-outcome status is a
/// terminal one (Delivered, Parked) a SECOND row is emitted carrying
/// that terminal status. Both emissions are wrapped in a try/catch so a
/// thrown audit writer NEVER aborts the user-facing dispatch — the
/// <see cref="CentralAuditWriter"/> itself swallows internal failures,
/// but the dispatcher wraps defensively per alog.md §13. The
/// missing-adapter park path also emits both rows because it IS an
/// attempt that resolved to a park from the dispatcher's point of view.
/// </para>
/// <para>
/// Attempt duration is measured around the adapter call and recorded on
@@ -299,8 +301,8 @@ public class NotificationOutboxActor : ReceiveActor, IWithTimers
if (!adapters.TryGetValue(notification.Type, out var adapter))
{
// Missing-adapter park: from the dispatcher's perspective this is an
// attempt that resolved to a park, so we emit the Attempted row
// alongside the row update.
// attempt that resolved to a terminal park. Emit Attempted then the
// terminal Parked row, both carrying the same explanatory error.
var missingAdapterError = $"no delivery adapter for type {notification.Type}";
notification.Status = NotificationStatus.Parked;
notification.LastError = missingAdapterError;
@@ -311,6 +313,7 @@ public class NotificationOutboxActor : ReceiveActor, IWithTimers
now,
durationMs: 0,
errorMessage: missingAdapterError);
EmitTerminalAudit(notification, now, errorMessage: missingAdapterError);
return;
}
@@ -364,6 +367,78 @@ public class NotificationOutboxActor : ReceiveActor, IWithTimers
now,
durationMs: durationMs,
errorMessage: outcome.Result == DeliveryResult.Success ? null : outcome.Error);
// If the post-outcome status is terminal (Delivered or Parked — the
// dispatcher never sets Discarded; that lives on the manual discard
// path), emit the terminal NotifyDeliver row (B3). The error message
// on a Delivered terminal is null; on Parked it carries the outcome's
// reason so downstream consumers can link Attempted+Parked rows.
if (IsTerminal(notification.Status))
{
EmitTerminalAudit(
notification,
now,
errorMessage: outcome.Result == DeliveryResult.Success ? null : outcome.Error);
}
}
/// <summary>
/// True for <see cref="NotificationStatus.Delivered"/>,
/// <see cref="NotificationStatus.Parked"/>, or
/// <see cref="NotificationStatus.Discarded"/> — the three terminal states
/// on the central outbox lifecycle. Used by the dispatcher and the manual
/// discard handler to decide when to emit the terminal NotifyDeliver row.
/// </summary>
private static bool IsTerminal(NotificationStatus status)
{
return status is NotificationStatus.Delivered
or NotificationStatus.Parked
or NotificationStatus.Discarded;
}
/// <summary>
/// Emits a single
/// <see cref="AuditChannel.Notification"/>/<see cref="AuditKind.NotifyDeliver"/>
/// audit row carrying the terminal status (Delivered, Parked, or
/// Discarded) of <paramref name="notification"/>. Wrapped in try/catch
/// for the same defensive reason as <see cref="EmitAttemptAudit"/>.
/// </summary>
private void EmitTerminalAudit(
Notification notification,
DateTimeOffset now,
string? errorMessage)
{
try
{
var terminalStatus = MapNotificationStatusToAuditStatus(notification.Status);
var evt = BuildNotifyDeliverEvent(notification, now, terminalStatus, errorMessage);
_ = _auditWriter.WriteAsync(evt);
}
catch (Exception ex)
{
_logger.LogWarning(
ex,
"Failed to emit terminal {Status} audit row for notification {NotificationId}.",
notification.Status, notification.NotificationId);
}
}
/// <summary>
/// Maps the central-outbox <see cref="NotificationStatus"/> terminal
/// values onto the corresponding <see cref="AuditStatus"/> values used by
/// AuditLog (#23). Non-terminal statuses throw — the caller must gate on
/// <see cref="IsTerminal"/>.
/// </summary>
private static AuditStatus MapNotificationStatusToAuditStatus(NotificationStatus status)
{
return status switch
{
NotificationStatus.Delivered => AuditStatus.Delivered,
NotificationStatus.Parked => AuditStatus.Parked,
NotificationStatus.Discarded => AuditStatus.Discarded,
_ => throw new ArgumentOutOfRangeException(
nameof(status), status, "non-terminal status has no audit terminal mapping"),
};
}
/// <summary>
@@ -680,6 +755,13 @@ public class NotificationOutboxActor : ReceiveActor, IWithTimers
notification.Status = NotificationStatus.Discarded;
await repository.UpdateAsync(notification);
// M4 Bundle B3: a manual discard is the OTHER code path that produces
// a terminal NotificationStatus transition (alongside the dispatcher).
// Emit a Discarded NotifyDeliver row to match the dispatcher's
// Delivered/Parked emissions; the row carries no error message because
// the discard is an operator-driven cancellation, not a delivery error.
EmitTerminalAudit(notification, DateTimeOffset.UtcNow, errorMessage: null);
return new DiscardNotificationResponse(request.CorrelationId, Success: true, ErrorMessage: null);
}