perf(misc): cached hot-path lookups, bounded observer queue, alarm-priority stream path

WP2.6 (arch-review remediation, cross-cutting misc): - SiteExternalSystemRepository: name/ID-indexed ExternalSystemDefinitionCache replaces the fetch-all + reverse-map scan on every by-ID/method lookup; loaded once per redeploy, invalidated by DeploymentManagerActor after HandleDeployArtifacts applies external-system changes. Static JsonSerializerOptions for method-list parsing. - Inbound API: short-TTL ApiMethodCache fronts the per-request ApiMethod repository fetch; invalidated by name via the existing ScriptArtifactChangeSubscriber/ IScriptArtifactChangeBus pipeline, self-healing via TTL for changes the bus doesn't cover (e.g. Management API edits). - StoreAndForward: the cached-call audit-observer queue — the one unbounded channel left in the system — is now bounded (ObserverQueueCapacity, default 10,000) with DropOldest overflow and a dropped-notification counter. - SiteStreamManager: alarm state changes now travel a dedicated publish source/broadcast hub, isolated from the (far higher-volume) attribute path, so an attribute storm can no longer evict a pending alarm transition; the alarm hand-off queue is bounded with a drop counter surfaced on the site health report (SiteStreamAlarmDropCount via the new SiteStreamAlarmDropReporter), and publishing is skipped entirely at zero subscribers on either path. - CLI ManagementHttpClient: explicit 30s HttpClient.Timeout on the shared construction (was the 100s framework default), overridable via SCADABRIDGE_HTTP_TIMEOUT_SECONDS. Deviation: the failback-probe heartbeat item is NOT included — its only viable surface (CentralChannelProvider.cs / heartbeat consumers) lives entirely in the Communication project, explicitly off-limits to this work package this phase. Tests: SiteRuntime.Tests (550), InboundAPI.Tests (278), StoreAndForward.Tests (133), CLI.Tests (390), HealthMonitoring.Tests (97) — all green after full solution build.
2026-08-14 20:59:43 -04:00
parent ee193cd2bb
commit a212283104
32 changed files with 1361 additions and 111 deletions
@@ -0,0 +1,110 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.InboundApi;
+
+namespace ZB.MOM.WW.ScadaBridge.InboundAPI.Tests;
+
+/// <summary>
+/// WP2.6b (arch-review misc — Inbound API per-request SQL): <see cref="ApiMethodCache"/>
+/// hit/miss/expiry/invalidation behavior, independent of the endpoint and subscriber wiring
+/// (covered separately by <see cref="ScriptArtifactChangeSubscriberTests"/>).
+/// </summary>
+public class ApiMethodCacheTests
+{
+    private static ApiMethod Method(string name) => new(name, "return 1;") { Id = 1 };
+
+    [Fact]
+    public async Task GetOrFetchAsync_SecondCallWithinTtl_ServesFromCache_NoRefetch()
+    {
+        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
+        var fetchCount = 0;
+        Task<ApiMethod?> Fetch(CancellationToken _)
+        {
+            fetchCount++;
+            return Task.FromResult<ApiMethod?>(Method("m"));
+        }
+
+        var first = await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+        var second = await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+
+        Assert.Equal(1, fetchCount);
+        Assert.Same(first, second);
+    }
+
+    [Fact]
+    public async Task GetOrFetchAsync_AfterTtlExpiry_Refetches()
+    {
+        var time = new FakeTimeProvider(DateTimeOffset.UtcNow);
+        var cache = new ApiMethodCache(TimeSpan.FromSeconds(1), time);
+        var fetchCount = 0;
+        Task<ApiMethod?> Fetch(CancellationToken _)
+        {
+            fetchCount++;
+            return Task.FromResult<ApiMethod?>(Method("m"));
+        }
+
+        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+        time.Advance(TimeSpan.FromSeconds(2));
+        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+
+        Assert.Equal(2, fetchCount);
+    }
+
+    [Fact]
+    public async Task GetOrFetchAsync_NegativeResult_IsCachedUntilTtlExpires()
+    {
+        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
+        var fetchCount = 0;
+        Task<ApiMethod?> Fetch(CancellationToken _)
+        {
+            fetchCount++;
+            return Task.FromResult<ApiMethod?>(null);
+        }
+
+        var first = await cache.GetOrFetchAsync("missing", Fetch, CancellationToken.None);
+        var second = await cache.GetOrFetchAsync("missing", Fetch, CancellationToken.None);
+
+        Assert.Null(first);
+        Assert.Null(second);
+        Assert.Equal(1, fetchCount);
+    }
+
+    [Fact]
+    public async Task Invalidate_DropsEntry_NextCallRefetches()
+    {
+        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
+        var fetchCount = 0;
+        Task<ApiMethod?> Fetch(CancellationToken _)
+        {
+            fetchCount++;
+            return Task.FromResult<ApiMethod?>(Method("m"));
+        }
+
+        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+        cache.Invalidate("m");
+        await cache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+
+        Assert.Equal(2, fetchCount);
+    }
+
+    [Fact]
+    public void Invalidate_UnknownName_DoesNotThrow()
+    {
+        var cache = new ApiMethodCache(TimeSpan.FromMinutes(5));
+        cache.Invalidate("never-cached");
+    }
+
+    [Fact]
+    public void Constructor_NonPositiveTtl_Throws()
+    {
+        Assert.Throws<ArgumentOutOfRangeException>(() => new ApiMethodCache(TimeSpan.Zero));
+        Assert.Throws<ArgumentOutOfRangeException>(() => new ApiMethodCache(TimeSpan.FromSeconds(-1)));
+    }
+
+    /// <summary>Minimal controllable <see cref="TimeProvider"/> for TTL-expiry tests.</summary>
+    private sealed class FakeTimeProvider : TimeProvider
+    {
+        private DateTimeOffset _now;
+        public FakeTimeProvider(DateTimeOffset start) => _now = start;
+        public void Advance(TimeSpan by) => _now += by;
+        public override DateTimeOffset GetUtcNow() => _now;
+    }
+}
@@ -65,4 +65,22 @@ public class InboundApiOptionsValidatorTests
        Assert.True(result.Failed);
        Assert.Contains("MaxRequestBodyBytes", result.FailureMessage);
    }
