feat(alarms): structural degraded-status signal for truncated alarm snapshots
The truncation-cliff fix made alarm transitions truncation-safe but silent:
when GetXmlCurrentAlarms2 returns exactly maxAlmCnt records the worker
suppresses absence-implies-Clear inference and says so only in a rate-limited
stderr warning. No client and no operator could tell a complete active set
from a capped one.
Two additive proto3 booleans carry the verdict out:
- QueryActiveAlarmsReplyPayload.snapshot_truncated = 2 (worker IPC reply)
- ActiveAlarmSnapshot.from_truncated_snapshot = 16 (per record)
The per-record field is not an aesthetic choice. QueryActiveAlarms returns a
bare `stream ActiveAlarmSnapshot` with no envelope, header, or trailer, so a
per-record boolean is the only carrier that stays wire-compatible; an envelope
message would change every existing client's stream element type. The reply
payload states it too because a prefix filter can leave zero records and a
truncated fetch with nothing to report still has to say so. The flag means
"this set may be incomplete", never "this record is unreliable" — it is
independent of the subtag-fallback `degraded` field.
Detection is deliberately UNCHANGED: IsTruncatedFetch remains
`fetchedRecordCount >= maxAlarmsPerFetch`. The live probe (docs/AlarmProbeFindings.md,
ce5d8ae) could not verify whether ALARM_RECORDS/@COUNT reports the total active
count or only the records in the reply, so @COUNT is not parsed for detection;
switching to it stays blocked on probe evidence. The probe's comment
annotations in WnWrapAlarmConsumer.cs are preserved.
Reset semantics: not latched. WnWrapAlarmConsumer.FoldFetch replaces the
verdict on every poll under the same lock as the snapshot merge, so the first
sub-cap fetch clears it; GatewayAlarmMonitor.ClearCache drops it with the cache
generation it describes. A caveat that never turns off is one operators learn
to ignore.
Flow: WnWrapAlarmConsumer.LastSnapshotTruncated -> AlarmDispatcher (stamps every
record) / IAlarmCommandHandler (payload) -> MxAccessCommandExecutor reply ->
GatewayAlarmMonitor._snapshotTruncated -> IGatewayAlarmService.SnapshotTruncated
-> DashboardAlarmQueryResult -> AlarmsPage warning banner (render-side only; the
poll loop and DisposeAsync drain are untouched). The public QueryActiveAlarms
RPC forwards worker snapshots unmodified, so the per-record flag needed no
mapper change — a test pins that.
Parity: this describes OUR fetch mechanics — additive gateway metadata — not
MXAccess provider behavior. No event is synthesized and no MXAccess-observable
semantics change, so it is not a parity deviation.
Tests: worker LastSnapshotTruncated set/reset/consecutive-burst (windev-run);
gateway end-to-end truncated reply -> monitor -> public stream, with the
complete-reply control as the load-bearing assertion; AlarmsPage banner
present/absent. Docs: gateway.md alarm surface, docs/DesignDecisions.md entry.
This commit is contained in:
@@ -0,0 +1,105 @@
|
||||
using Microsoft.AspNetCore.Components.Web.HtmlRendering;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Microsoft.Extensions.Options;
|
||||
using ZB.MOM.WW.MxGateway.Server.Alarms;
|
||||
using ZB.MOM.WW.MxGateway.Server.Configuration;
|
||||
using ZB.MOM.WW.MxGateway.Server.Dashboard;
|
||||
using ZB.MOM.WW.MxGateway.Server.Dashboard.Components.Pages;
|
||||
using ZB.MOM.WW.MxGateway.Tests.TestSupport;
|
||||
using HtmlRenderer = Microsoft.AspNetCore.Components.Web.HtmlRenderer;
|
||||
|
||||
namespace ZB.MOM.WW.MxGateway.Tests.Dashboard;
|
||||
|
||||
/// <summary>
|
||||
/// Renders <see cref="AlarmsPage"/> and asserts the truncated-snapshot
|
||||
/// caveat banner appears exactly when the alarm query reports a capped
|
||||
/// provider fetch.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// The absence assertion is the load-bearing one: a banner that renders
|
||||
/// unconditionally would satisfy the positive case while telling every
|
||||
/// operator, on every normal day, that the alarm list might be missing
|
||||
/// alarms. A caveat that is always on is a caveat nobody reads.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Static rendering via the framework's <see cref="HtmlRenderer"/>, as in
|
||||
/// <c>SecretsNavRenderTests</c> — the assertion is about markup the server
|
||||
/// emits, so no component-testing dependency is warranted. The page's
|
||||
/// poll loop runs its first pass inline during <c>OnInitialized</c>
|
||||
/// (the stub query completes synchronously), so the rendered markup
|
||||
/// already reflects the query result.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class AlarmsPageTruncationBannerTests
|
||||
{
|
||||
private const string BannerMarker = "Alarm snapshot may be incomplete";
|
||||
|
||||
/// <summary>A capped provider fetch puts the completeness caveat on the page.</summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AlarmsPage_WhenSnapshotTruncated_RendersTheCaveatBanner()
|
||||
{
|
||||
string html = await RenderAsync(snapshotTruncated: true);
|
||||
|
||||
Assert.Contains(BannerMarker, html, StringComparison.Ordinal);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The proof the banner is gated. A complete fetch must render no caveat
|
||||
/// at all, while the page itself still renders — the alarm-table heading
|
||||
/// is the control that keeps this from passing over a blank page.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
public async Task AlarmsPage_WhenSnapshotComplete_OmitsTheCaveatBanner()
|
||||
{
|
||||
string html = await RenderAsync(snapshotTruncated: false);
|
||||
|
||||
Assert.DoesNotContain(BannerMarker, html, StringComparison.Ordinal);
|
||||
Assert.Contains("Active Alarms", html, StringComparison.Ordinal);
|
||||
}
|
||||
|
||||
private static async Task<string> RenderAsync(bool snapshotTruncated)
|
||||
{
|
||||
ServiceCollection services = new();
|
||||
services.AddLogging();
|
||||
services.AddSingleton<IDashboardLiveDataService>(
|
||||
new StubLiveDataService(snapshotTruncated));
|
||||
services.AddSingleton<IGatewayAlarmService>(
|
||||
new FakeGatewayAlarmService { SnapshotTruncated = snapshotTruncated });
|
||||
services.AddSingleton<IOptions<GatewayOptions>>(
|
||||
Options.Create(new GatewayOptions { Alarms = new AlarmsOptions { Enabled = true } }));
|
||||
|
||||
await using ServiceProvider provider = services.BuildServiceProvider();
|
||||
await using HtmlRenderer renderer = new(
|
||||
provider,
|
||||
provider.GetRequiredService<ILoggerFactory>());
|
||||
|
||||
return await renderer.Dispatcher.InvokeAsync(async () =>
|
||||
{
|
||||
HtmlRootComponent output = await renderer.RenderComponentAsync<AlarmsPage>();
|
||||
return output.ToHtmlString();
|
||||
});
|
||||
}
|
||||
|
||||
// Answers the page's 3-second poll synchronously, so the first pass completes
|
||||
// inline inside OnInitialized and the rendered markup reflects it.
|
||||
private sealed class StubLiveDataService(bool snapshotTruncated) : IDashboardLiveDataService
|
||||
{
|
||||
/// <inheritdoc />
|
||||
public Task<DashboardLiveReadResult> ReadAsync(
|
||||
IReadOnlyCollection<string> tagAddresses,
|
||||
CancellationToken cancellationToken) =>
|
||||
Task.FromResult(DashboardLiveReadResult.Empty);
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<DashboardAlarmQueryResult> QueryAlarmsAsync(CancellationToken cancellationToken) =>
|
||||
Task.FromResult(new DashboardAlarmQueryResult(
|
||||
Alarms: [],
|
||||
Error: null,
|
||||
WorkerProcessId: null,
|
||||
SnapshotTruncated: snapshotTruncated));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user