refactor(deployment): move PendingUpdatesCache to DeploymentManager so the CLI shares it (ScadaBridge#91)

`health pending-updates` (#63) called IPendingUpdatesEvaluator.EvaluateAsync directly
from ManagementActor because the cache lived in CentralUI, so every CLI call was a full
uncached fleet flatten. IPendingUpdatesCache/PendingUpdatesCache now live in
DeploymentManager.PendingUpdates and are registered by AddDeploymentManager; the
SingleFlightMemo<T> primitive moves to Commons.Caching (public) so both CentralUI's KPI /
alarm-summary caches and DeploymentManager can use it. HandleGetPendingUpdates reads the
shared cache; the UI circuits and the CLI now share one memo per node.

Tests: ManagementActor repeated-calls test (fails against the direct evaluator call:
2 evaluations instead of 1), AddDeploymentManager singleton-registration test; the cache
and memo tests move with their types.

(ScadaBridge#91)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 13:30:38 -05:00
parent c7d868c52e
commit 1ee2e171cf
16 changed files with 102 additions and 33 deletions
@@ -137,7 +137,7 @@ public class HealthPageTests : BunitContext
// Gitea #63: the pending-updates tiles read the shared fleet cache and size scope via
// SiteScopeService. The signed-in test user is an Administrator.
Services.AddScoped<ZB.MOM.WW.ScadaBridge.CentralUI.Auth.SiteScopeService>();
var pending = Substitute.For<IPendingUpdatesCache>();
var pending = Substitute.For<ZB.MOM.WW.ScadaBridge.DeploymentManager.PendingUpdates.IPendingUpdatesCache>();
pending.GetAsync(Arg.Any<bool>(), Arg.Any<CancellationToken>()).Returns(Task.FromResult(
new ZB.MOM.WW.ScadaBridge.DeploymentManager.PendingUpdates.PendingUpdatesSnapshot(
DateTimeOffset.UtcNow,
@@ -1,234 +0,0 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.Logging.Abstractions;
using NSubstitute;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
using ZB.MOM.WW.ScadaBridge.CentralUI.Services;
using ZB.MOM.WW.ScadaBridge.DeploymentManager;
using ZB.MOM.WW.ScadaBridge.DeploymentManager.PendingUpdates;
namespace ZB.MOM.WW.ScadaBridge.CentralUI.Tests.Services;
/// <summary>
/// Unit tests for <see cref="PendingUpdatesCache"/> — the same single-flight TTL contract as
/// <see cref="SingleFlightMemoTests"/> proves for the primitive, exercised here through the
/// full DI-scope-per-flight shape: N concurrent callers before the evaluator resolves must
/// share ONE fleet flatten, a value produced inside the TTL is served without re-evaluating,
/// <c>forceRefresh</c> bypasses a fresh value but still joins an in-flight round, and a
/// faulted evaluation is never memoized.
/// </summary>
public class PendingUpdatesCacheTests : IDisposable
{
private static readonly DateTimeOffset T0 = new(2026, 9, 14, 9, 0, 0, TimeSpan.Zero);
private readonly IPendingUpdatesEvaluator _evaluator = Substitute.For<IPendingUpdatesEvaluator>();
private readonly ServiceProvider _provider;
private readonly DeploymentStatusNotifier _statusNotifier =
new(NullLogger<DeploymentStatusNotifier>.Instance);
/// <summary>Initializes a service provider that resolves the substitute pending-updates evaluator.</summary>
public PendingUpdatesCacheTests()
{
var services = new ServiceCollection();
services.AddScoped(_ => _evaluator);
_provider = services.BuildServiceProvider();
}
// A generous TTL (1h) so every test's timing is driven by task completion, not the clock.
private static IOptions<DeploymentManagerOptions> Options(TimeSpan? ttl = null) =>
Microsoft.Extensions.Options.Options.Create(
new DeploymentManagerOptions { PendingUpdatesCacheTtl = ttl ?? TimeSpan.FromHours(1) });
private PendingUpdatesCache CreateSut(TimeSpan? ttl = null, TimeSpan? invalidationQuietPeriod = null) =>
new(
_provider.GetRequiredService<IServiceScopeFactory>(),
Options(ttl),
_statusNotifier,
invalidationQuietPeriod ?? TimeSpan.FromMilliseconds(20));
private void Finish(int instanceId, DeploymentStatus status) =>
_statusNotifier.NotifyStatusChanged(new DeploymentStatusChange($"dep-{instanceId}", instanceId, status));
private static PendingUpdatesSnapshot Snapshot() =>
new(T0, Array.Empty<SitePendingUpdates>());
/// <summary>Verifies that concurrent callers share a single evaluation.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConcurrentCallers_ShareOneEvaluation()
{
var released = new TaskCompletionSource<PendingUpdatesSnapshot>(
TaskCreationOptions.RunContinuationsAsynchronously);
_evaluator.EvaluateAsync(Arg.Any<CancellationToken>()).Returns(released.Task);
var sut = CreateSut();
var waiters = Enumerable.Range(0, 10).Select(_ => sut.GetAsync()).ToArray();
released.SetResult(Snapshot());
var results = await Task.WhenAll(waiters);
await _evaluator.Received(1).EvaluateAsync(Arg.Any<CancellationToken>());
Assert.All(results, r => Assert.Same(results[0], r));
}
/// <summary>Verifies that a call within the TTL serves the memoized value without re-evaluating.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WithinTtl_ServesTheMemoizedValue_WithoutReEvaluating()
{
_evaluator.EvaluateAsync(Arg.Any<CancellationToken>()).Returns(Snapshot());
var sut = CreateSut();
var first = await sut.GetAsync();
var second = await sut.GetAsync();
await _evaluator.Received(1).EvaluateAsync(Arg.Any<CancellationToken>());
Assert.Same(first, second);
}
/// <summary>Verifies that a forced refresh bypasses a still-fresh cached value.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ForceRefresh_BypassesAFreshValue()
{
var snapshotA = Snapshot();
var snapshotB = new PendingUpdatesSnapshot(T0.AddMinutes(1), Array.Empty<SitePendingUpdates>());
_evaluator.EvaluateAsync(Arg.Any<CancellationToken>()).Returns(snapshotA, snapshotB);
var sut = CreateSut();
var first = await sut.GetAsync();
var forced = await sut.GetAsync(forceRefresh: true);
await _evaluator.Received(2).EvaluateAsync(Arg.Any<CancellationToken>());
Assert.Same(snapshotA, first);
Assert.Same(snapshotB, forced);
}
/// <summary>Verifies that a forced refresh still joins an evaluation that is already in flight.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ForceRefresh_StillJoinsAnInFlightRound()
{
var released = new TaskCompletionSource<PendingUpdatesSnapshot>(
TaskCreationOptions.RunContinuationsAsynchronously);
_evaluator.EvaluateAsync(Arg.Any<CancellationToken>()).Returns(released.Task);
var sut = CreateSut();
var first = sut.GetAsync();
var forcedA = sut.GetAsync(forceRefresh: true);
var forcedB = sut.GetAsync(forceRefresh: true);
var snapshot = Snapshot();
released.SetResult(snapshot);
Assert.Same(snapshot, await first);
Assert.Same(snapshot, await forcedA);
Assert.Same(snapshot, await forcedB);
await _evaluator.Received(1).EvaluateAsync(Arg.Any<CancellationToken>());
}
/// <summary>Verifies that a failed evaluation surfaces to the caller and is remembered only for the short back-off (review 2026-10-21 04/C4).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task FailedEvaluation_SurfacesToTheCaller_AndIsBackedOffNotRetriedPerPoll()
{
_evaluator.EvaluateAsync(Arg.Any<CancellationToken>())
.Returns(
Task.FromException<PendingUpdatesSnapshot>(new InvalidOperationException("flatten failed")),
Task.FromResult(Snapshot()));
var sut = CreateSut();
await Assert.ThrowsAsync<InvalidOperationException>(() => sut.GetAsync());
// Inside the negative TTL a poll is served the same fault with no new flatten.
await Assert.ThrowsAsync<InvalidOperationException>(() => sut.GetAsync());
await _evaluator.Received(1).EvaluateAsync(Arg.Any<CancellationToken>());
// An operator Re-check bypasses the back-off.
var recovered = await sut.GetAsync(forceRefresh: true);
Assert.NotNull(recovered);
await _evaluator.Received(2).EvaluateAsync(Arg.Any<CancellationToken>());
}
/// <summary>
/// Verifies that a finished deployment drops the memoized snapshot — a deploy is exactly the
/// event that changes the answer, so serving the pre-deploy count for the rest of the TTL
/// window left the rail showing stale "pending" counts after a successful Deploy all.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(DeploymentStatus.Success)]
[InlineData(DeploymentStatus.Failed)]
public async Task FinishedDeployment_InvalidatesTheMemoizedSnapshot(DeploymentStatus status)
{
_evaluator.EvaluateAsync(Arg.Any<CancellationToken>()).Returns(_ => Snapshot());
using var sut = CreateSut();
await sut.GetAsync();
Finish(1, status);
await sut.GetAsync();
await _evaluator.Received(2).EvaluateAsync(Arg.Any<CancellationToken>());
}
/// <summary>Verifies that a deployment that has only started does not invalidate the snapshot.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StartedDeployment_DoesNotInvalidate()
{
_evaluator.EvaluateAsync(Arg.Any<CancellationToken>()).Returns(_ => Snapshot());
using var sut = CreateSut();
await sut.GetAsync();
Finish(1, DeploymentStatus.InProgress);
await sut.GetAsync();
await _evaluator.Received(1).EvaluateAsync(Arg.Any<CancellationToken>());
}
/// <summary>
/// Verifies that a burst of completions — one per instance in a bulk deploy — raises
/// <c>Invalidated</c> once, after the burst goes quiet, so every open rail re-reads once
/// instead of once per instance.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task BurstOfFinishedDeployments_RaisesInvalidatedOnceAfterItGoesQuiet()
{
using var sut = CreateSut(invalidationQuietPeriod: TimeSpan.FromMilliseconds(100));
var raised = 0;
var signal = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
sut.Invalidated += () =>
{
Interlocked.Increment(ref raised);
signal.TrySetResult();
};
for (var i = 1; i <= 9; i++)
{
Finish(i, DeploymentStatus.Success);
}
await signal.Task.WaitAsync(TimeSpan.FromSeconds(5));
await Task.Delay(300);
Assert.Equal(1, Volatile.Read(ref raised));
}
/// <summary>Verifies that the cache stops listening to deployment status changes once disposed.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Dispose_UnsubscribesFromStatusChanges()
{
var sut = CreateSut();
var raised = 0;
sut.Invalidated += () => Interlocked.Increment(ref raised);
sut.Dispose();
Finish(1, DeploymentStatus.Success);
await Task.Delay(150);
Assert.Equal(0, Volatile.Read(ref raised));
}
/// <summary>Releases the resources held by the test fixture.</summary>
public void Dispose() => _provider.Dispose();
}
@@ -1,245 +0,0 @@
using ZB.MOM.WW.ScadaBridge.CentralUI.Services;
namespace ZB.MOM.WW.ScadaBridge.CentralUI.Tests.Services;
/// <summary>
/// Unit tests for <see cref="SingleFlightMemo{T}"/> — the primitive behind the process-level
/// KPI snapshot cache and the shared Alarm Summary fan-out. The two
/// properties the whole optimisation rests on are tested here: <b>single-flight</b> (N
/// concurrent circuits asking the same question produce ONE query) and <b>TTL</b> (a query
/// answered inside the freshness window is served from memory, and one outside it is not).
/// </summary>
public class SingleFlightMemoTests
{
private static readonly DateTimeOffset T0 = new(2026, 8, 14, 9, 0, 0, TimeSpan.Zero);
/// <summary>Verifies that concurrent callers share a single in-flight query.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConcurrentCallers_ShareOneFlight()
{
var released = new TaskCompletionSource<int>(TaskCreationOptions.RunContinuationsAsynchronously);
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(10), () => T0);
// Ten circuits ask while the first flight is still in progress.
var waiters = Enumerable.Range(0, 10)
.Select(_ => memo.GetAsync(() =>
{
Interlocked.Increment(ref invocations);
return released.Task;
}))
.ToArray();
released.SetResult(42);
var results = await Task.WhenAll(waiters);
Assert.Equal(1, invocations);
Assert.Equal(1, memo.FlightCount);
Assert.All(results, r => Assert.Equal(42, r));
}
/// <summary>Verifies that a call within the TTL serves the memoized value without querying again.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WithinTtl_ServesTheMemoizedValue_WithoutRequerying()
{
var now = T0;
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(8), () => now);
var first = await memo.GetAsync(() => Task.FromResult(++invocations));
now = T0.AddSeconds(7);
var second = await memo.GetAsync(() => Task.FromResult(++invocations));
Assert.Equal(1, first);
Assert.Equal(1, second);
Assert.Equal(1, memo.FlightCount);
}
/// <summary>Verifies that a call after the TTL expires queries exactly once more.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AfterTtl_RequeriesOnce()
{
var now = T0;
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(8), () => now);
await memo.GetAsync(() => Task.FromResult(++invocations));
now = T0.AddSeconds(9);
var refreshed = await memo.GetAsync(() => Task.FromResult(++invocations));
Assert.Equal(2, refreshed);
Assert.Equal(2, memo.FlightCount);
}
/// <summary>Verifies that a forced refresh bypasses a value that is still fresh.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ForceRefresh_BypassesAFreshValue()
{
var now = T0;
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(60), () => now);
await memo.GetAsync(() => Task.FromResult(++invocations));
var forced = await memo.GetAsync(() => Task.FromResult(++invocations), forceRefresh: true);
Assert.Equal(2, forced);
Assert.Equal(2, memo.FlightCount);
}
/// <summary>Verifies that a forced refresh still joins a query that is already in flight.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ForceRefresh_StillJoinsAnInFlightRound()
{
var released = new TaskCompletionSource<int>(TaskCreationOptions.RunContinuationsAsynchronously);
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(60), () => T0);
var first = memo.GetAsync(() =>
{
Interlocked.Increment(ref invocations);
return released.Task;
});
// A burst of operator "Refresh" clicks must not multiply the query.
var forcedA = memo.GetAsync(() => Task.FromResult(-1), forceRefresh: true);
var forcedB = memo.GetAsync(() => Task.FromResult(-1), forceRefresh: true);
released.SetResult(7);
Assert.Equal(7, await first);
Assert.Equal(7, await forcedA);
Assert.Equal(7, await forcedB);
Assert.Equal(1, invocations);
}
/// <summary>Verifies that a failure is not memoized and the next caller retries.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Failure_IsNotMemoized_AndTheNextCallerRetries()
{
var now = T0;
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(60), () => now);
await Assert.ThrowsAsync<InvalidOperationException>(() =>
memo.GetAsync(() =>
{
invocations++;
return Task.FromException<int>(new InvalidOperationException("KPI query failed"));
}));
// Same instant, well inside the TTL — a cached fault would starve the tiles for a
// whole window, so the next caller must produce a new flight.
var recovered = await memo.GetAsync(() => Task.FromResult(++invocations));
Assert.Equal(2, recovered);
Assert.Equal(2, memo.FlightCount);
}
/// <summary>Verifies the opt-in fault back-off memoizes a fault briefly, then retries.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task FaultBackoff_ReservesTheFault_ThenRetriesAfterWindow()
{
var now = T0;
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(60), () => now, TimeSpan.FromSeconds(10));
await Assert.ThrowsAsync<InvalidOperationException>(() =>
memo.GetAsync(() => { invocations++; return Task.FromException<int>(new InvalidOperationException("x")); }));
now = T0.AddSeconds(5);
await Assert.ThrowsAsync<InvalidOperationException>(() => memo.GetAsync(() => Task.FromResult(++invocations)));
Assert.Equal(1, memo.FlightCount);
now = T0.AddSeconds(11);
Assert.Equal(2, await memo.GetAsync(() => Task.FromResult(++invocations)));
Assert.Equal(2, memo.FlightCount);
}
/// <summary>Verifies that a TTL override applies to the flight it was supplied for.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task TtlOverride_AppliesToThatFlight()
{
var now = T0;
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(5), () => now);
// Produced under a 60s override — still fresh 30s later despite the 5s default.
await memo.GetAsync(() => Task.FromResult(++invocations), ttlOverride: TimeSpan.FromSeconds(60));
now = T0.AddSeconds(30);
var second = await memo.GetAsync(() => Task.FromResult(++invocations));
Assert.Equal(1, second);
Assert.Equal(1, memo.FlightCount);
}
/// <summary>Verifies that cancelling one caller does not cancel the shared flight.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CallerCancellation_DoesNotCancelTheSharedFlight()
{
var released = new TaskCompletionSource<int>(TaskCreationOptions.RunContinuationsAsynchronously);
var memo = new SingleFlightMemo<int>(TimeSpan.FromSeconds(60), () => T0);
using var giveUp = new CancellationTokenSource();
var impatient = memo.GetAsync(() => released.Task, cancellationToken: giveUp.Token);
var patient = memo.GetAsync(() => Task.FromResult(-1));
giveUp.Cancel();
await Assert.ThrowsAnyAsync<OperationCanceledException>(() => impatient);
// The abandoned wait must not have taken the round down with it.
released.SetResult(99);
Assert.Equal(99, await patient);
}
/// <summary>Verifies that <c>Invalidate</c> makes a still-fresh value stale, so the next call queries again.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Invalidate_DiscardsAFreshValue()
{
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromHours(1), () => T0);
var first = await memo.GetAsync(() => Task.FromResult(++invocations));
memo.Invalidate();
var second = await memo.GetAsync(() => Task.FromResult(++invocations));
Assert.Equal(1, first);
Assert.Equal(2, second);
Assert.Equal(2, memo.FlightCount);
}
/// <summary>
/// Verifies that a flight already running when <c>Invalidate</c> is called still answers its
/// callers but is not memoized: it may have read the state the invalidation says changed.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Invalidate_DuringAFlight_ResultIsServedButNotMemoized()
{
var released = new TaskCompletionSource<int>(TaskCreationOptions.RunContinuationsAsynchronously);
var invocations = 0;
var memo = new SingleFlightMemo<int>(TimeSpan.FromHours(1), () => T0);
var inFlight = memo.GetAsync(() =>
{
invocations++;
return released.Task;
});
memo.Invalidate();
released.SetResult(7);
Assert.Equal(7, await inFlight);
var next = await memo.GetAsync(() => Task.FromResult(++invocations));
Assert.Equal(2, next);
Assert.Equal(2, memo.FlightCount);
}
}