Merge re/r1.4-gethi-finding: R1.1 ExecuteSqlCommand + R1.4 GetHistorianInfo (bounded)

# Conflicts: # docs/plans/hcal-roadmap.md # src/AVEVA.Historian.Client/HistorianClient.cs # src/AVEVA.Historian.Client/Protocol/Historian2020ProtocolDialect.cs # tests/AVEVA.Historian.Client.Tests/HistorianClientIntegrationTests.cs # tools/AVEVA.Historian.NativeTraceHarness/Program.cs
2026-06-21 16:18:01 -04:00
parent c1b1b3d23b fbd839077b
commit 4de222c950
19 changed files with 1118 additions and 14 deletions
@@ -331,6 +331,65 @@ public sealed class HistorianClientIntegrationTests
        });
    }

+    [Fact]
+    public async Task ExecuteSqlCommandAsync_AgainstLocalHistorian_ReturnsRecordSet()
+    {
+        string? host = Environment.GetEnvironmentVariable("HISTORIAN_HOST");
+        if (string.IsNullOrWhiteSpace(host) || !string.Equals(host, "localhost", StringComparison.OrdinalIgnoreCase) || !OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        HistorianClient client = new(new HistorianClientOptions
+        {
+            Host = host,
+            IntegratedSecurity = true,
+            Transport = HistorianTransport.LocalPipe
+        });
+
+        // ExeC/GetR ride the storage-session GUID as an uppercase string handle. A constant SELECT
+        // returns a single int column; the DataTable is decoded from the NRBF stream (no BinaryFormatter).
+        AVEVA.Historian.Client.Models.HistorianSqlResult result =
+            await client.ExecuteSqlCommandAsync("SELECT 1 AS ProbeValue", cancellationToken: CancellationToken.None);
+
+        AVEVA.Historian.Client.Models.HistorianSqlColumn column = Assert.Single(result.Columns);
+        Assert.Equal("ProbeValue", column.Name);
+        IReadOnlyList<object?> row = Assert.Single(result.Rows);
+        Assert.Equal(1, Assert.Single(row));
+    }
+
+    [Fact]
+    public async Task ExecuteSqlCommandAsync_AgainstLocalHistorian_MultiColumnMultiRow()
+    {
+        string? host = Environment.GetEnvironmentVariable("HISTORIAN_HOST");
+        if (string.IsNullOrWhiteSpace(host) || !string.Equals(host, "localhost", StringComparison.OrdinalIgnoreCase) || !OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        HistorianClient client = new(new HistorianClientOptions
+        {
+            Host = host,
+            IntegratedSecurity = true,
+            Transport = HistorianTransport.LocalPipe
+        });
+
+        // Fully synthetic query (no server data): two columns (int + string), two rows, one NULL —
+        // exercises the schema/diffgram parser beyond the single-cell case.
+        AVEVA.Historian.Client.Models.HistorianSqlResult result = await client.ExecuteSqlCommandAsync(
+            "SELECT 10 AS Num, 'alpha' AS Word UNION ALL SELECT 20, NULL",
+            cancellationToken: CancellationToken.None);
+
+        Assert.Equal(2, result.Columns.Count);
+        Assert.Equal("Num", result.Columns[0].Name);
+        Assert.Equal("Word", result.Columns[1].Name);
+        Assert.Equal(2, result.Rows.Count);
+        Assert.Equal(10, result.Rows[0][0]);
+        Assert.Equal("alpha", result.Rows[0][1]);
+        Assert.Equal(20, result.Rows[1][0]);
+        Assert.Null(result.Rows[1][1]);
+    }
+
    [Fact]
    public async Task GetConnectionStatusAsync_AgainstLocalHistorian_ReportsConnectedToServer()
    {
@@ -66,6 +66,80 @@ public sealed class StringHandleProbeDiagnosticTests
        });
    }