+
+    [Fact]
+    public void ZeroApiMethodCacheTtl_IsRejected()
+    {
+        var result = Validate(new InboundApiOptions { ApiMethodCacheTtl = TimeSpan.Zero });
+
+        Assert.True(result.Failed);
+        Assert.Contains("ApiMethodCacheTtl", result.FailureMessage);
+    }
+
+    [Fact]
+    public void NegativeApiMethodCacheTtl_IsRejected()
+    {
+        var result = Validate(new InboundApiOptions { ApiMethodCacheTtl = TimeSpan.FromSeconds(-1) });
+
+        Assert.True(result.Failed);
+        Assert.Contains("ApiMethodCacheTtl", result.FailureMessage);
+    }
 }
@@ -41,12 +41,13 @@ public class ScriptArtifactChangeSubscriberTests

    private readonly InboundScriptExecutor _executor = new(
        NullLogger<InboundScriptExecutor>.Instance, Substitute.For<IServiceProvider>());
+    private readonly ApiMethodCache _methodCache = new(TimeSpan.FromMinutes(5));
    private readonly RecordingBus _bus = new();
    private readonly RouteHelper _route = new(
        Substitute.For<IInstanceLocator>(), Substitute.For<IInstanceRouter>());

    private ScriptArtifactChangeSubscriber CreateSubscriber(IScriptArtifactChangeBus? bus) =>
-        new(_executor, NullLogger<ScriptArtifactChangeSubscriber>.Instance, bus);
+        new(_executor, _methodCache, NullLogger<ScriptArtifactChangeSubscriber>.Instance, bus);

    private Task<InboundScriptResult> Run(ApiMethod m) => _executor.ExecuteAsync(
        m, new Dictionary<string, object?>(), _route, TimeSpan.FromSeconds(10));
@@ -121,6 +122,34 @@ public class ScriptArtifactChangeSubscriberTests
        Assert.Equal(0, _bus.SubscriberCount);
    }

+    /// <summary>
+    /// WP2.6b: an ApiMethod change notification must also drop the resolved-row cache
+    /// entry (not just the compiled handler) — proving EndpointExtensions' next lookup
+    /// re-fetches instead of serving a stale cached row for the rest of the TTL window.
+    /// </summary>
+    [Fact]
+    public async Task ApiMethodPublish_InvalidatesResolvedMethodCache()
+    {
+        var subscriber = CreateSubscriber(_bus);
+        await subscriber.StartAsync(CancellationToken.None);
+
+        var fetchCount = 0;
+        Task<ApiMethod?> Fetch(CancellationToken _)
+        {
+            fetchCount++;
+            return Task.FromResult<ApiMethod?>(new ApiMethod("m", "return 1;") { Id = 1 });
+        }
+
+        await _methodCache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+        await _methodCache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+        Assert.Equal(1, fetchCount); // second call served from cache
+
+        _bus.Publish(ApiMethodChanged("m"));
+
+        await _methodCache.GetOrFetchAsync("m", Fetch, CancellationToken.None);
+        Assert.Equal(2, fetchCount); // cache entry was dropped — re-fetched
+    }
+
    [Fact]
    public async Task NullBus_NoOps()
    {