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

fix(sitecallaudit): push StuckOnly filter into SQL; doc accuracy fixes

Browse Source
This commit is contained in:
Joseph Doherty
2026-05-21 04:24:16 -04:00
parent e3519fdb39
commit ac1f73cf8a
8 changed files with 168 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
src/ScadaLink.Commons/Messages/Audit/SiteCallQueries.cs
View File

@@ -18,6 +18,10 @@ namespace ScadaLink.Commons.Messages.Audit;
/// exact-match target filter, consistent with the repository's
/// <see cref="SiteCallQueryFilter.Target"/> predicate.
/// </remarks>
/// <param name="PageSize">
/// Requested page size. The actor clamps this to the <c>[1, 200]</c> range, so
/// the effective ceiling is 200 rows per page regardless of the value sent.
/// </param>
public sealed record SiteCallQueryRequest(
string CorrelationId,
string? StatusFilter,
@@ -39,6 +43,12 @@ public sealed record SiteCallQueryRequest(
/// <see cref="ScadaLink.Commons.Messages.Notification.NotificationSummary"/>
/// none are surfaced here.
/// </summary>
/// <remarks>
/// <see cref="HttpStatus"/> is not called out in the Site Call Audit plan, but
/// it is a real (nullable) <see cref="ScadaLink.Commons.Entities.Audit.SiteCall"/>
/// column — the last HTTP status code observed for the call — so it is surfaced
/// here for the grid; <c>null</c> for non-HTTP channels or before a first attempt.
/// </remarks>
public sealed record SiteCallSummary(
Guid TrackedOperationId,
string SourceSite,

4
src/ScadaLink.Commons/Types/Audit/SiteCallKpiSnapshot.cs
View File

@@ -8,7 +8,7 @@ namespace ScadaLink.Commons.Types.Audit;
/// Notification Outbox tile layout.
/// </summary>
/// <param name="BufferedCount">
/// Count of non-terminal rows (<c>Pending</c> + <c>Retrying</c>) — calls
/// Count of non-terminal rows (<c>TerminalAtUtc IS NULL</c>) — calls
/// buffered at sites awaiting retry.
/// </param>
/// <param name="ParkedCount">Count of rows in the <c>Parked</c> status.</param>
@@ -25,7 +25,7 @@ namespace ScadaLink.Commons.Types.Audit;
/// <c>null</c> when there are no non-terminal rows.
/// </param>
/// <param name="StuckCount">
/// Count of non-terminal rows (<c>Pending</c>/<c>Retrying</c>) whose
/// Count of non-terminal rows (<c>TerminalAtUtc IS NULL</c>) whose
/// <see cref="ScadaLink.Commons.Entities.Audit.SiteCall.CreatedAtUtc"/> is older
/// than the supplied stuck cutoff. Display-only — no escalation.
/// </param>

17
src/ScadaLink.Commons/Types/Audit/SiteCallQueryFilter.cs
View File

@@ -12,10 +12,25 @@ namespace ScadaLink.Commons.Types.Audit;
/// underlying columns are bounded ASCII (varchar) and the Central UI Site Calls
/// page exposes them as drop-down filters, not free-text search.
/// </remarks>
/// <param name="Channel">Restrict to a single channel (exact match).</param>
/// <param name="SourceSite">Restrict to a single source site (exact match).</param>
/// <param name="Status">Restrict to a single status (exact match).</param>
/// <param name="Target">Restrict to a single target (exact match).</param>
/// <param name="FromUtc">Inclusive lower bound on <c>CreatedAtUtc</c>.</param>
/// <param name="ToUtc">Inclusive upper bound on <c>CreatedAtUtc</c>.</param>
/// <param name="StuckCutoffUtc">
/// When set, restrict to stuck rows: <c>TerminalAtUtc IS NULL AND CreatedAtUtc &lt;
/// StuckCutoffUtc</c>. Both columns are plain (no value converter) and compose
/// directly with the keyset cursor. Mirrors
/// <see cref="ScadaLink.Commons.Types.Notifications.NotificationOutboxFilter.StuckCutoff"/>;
/// keeps the "StuckOnly" filter honest so paging never returns under-filled
/// pages with a non-null next cursor.
/// </param>
public sealed record SiteCallQueryFilter(
string? Channel = null,
string? SourceSite = null,
string? Status = null,
string? Target = null,
DateTime? FromUtc = null,
DateTime? ToUtc = null);
DateTime? ToUtc = null,
DateTime? StuckCutoffUtc = null);

2
src/ScadaLink.Commons/Types/Audit/SiteCallSiteKpiSnapshot.cs
View File

@@ -7,7 +7,7 @@ namespace ScadaLink.Commons.Types.Audit;
/// <see cref="ScadaLink.Commons.Types.Notifications.SiteNotificationKpiSnapshot"/>.
/// </summary>
/// <param name="SourceSite">The site identifier these metrics are scoped to.</param>
/// <param name="BufferedCount">Count of this site's non-terminal rows (<c>Pending</c> + <c>Retrying</c>).</param>
/// <param name="BufferedCount">Count of this site's non-terminal rows (<c>TerminalAtUtc IS NULL</c>).</param>
/// <param name="ParkedCount">Count of this site's rows in the <c>Parked</c> status.</param>
/// <param name="FailedLastInterval">
/// Count of this site's <c>Failed</c> rows whose <c>TerminalAtUtc</c> is at or

7
src/ScadaLink.ConfigurationDatabase/Repositories/SiteCallAuditRepository.cs
View File

@@ -164,7 +164,13 @@ WHERE TrackedOperationId = {idText}
var fromUtc = filter.FromUtc;
var toUtc = filter.ToUtc;
var stuckCutoff = filter.StuckCutoffUtc;
// The stuck predicate (TerminalAtUtc IS NULL AND CreatedAtUtc < cutoff)
// is pushed into SQL here — both columns are plain (no value converter)
// and compose with the keyset cursor, so a StuckOnly page is honest:
// never under-filled with a non-null next cursor. Mirrors how
// NotificationOutboxRepository.QueryAsync applies NotificationOutboxFilter.StuckCutoff.
FormattableString sql = $@"
SELECT TOP ({paging.PageSize})
TrackedOperationId, Channel, Target, SourceSite, Status, RetryCount,
@@ -176,6 +182,7 @@ WHERE ({filter.Channel} IS NULL OR Channel = {filter.Channel})
AND ({filter.Target} IS NULL OR Target = {filter.Target})
AND ({fromUtc} IS NULL OR CreatedAtUtc >= {fromUtc})
AND ({toUtc} IS NULL OR CreatedAtUtc <= {toUtc})
AND ({stuckCutoff} IS NULL OR (TerminalAtUtc IS NULL AND CreatedAtUtc < {stuckCutoff}))
AND ({(hasCursor ? 1 : 0)} = 0
OR CreatedAtUtc < {afterCreated}
OR (CreatedAtUtc = {afterCreated} AND TrackedOperationId < {afterIdString}))

28
src/ScadaLink.SiteCallAudit/SiteCallAuditActor.cs
View File

@@ -21,10 +21,9 @@ namespace ScadaLink.SiteCallAudit;
/// </summary>
/// <remarks>
/// <para>
/// M3 ships the minimum surface: ingest only. Reconciliation, KPIs, and
/// central→site Retry/Discard relay are deferred (per CLAUDE.md scope
/// discipline — Site Call Audit's KPIs and the Retry/Discard relay land in a
/// follow-up).
/// Query, detail and KPIs land in Task 4; reconciliation and the central→site
/// Retry/Discard relay remain deferred (per CLAUDE.md scope discipline — they
/// land in a later follow-up).
/// </para>
/// <para>
/// Per CLAUDE.md "audit-write failure NEVER aborts the user-facing action" —
@@ -195,13 +194,20 @@ public class SiteCallAuditActor : ReceiveActor
private async Task<SiteCallQueryResponse> QueryAsync(SiteCallQueryRequest request, DateTime now)
{
var stuckCutoff = now - _options.StuckAgeThreshold;
var filter = new SiteCallQueryFilter(
Channel: NullIfBlank(request.ChannelFilter),
SourceSite: NullIfBlank(request.SourceSiteFilter),
Status: NullIfBlank(request.StatusFilter),
Target: NullIfBlank(request.TargetKeyword),
FromUtc: request.FromUtc,
ToUtc: request.ToUtc);
ToUtc: request.ToUtc,
// StuckOnly is pushed into the repository SQL via StuckCutoffUtc —
// TerminalAtUtc IS NULL AND CreatedAtUtc < cutoff composes with the
// keyset cursor, so the page is always honest (full pages, no empty
// pages with a non-null next cursor).
StuckCutoffUtc: request.StuckOnly ? stuckCutoff : null);
var pageSize = Math.Clamp(request.PageSize, 1, MaxPageSize);
var paging = new SiteCallPaging(
@@ -214,21 +220,11 @@ public class SiteCallAuditActor : ReceiveActor
{
var rows = await repository.QueryAsync(filter, paging).ConfigureAwait(false);
var stuckCutoff = now - _options.StuckAgeThreshold;
var summaries = rows
// StuckOnly is post-filtered here rather than pushed into the
// repository SQL — the SiteCallQueryFilter has no stuck predicate
// and a status-aware created-before clause does not compose with
// the keyset cursor. The page may therefore return fewer than
// PageSize rows when StuckOnly is set; that is acceptable for a
// display-only filter.
.Where(row => !request.StuckOnly || IsStuck(row, stuckCutoff))
.Select(row => ToSummary(row, stuckCutoff))
.ToList();
// The next-page cursor is the LAST row of the materialised page —
// before StuckOnly post-filtering, so paging still advances even
// when every row on a page was filtered out.
// The next-page cursor is the last row of the materialised page.
var cursorRow = rows.Count > 0 ? rows[^1] : null;
return new SiteCallQueryResponse(