Initial commit: managed .NET 10 AVEVA Historian SDK + reverse-engineering toolkit

Full read-only SDK (src/AVEVA.Historian.Client) implementing the CLAUDE.md required surface against AVEVA Historian's binary WCF protocol — no native AVEVA runtime dependency. All operations live-verified against a local Historian: - ProbeAsync, ReadRawAsync, ReadAggregateAsync, ReadAtTimeAsync, ReadEventsAsync - BrowseTagNamesAsync, GetTagMetadataAsync (17 native data-type codes mapped) - GetConnectionStatusAsync, GetStoreForwardStatusAsync, GetSystemParameterAsync - 108/108 unit + integration tests pass Includes the reverse-engineering toolkit (tools/AVEVA.Historian.ReverseEngineering) used to decode the protocol: WCF probes, IL inspection via dnlib, and IL-rewrite instrumentation (instrument-wcf-{write,read}message etc.) plus the .NET Framework trace harness (tools/AVEVA.Historian.NativeTraceHarness) for parity testing. Sanitized handoff evidence under docs/reverse-engineering/. Native AVEVA binaries (current/, aveva-install-x64/, aveva-install-x86/) are gitignored — fetch separately from the AVEVA installer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-04 06:31:48 -04:00
commit c95824a65d
230 changed files with 38666 additions and 0 deletions
@@ -0,0 +1,109 @@
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Wcf;
+
+namespace AVEVA.Historian.Client.Tests;
+
+public sealed class WcfDataQueryResultBufferTests
+{
+    // Captured from artifacts/reverse-engineering/instrumented-openconnection3-correlation/capture.ndjson
+    // Wcf.GetNextQueryResultBuffer2.ResultBytes for a 4-row OtOpcUaParityTest_001.Counter Full read.
+    private static readonly byte[] CapturedResultBytes = Convert.FromBase64String(
+        "CQAEAAAA7gAAAB0AAABPAHQATwBwAGMAVQBhAFAAYQByAGkAdAB5AFQAZQBzAHQAXwAwADAAMQAu" +
+        "AEMAbwB1AG4AdABlAHIAAQAAAGvPzFvD2dwBhQAAAPgAAADAAAAAAAAAAAAAAAAAAAAAAABZQAAA" +
+        "AWvPzFvD2dwBAAAAAAAAAAClBtClfAAAAAAAAAAAAAAA7gAAAB0AAABPAHQATwBwAGMAVQBhAFAA" +
+        "YQByAGkAdAB5AFQAZQBzAHQAXwAwADAAMQAuAEMAbwB1AG4AdABlAHIAAQAAABDWnAFA2twBAQAA" +
+        "ABgAAAAYAAAAAAAAAAAAAAAAAAAAAAAAAAAAARDWnAFA2twBAAAAAAAAAAAwZOgAAAAAAAEAAAAA" +
+        "AAAA7gAAAB0AAABPAHQATwBwAGMAVQBhAFAAYQByAGkAdAB5AFQAZQBzAHQAXwAwADAAMQAuAEMA" +
+        "bwB1AG4AdABlAHIAAQAAAEA6hQJA2twBAQAAABgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAUA6" +
+        "hQJA2twBAAAAAAAAAABQwwAAAAAAAAEAAAAAAAAA7gAAAB0AAABPAHQATwBwAGMAVQBhAFAAYQBy" +
+        "AGkAdAB5AFQAZQBzAHQAXwAwADAAMQAuAEMAbwB1AG4AdABlAHIAAQAAAJD9hQJA2twBAAAAAPgA" +
+        "AADAAAAAAAAAAAAAAAAAAAAAAABZQAAAAZD9hQJA2twBAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAA");
+
+    private static readonly byte[] TerminalNoMoreData = Convert.FromBase64String("BB4AAAA=");
+
+    [Fact]
+    public void TryParseGetNextQueryResultBufferRows_ParsesFourCanonicalFixtureRows()
+    {
+        bool ok = HistorianDataQueryProtocol.TryParseGetNextQueryResultBufferRows(
+            CapturedResultBytes,
+            TerminalNoMoreData,
+            out IReadOnlyList<HistorianSample> rows,
+            out bool hasMoreData);
+
+        Assert.True(ok);
+        Assert.False(hasMoreData);
+        Assert.Equal(4, rows.Count);
+
+        Assert.All(rows, r => Assert.Equal("OtOpcUaParityTest_001.Counter", r.TagName));
+
+        HistorianSample row0 = rows[0];
+        Assert.Equal(133, row0.Quality);
+        Assert.Equal(248u, row0.QualityDetail);
+        Assert.Equal(192, row0.OpcQuality);
+        Assert.Equal(0, row0.NumericValue);
+        Assert.Equal(100.0, row0.PercentGood);
+        Assert.Equal(DateTime.FromFileTimeUtc(0x01DCD9C35BCCCF6B), row0.TimestampUtc);
+
+        HistorianSample row3 = rows[3];
+        Assert.Equal(0, row3.Quality);
+        Assert.Equal(248u, row3.QualityDetail);
+        Assert.Equal(192, row3.OpcQuality);
+        Assert.Equal(100.0, row3.PercentGood);
+    }
+
+    [Fact]
+    public void TryParseGetNextQueryResultBufferRows_FlagsContinuationWhenErrorTerminalIsEmpty()
+    {
+        bool ok = HistorianDataQueryProtocol.TryParseGetNextQueryResultBufferRows(
+            CapturedResultBytes,
+            errorTerminal: [],
+            out _,
+            out bool hasMoreData);
+
+        Assert.True(ok);
+        Assert.True(hasMoreData);
+    }
+
+    [Fact]
+    public void TryParseGetNextQueryResultBufferRows_FlagsContinuationWhenErrorIsNotNoMoreData()
+    {
+        bool ok = HistorianDataQueryProtocol.TryParseGetNextQueryResultBufferRows(
+            CapturedResultBytes,
+            errorTerminal: [0x04, 0x01, 0x00, 0x00, 0x00],
+            out _,
+            out bool hasMoreData);
+
+        Assert.True(ok);
+        Assert.True(hasMoreData);
+    }
+
+    [Fact]
+    public void TryParseGetNextQueryResultBufferRows_RejectsBufferWithUnsupportedVersion()
+    {
+        byte[] mangled = (byte[])CapturedResultBytes.Clone();
+        mangled[0] = 0x07;
+
+        bool ok = HistorianDataQueryProtocol.TryParseGetNextQueryResultBufferRows(
+            mangled,
+            TerminalNoMoreData,
+            out IReadOnlyList<HistorianSample> rows,
+            out _);
+
+        Assert.False(ok);
+        Assert.Empty(rows);
+    }
+
+    [Fact]
+    public void TryParseGetNextQueryResultBufferRows_HandlesEmptyResultBuffer()
+    {
+        bool ok = HistorianDataQueryProtocol.TryParseGetNextQueryResultBufferRows(
+            result: [],
+            TerminalNoMoreData,
+            out IReadOnlyList<HistorianSample> rows,
+            out bool hasMoreData);
+
+        Assert.True(ok);
+        Assert.False(hasMoreData);
+        Assert.Empty(rows);
+    }
+}