feat(historian): ServerHistorian:MaxRawValuesPerRead caps raw pages and backend reads

Review R08:1.1: an uncapped HistoryRead-Raw (NumValuesPerNode = 0) read a tag's whole window into memory on every backend (SQL TOP(int.MaxValue), QuestDB LIMIT, Gateway max_values = int.MaxValue + a second snapshot copy). New ServerHistorian:MaxRawValuesPerRead (default 10 000; <= 0 unbounded with a Validate() warning; 1 raised to 2). Each backend data source takes it, reports it as IHistorianDataSource.MaxRawValuesPerRead (the Gateway: min with a strict gateway's learned ceiling), so the node manager's existing RawPageLimit paging serves N = 0 and N > cap as pages of at most the cap with a continuation point. Independently, a backend raw read asking for 0 or more than the cap reads cap + 1 rows and is REFUSED (HistoryReadLimitExceededException => BadTooManyOperations) when the window holds more - never answered truncated, since the server's paging reads a short answer as the last page. Bound through the Host registry, the SqlServer/QuestDb providers and GatewayHistorian.CreateDataSource. Tests: options (default/binding/warnings), provider binding, Gateway unit + through a real SDK node manager (uncapped -> 999/998/998/605 + CPs), and a conformance case for the SQL backends. Refs #736 Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 06:29:10 -04:00
parent ad2b5c4044
commit 6669fae7e5
17 changed files with 621 additions and 33 deletions
@@ -168,4 +168,64 @@ public sealed class ServerHistorianOptionsTests
        }.Validate();
        Assert.Empty(w);
    }
+
+    // ── MaxRawValuesPerRead (R08:1.1, #736) ─────────────────────────────────────────────────────
+
+    [Fact]
+    public void MaxRawValuesPerRead_defaults_to_ten_thousand_and_binds()
+    {
+        var o = new ServerHistorianOptions();
+        Assert.Equal(10_000, o.MaxRawValuesPerRead);
+        Assert.Equal(10_000, ServerHistorianOptions.DefaultMaxRawValuesPerRead);
+        Assert.Equal(10_000, o.EffectiveMaxRawValuesPerRead);
+
+        var bound = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?> { ["ServerHistorian:MaxRawValuesPerRead"] = "2500" })
+            .Build()
+            .GetSection(ServerHistorianOptions.SectionName)
+            .Get<ServerHistorianOptions>()!;
+        Assert.Equal(2500, bound.MaxRawValuesPerRead);
+        Assert.Equal(2500, bound.EffectiveMaxRawValuesPerRead);
+        Assert.Empty(new ServerHistorianOptions
+        {
+            Enabled = true, Endpoint = "https://h:5222", ApiKey = "histgw_x_y", MaxRawValuesPerRead = 2500,
+        }.Validate());
+    }
+
+    [Theory]
+    [InlineData(0)]
+    [InlineData(-5)]
+    public void Nonpositive_MaxRawValuesPerRead_is_unbounded_and_warns_when_enabled(int value)
+    {
+        var o = new ServerHistorianOptions
+        {
+            Enabled = true, Endpoint = "https://h:5222", ApiKey = "histgw_x_y", MaxRawValuesPerRead = value,
+        };
+        Assert.Equal(0, o.EffectiveMaxRawValuesPerRead);
+        var w = o.Validate();
+        var m = Assert.Single(w);
+        Assert.Contains("MaxRawValuesPerRead", m);
+        Assert.Contains("unbounded", m);
+    }
+
+    [Fact]
+    public void A_MaxRawValuesPerRead_of_one_is_raised_to_two_and_warns_when_enabled()
+    {
+        // One row per read cannot carry a page AND the lookahead row that says "more follows" — a fresh page would be refused.
+        var o = new ServerHistorianOptions
+        {
+            Enabled = true, Endpoint = "https://h:5222", ApiKey = "histgw_x_y", MaxRawValuesPerRead = 1,
+        };
+        Assert.Equal(2, o.EffectiveMaxRawValuesPerRead);
+        Assert.Equal(ServerHistorianOptions.MinMaxRawValuesPerRead, o.EffectiveMaxRawValuesPerRead);
+        var m = Assert.Single(o.Validate());
+        Assert.Contains("MaxRawValuesPerRead", m);
+    }
+
+    [Fact]
+    public void Disabled_with_an_odd_MaxRawValuesPerRead_is_silent()
+    {
+        Assert.Empty(new ServerHistorianOptions { Enabled = false, MaxRawValuesPerRead = 0 }.Validate());
+        Assert.Empty(new ServerHistorianOptions { Enabled = false, MaxRawValuesPerRead = 1 }.Validate());
+    }
 }