+    /// <summary>
+    /// R1.4 probe: GETHI on 2020 WCF is a named-value query (capture showed the native client
+    /// only ever asks for "HistorianVersion"; the 518-byte struct + EventStorageMode@514 is the
+    /// 2023R2 HCAL-native/gRPC model). This probes whether the 2020 server exposes any
+    /// storage-mode / extended info value through GETHI under other parameter names, so we can
+    /// decide honestly what GetHistorianInfoAsync can return over WCF.
+    /// </summary>
+    [Fact]
+    public void GETHI_CandidateInfoNames_AgainstLocalHistorian()
+    {
+        if (!ShouldRun(out string host)) return;
+
+        HistorianClientOptions options = new()
+        {
+            Host = host,
+            IntegratedSecurity = true,
+            Transport = HistorianTransport.LocalPipe
+        };
+
+        string[] candidates =
+        {
+            "HistorianVersion", "EventStorageMode", "EventStorageType", "StorageType",
+            "HistorianEventStorageMode", "EventStorage", "StorageMode", "HistorianInfo",
+        };
+
+        Dictionary<string, (bool ok, int respLen)> results = new();
+        ProbeOnStatusChannel(options, (channel, handle) =>
+        {
+            foreach (string name in candidates)
+            {
+                using MemoryStream ms = new();
+                using (BinaryWriter w = new(ms, Encoding.Unicode, leaveOpen: true))
+                {
+                    w.Write(new byte[] { 0x53, 0x67, 0x02, 0x00 });
+                    w.Write((uint)name.Length);
+                    w.Write(Encoding.Unicode.GetBytes(name));
+                }
+                byte[] req = ms.ToArray();
+                byte[]? resp = null;
+                byte[]? err = null;
+                bool ok;
+                try
+                {
+                    ok = channel.GetHistorianInfo(handle, req, out resp, out err);
+                }
+                catch (Exception ex)
+                {
+                    _output.WriteLine($"  {name,-26} EXCEPTION {ex.GetType().Name}: {ex.Message}");
+                    results[name] = (false, -1);
+                    continue;
+                }
+                string respHex = resp is { Length: > 0 }
+                    ? Convert.ToHexString(resp.AsSpan(0, Math.Min(48, resp.Length)))
+                    : "(empty)";
+                _output.WriteLine($"  {name,-26} ok={ok} respLen={resp?.Length ?? 0} errLen={err?.Length ?? 0} resp={respHex}");
+                results[name] = (ok, resp?.Length ?? 0);
+            }
+        });
+
+        // Locked finding (2026-06-20): on 2020 WCF, GETHI is a named-value query whose only
+        // working key is HistorianVersion. No storage-mode key is honored — EventStorageMode is
+        // not on the 2020 WCF wire (it is the 2023R2 HCAL-native/gRPC 518-byte-struct path).
+        Assert.True(results["HistorianVersion"].ok);
+        Assert.True(results["HistorianVersion"].respLen > 0);
+        foreach (string storageName in new[]
+                 {
+                     "EventStorageMode", "EventStorageType", "StorageType",
+                     "HistorianEventStorageMode", "EventStorage", "StorageMode",
+                 })
+        {
+            Assert.False(results[storageName].ok, $"unexpected: GETHI honored '{storageName}'");
+        }
+    }
+
    [Fact]
    public void ExeC_WithUppercaseStorageGuid_AgainstLocalHistorian()
    {
@@ -0,0 +1,79 @@
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Protocol;
+using AVEVA.Historian.Client.Wcf;
+
+namespace AVEVA.Historian.Client.Tests;
+
+/// <summary>
+/// Golden tests for the ExeC/GetR SQL result codec. The fixture is the real, clean GetR
+/// <c>pResultBuff</c> captured from the live server for the benign query
+/// <c>SELECT 1 AS ProbeValue</c> (no sensitive data) — an NRBF stream wrapping a
+/// <c>System.Data.DataTable</c> serialized with <c>SerializationFormat.Xml</c>. It is the
+/// contract-level byte[] the WCF channel reassembles (free of MDAS transport chunk markers).
+/// </summary>
+public sealed class WcfSqlResultProtocolTests
+{
+    // GetR pResultBuff for "SELECT 1 AS ProbeValue" (1232 bytes), base64. Captured via the
+    // AVEVA_HISTORIAN_SQL_DUMP diagnostic in HistorianWcfSqlClient.
+    private const string GetRStreamBase64 =
+        "AAEAAAD/////AQAAAAAAAAAMAgAAAE5TeXN0ZW0uRGF0YSwgVmVyc2lvbj00LjAuMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1Ymxp" +
+        "Y0tleVRva2VuPWI3N2E1YzU2MTkzNGUwODkFAQAAABVTeXN0ZW0uRGF0YS5EYXRhVGFibGUDAAAAGURhdGFUYWJsZS5SZW1vdGlu" +
+        "Z1ZlcnNpb24JWG1sU2NoZW1hC1htbERpZmZHcmFtAwEBDlN5c3RlbS5WZXJzaW9uAgAAAAkDAAAABgQAAACJBTw/eG1sIHZlcnNp" +
+        "b249IjEuMCIgZW5jb2Rpbmc9InV0Zi0xNiI/Pg0KPHhzOnNjaGVtYSB4bWxucz0iIiB4bWxuczp4cz0iaHR0cDovL3d3dy53My5v" +
+        "cmcvMjAwMS9YTUxTY2hlbWEiIHhtbG5zOm1zZGF0YT0idXJuOnNjaGVtYXMtbWljcm9zb2Z0LWNvbTp4bWwtbXNkYXRhIj4NCiAg" +
+        "PHhzOmVsZW1lbnQgbmFtZT0iVGFibGUxIj4NCiAgICA8eHM6Y29tcGxleFR5cGU+DQogICAgICA8eHM6c2VxdWVuY2U+DQogICAg" +
+        "ICAgIDx4czplbGVtZW50IG5hbWU9IlByb2JlVmFsdWUiIG1zZGF0YTpSZWFkT25seT0idHJ1ZSIgdHlwZT0ieHM6aW50IiBtc2Rh" +
+        "dGE6dGFyZ2V0TmFtZXNwYWNlPSIiIC8+DQogICAgICA8L3hzOnNlcXVlbmNlPg0KICAgIDwveHM6Y29tcGxleFR5cGU+DQogIDwv" +
+        "eHM6ZWxlbWVudD4NCiAgPHhzOmVsZW1lbnQgbmFtZT0idG1wRGF0YVNldCIgbXNkYXRhOklzRGF0YVNldD0idHJ1ZSIgbXNkYXRh" +
+        "Ok1haW5EYXRhVGFibGU9IlRhYmxlMSIgbXNkYXRhOlVzZUN1cnJlbnRMb2NhbGU9InRydWUiPg0KICAgIDx4czpjb21wbGV4VHlw" +
+        "ZT4NCiAgICAgIDx4czpjaG9pY2UgbWluT2NjdXJzPSIwIiBtYXhPY2N1cnM9InVuYm91bmRlZCIgLz4NCiAgICA8L3hzOmNvbXBs" +
+        "ZXhUeXBlPg0KICA8L3hzOmVsZW1lbnQ+DQo8L3hzOnNjaGVtYT4GBQAAAJoCPGRpZmZncjpkaWZmZ3JhbSB4bWxuczptc2RhdGE9" +
+        "InVybjpzY2hlbWFzLW1pY3Jvc29mdC1jb206eG1sLW1zZGF0YSIgeG1sbnM6ZGlmZmdyPSJ1cm46c2NoZW1hcy1taWNyb3NvZnQt" +
+        "Y29tOnhtbC1kaWZmZ3JhbS12MSI+DQogIDx0bXBEYXRhU2V0Pg0KICAgIDxUYWJsZTEgZGlmZmdyOmlkPSJUYWJsZTExIiBtc2Rh" +
+        "dGE6cm93T3JkZXI9IjAiPg0KICAgICAgPFByb2JlVmFsdWU+MTwvUHJvYmVWYWx1ZT4NCiAgICA8L1RhYmxlMT4NCiAgPC90bXBE" +
+        "YXRhU2V0Pg0KPC9kaWZmZ3I6ZGlmZmdyYW0+BAMAAAAOU3lzdGVtLlZlcnNpb24EAAAABl9NYWpvcgZfTWlub3IGX0J1aWxkCV9S" +
+        "ZXZpc2lvbgAAAAAICAgIAgAAAAAAAAD//////////ws=";
+
+    [Fact]
+    public void Parse_DataTableStream_ExtractsColumnAndTypedRow()
+    {
+        byte[] stream = Convert.FromBase64String(GetRStreamBase64);
+
+        HistorianSqlResult result = HistorianSqlResultProtocol.Parse(stream, returnValue: 0);
+
+        HistorianSqlColumn column = Assert.Single(result.Columns);
+        Assert.Equal("ProbeValue", column.Name);
+        Assert.Equal("xs:int", column.SchemaType);
+
+        IReadOnlyList<object?> row = Assert.Single(result.Rows);
+        object? value = Assert.Single(row);
+        Assert.Equal(1, value);                  // typed to int per the xs:int schema
+        Assert.IsType<int>(value);
+        Assert.Equal(0, result.ReturnValue);
+    }
+
+    [Fact]
+    public void Parse_PreservesReturnValue()
+    {
+        byte[] stream = Convert.FromBase64String(GetRStreamBase64);
+        HistorianSqlResult result = HistorianSqlResultProtocol.Parse(stream, returnValue: 7);
+        Assert.Equal(7, result.ReturnValue);
+    }
+
+    [Fact]
+    public void Parse_EmptyBuffer_ReturnsEmptyResult()
+    {
+        HistorianSqlResult result = HistorianSqlResultProtocol.Parse(ReadOnlyMemory<byte>.Empty, returnValue: 3);
+        Assert.Empty(result.Columns);
+        Assert.Empty(result.Rows);
+        Assert.Equal(3, result.ReturnValue);
+    }
+
+    [Fact]
+    public void Parse_NonNrbfBuffer_Throws()
+    {
+        byte[] garbage = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08];
+        Assert.Throws<ProtocolEvidenceMissingException>(
+            () => HistorianSqlResultProtocol.Parse(garbage, returnValue: 0));
+    }
+}