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,9 @@
+namespace AVEVA.Historian.Client.Protocol;
+
+internal sealed class FrameFormatException : Exception
+{
+    public FrameFormatException(string message)
+        : base(message)
+    {
+    }
+}
@@ -0,0 +1,163 @@
+using System.Runtime.InteropServices;
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Wcf;
+
+namespace AVEVA.Historian.Client.Protocol;
+
+internal sealed class Historian2020ProtocolDialect
+{
+    private readonly HistorianClientOptions _options;
+
+    public Historian2020ProtocolDialect(HistorianClientOptions options)
+    {
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+    }
+
+    public IAsyncEnumerable<HistorianSample> ReadRawAsync(string tag, DateTime startUtc, DateTime endUtc, int maxValues, CancellationToken cancellationToken)
+    {
+        if (_options.Transport != HistorianTransport.LocalPipe)
+        {
+            return Missing<HistorianSample>($"StartDataRetrievalQuery/Full over {_options.Transport}", cancellationToken);
+        }
+
+        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            return Missing<HistorianSample>("StartDataRetrievalQuery/Full requires Windows for the LocalPipe + SSPI path", cancellationToken);
+        }
+
+        return ReadRawWindowsAsync(tag, startUtc, endUtc, maxValues, cancellationToken);
+    }
+
+    private IAsyncEnumerable<HistorianSample> ReadRawWindowsAsync(string tag, DateTime startUtc, DateTime endUtc, int maxValues, CancellationToken cancellationToken)
+    {
+#pragma warning disable CA1416 // Validated by RuntimeInformation.IsOSPlatform check above.
+        HistorianWcfReadOrchestrator orchestrator = new(_options);
+        return orchestrator.ReadRawAsync(tag, startUtc, endUtc, maxValues, cancellationToken);
+#pragma warning restore CA1416
+    }
+
+    public IAsyncEnumerable<HistorianAggregateSample> ReadAggregateAsync(string tag, DateTime startUtc, DateTime endUtc, RetrievalMode mode, TimeSpan interval, CancellationToken cancellationToken)
+    {
+        if (_options.Transport != HistorianTransport.LocalPipe)
+        {
+            return Missing<HistorianAggregateSample>($"StartDataRetrievalQuery/{mode} over {_options.Transport}", cancellationToken);
+        }
+
+        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            return Missing<HistorianAggregateSample>($"StartDataRetrievalQuery/{mode} requires Windows for the LocalPipe + SSPI path", cancellationToken);
+        }
+
+        return ReadAggregateWindowsAsync(tag, startUtc, endUtc, mode, interval, cancellationToken);
+    }
+
+    private IAsyncEnumerable<HistorianAggregateSample> ReadAggregateWindowsAsync(string tag, DateTime startUtc, DateTime endUtc, RetrievalMode mode, TimeSpan interval, CancellationToken cancellationToken)
+    {
+#pragma warning disable CA1416
+        HistorianWcfReadOrchestrator orchestrator = new(_options);
+        return orchestrator.ReadAggregateAsync(tag, startUtc, endUtc, mode, interval, cancellationToken);
+#pragma warning restore CA1416
+    }
+
+    public Task<IReadOnlyList<HistorianSample>> ReadAtTimeAsync(string tag, IReadOnlyList<DateTime> timestampsUtc, CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        if (_options.Transport != HistorianTransport.LocalPipe)
+        {
+            throw new ProtocolEvidenceMissingException($"StartDataRetrievalQuery/Interpolated at-time over {_options.Transport}");
+        }
+
+        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            throw new ProtocolEvidenceMissingException("StartDataRetrievalQuery/Interpolated at-time requires Windows for the LocalPipe + SSPI path");
+        }
+
+#pragma warning disable CA1416
+        HistorianWcfReadOrchestrator orchestrator = new(_options);
+        return orchestrator.ReadAtTimeAsync(tag, timestampsUtc, cancellationToken);
+#pragma warning restore CA1416
+    }
+
+    public IAsyncEnumerable<HistorianBlock> ReadBlocksAsync(string tag, DateTime startUtc, DateTime endUtc, CancellationToken cancellationToken)
+    {
+        return Missing<HistorianBlock>("StartBlockRetrievalQuery", cancellationToken);
+    }
+
+    public IAsyncEnumerable<HistorianEvent> ReadEventsAsync(DateTime startUtc, DateTime endUtc, CancellationToken cancellationToken)
+    {
+        if (_options.Transport != HistorianTransport.LocalPipe)
+        {
+            return Missing<HistorianEvent>($"StartEventDataRetrievalQuery over {_options.Transport}", cancellationToken);
+        }
+
+        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            return Missing<HistorianEvent>("StartEventDataRetrievalQuery requires Windows for the LocalPipe + SSPI path", cancellationToken);
+        }
+
+        return ReadEventsWindowsAsync(startUtc, endUtc, cancellationToken);
+    }
+
+    private IAsyncEnumerable<HistorianEvent> ReadEventsWindowsAsync(DateTime startUtc, DateTime endUtc, CancellationToken cancellationToken)
+    {
+#pragma warning disable CA1416
+        HistorianWcfEventOrchestrator orchestrator = new(_options);
+        return orchestrator.ReadEventsAsync(startUtc, endUtc, cancellationToken);
+#pragma warning restore CA1416
+    }
+
+    public IAsyncEnumerable<string> BrowseTagNamesAsync(string filter, CancellationToken cancellationToken)
+    {
+        return Missing<string>("StartLikeTagNameSearch/GetLikeTagnames", cancellationToken);
+    }
+
+    public Task<HistorianTagMetadata?> GetTagMetadataAsync(string tag, CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        throw new ProtocolEvidenceMissingException("GetTagInfoByName/GetTagInfos");
+    }
+
+    public Task<HistorianConnectionStatus> GetConnectionStatusAsync(CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        if (!OperatingSystem.IsWindows())
+        {
+            throw new ProtocolEvidenceMissingException("GetConnectionStatus on non-Windows");
+        }
+        return Wcf.HistorianWcfStatusClient.GetConnectionStatusAsync(_options, cancellationToken);
+    }
+
+    public Task<HistorianStoreForwardStatus> GetStoreForwardStatusAsync(CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        if (!OperatingSystem.IsWindows())
+        {
+            throw new ProtocolEvidenceMissingException("GetStoreForwardStatus on non-Windows");
+        }
+        return Wcf.HistorianWcfStatusClient.GetStoreForwardStatusAsync(_options, cancellationToken);
+    }
+
+    public Task<string?> GetSystemParameterAsync(string name, CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        ArgumentException.ThrowIfNullOrWhiteSpace(name);
+        if (!OperatingSystem.IsWindows())
+        {
+            throw new ProtocolEvidenceMissingException("GetSystemParameter on non-Windows");
+        }
+        return Wcf.HistorianWcfStatusClient.GetSystemParameterAsync(_options, name, cancellationToken);
+    }
+
+    private static async IAsyncEnumerable<T> Missing<T>(
+        string operation,
+        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        await Task.Yield();
+        cancellationToken.ThrowIfCancellationRequested();
+        throw new ProtocolEvidenceMissingException(operation);
+#pragma warning disable CS0162
+        yield break;
+#pragma warning restore CS0162
+    }
+}
@@ -0,0 +1,50 @@
+using System.Buffers.Binary;
+using System.Text;
+
+namespace AVEVA.Historian.Client.Protocol;
+
+internal static class HistorianBinaryPrimitives
+{
+    public static long ToFileTimeUtc(DateTime value)
+    {
+        return value.Kind == DateTimeKind.Unspecified
+            ? DateTime.SpecifyKind(value, DateTimeKind.Utc).ToFileTimeUtc()
+            : value.ToUniversalTime().ToFileTimeUtc();
+    }
+
+    public static void WriteUInt16LittleEndian(Stream stream, ushort value)
+    {
+        Span<byte> buffer = stackalloc byte[sizeof(ushort)];
+        BinaryPrimitives.WriteUInt16LittleEndian(buffer, value);
+        stream.Write(buffer);
+    }
+
+    public static void WriteUInt32LittleEndian(Stream stream, uint value)
+    {
+        Span<byte> buffer = stackalloc byte[sizeof(uint)];
+        BinaryPrimitives.WriteUInt32LittleEndian(buffer, value);
+        stream.Write(buffer);
+    }
+
+    public static void WriteUInt64LittleEndian(Stream stream, ulong value)
+    {
+        Span<byte> buffer = stackalloc byte[sizeof(ulong)];
+        BinaryPrimitives.WriteUInt64LittleEndian(buffer, value);
+        stream.Write(buffer);
+    }
+
+    public static void WriteFileTimeUtc(Stream stream, DateTime value)
+    {
+        WriteUInt64LittleEndian(stream, unchecked((ulong)ToFileTimeUtc(value)));
+    }
+
+    public static void WriteUtf16NullTerminated(Stream stream, string value)
+    {
+        ArgumentNullException.ThrowIfNull(value);
+
+        byte[] bytes = Encoding.Unicode.GetBytes(value);
+        stream.Write(bytes);
+        stream.WriteByte(0);
+        stream.WriteByte(0);
+    }
+}
@@ -0,0 +1,75 @@
+using AVEVA.Historian.Client.Transport;
+
+namespace AVEVA.Historian.Client.Protocol;
+
+internal sealed class HistorianConnection : IAsyncDisposable
+{
+    private readonly HistorianClientOptions _options;
+    private readonly IHistorianTransport _transport;
+
+    public HistorianConnection(HistorianClientOptions options, IHistorianTransport transport)
+    {
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+        _transport = transport ?? throw new ArgumentNullException(nameof(transport));
+    }
+
+    public async ValueTask ConnectTcpAsync(CancellationToken cancellationToken)
+    {
+        using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        timeout.CancelAfter(_options.ConnectTimeout);
+        await _transport.ConnectAsync(_options, timeout.Token).ConfigureAwait(false);
+    }
+
+    public ValueTask OpenProtocolSessionAsync(CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        throw new ProtocolEvidenceMissingException("OpenConnection handshake");
+    }
+
+    public async ValueTask SendFrameAsync(HistorianFrame frame, CancellationToken cancellationToken)
+    {
+        byte[] buffer = HistorianFrameWriter.ToArray(frame);
+        await _transport.SendAsync(buffer, cancellationToken).ConfigureAwait(false);
+    }
+
+    public async ValueTask<HistorianFrame> ReceiveFrameAsync(CancellationToken cancellationToken)
+    {
+        using MemoryStream frameBytes = new();
+        byte[] header = new byte[HistorianFrameReader.HeaderSize];
+        await ReadTransportExactlyAsync(header, cancellationToken).ConfigureAwait(false);
+        frameBytes.Write(header);
+
+        int frameLength = BitConverter.ToInt32(header, 0);
+        if (frameLength < HistorianFrameReader.HeaderSize || frameLength > HistorianFrameReader.MaxFrameSize)
+        {
+            throw new FrameFormatException($"Invalid frame length {frameLength}.");
+        }
+
+        byte[] payload = new byte[frameLength - HistorianFrameReader.HeaderSize];
+        await ReadTransportExactlyAsync(payload, cancellationToken).ConfigureAwait(false);
+        frameBytes.Write(payload);
+        frameBytes.Position = 0;
+
+        return await HistorianFrameReader.ReadAsync(frameBytes, cancellationToken).ConfigureAwait(false);
+    }
+
+    public ValueTask DisposeAsync()
+    {
+        return _transport.DisposeAsync();
+    }
+
+    private async ValueTask ReadTransportExactlyAsync(Memory<byte> buffer, CancellationToken cancellationToken)
+    {
+        int offset = 0;
+        while (offset < buffer.Length)
+        {
+            int read = await _transport.ReceiveAsync(buffer[offset..], cancellationToken).ConfigureAwait(false);
+            if (read == 0)
+            {
+                throw new EndOfStreamException("Unexpected end of stream from Historian transport.");
+            }
+
+            offset += read;
+        }
+    }
+}
@@ -0,0 +1,6 @@
+namespace AVEVA.Historian.Client.Protocol;
+
+internal readonly record struct HistorianFrame(
+    HistorianMessageType MessageType,
+    uint CorrelationId,
+    ReadOnlyMemory<byte> Payload);
@@ -0,0 +1,45 @@
+using System.Buffers.Binary;
+
+namespace AVEVA.Historian.Client.Protocol;
+
+internal static class HistorianFrameReader
+{
+    public const int HeaderSize = 10;
+    public const int MaxFrameSize = 16 * 1024 * 1024;
+
+    public static async ValueTask<HistorianFrame> ReadAsync(Stream stream, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(stream);
+
+        byte[] header = new byte[HeaderSize];
+        await ReadExactlyAsync(stream, header, cancellationToken).ConfigureAwait(false);
+
+        int frameLength = BinaryPrimitives.ReadInt32LittleEndian(header.AsSpan(0, 4));
+        if (frameLength < HeaderSize || frameLength > MaxFrameSize)
+        {
+            throw new FrameFormatException($"Invalid frame length {frameLength}.");
+        }
+
+        ushort messageType = BinaryPrimitives.ReadUInt16LittleEndian(header.AsSpan(4, 2));
+        uint correlationId = BinaryPrimitives.ReadUInt32LittleEndian(header.AsSpan(6, 4));
+        byte[] payload = new byte[frameLength - HeaderSize];
+        await ReadExactlyAsync(stream, payload, cancellationToken).ConfigureAwait(false);
+
+        return new HistorianFrame((HistorianMessageType)messageType, correlationId, payload);
+    }
+
+    private static async ValueTask ReadExactlyAsync(Stream stream, Memory<byte> buffer, CancellationToken cancellationToken)
+    {
+        int offset = 0;
+        while (offset < buffer.Length)
+        {
+            int read = await stream.ReadAsync(buffer[offset..], cancellationToken).ConfigureAwait(false);
+            if (read == 0)
+            {
+                throw new EndOfStreamException("Unexpected end of stream while reading Historian frame.");
+            }
+
+            offset += read;
+        }
+    }
+}
@@ -0,0 +1,27 @@
+using System.Buffers.Binary;
+
+namespace AVEVA.Historian.Client.Protocol;
+
+internal static class HistorianFrameWriter
+{
+    public static void Write(Stream stream, HistorianFrame frame)
+    {
+        ArgumentNullException.ThrowIfNull(stream);
+
+        int frameLength = HistorianFrameReader.HeaderSize + frame.Payload.Length;
+        Span<byte> header = stackalloc byte[HistorianFrameReader.HeaderSize];
+        BinaryPrimitives.WriteInt32LittleEndian(header[0..4], frameLength);
+        BinaryPrimitives.WriteUInt16LittleEndian(header[4..6], (ushort)frame.MessageType);
+        BinaryPrimitives.WriteUInt32LittleEndian(header[6..10], frame.CorrelationId);
+
+        stream.Write(header);
+        stream.Write(frame.Payload.Span);
+    }
+
+    public static byte[] ToArray(HistorianFrame frame)
+    {
+        using MemoryStream stream = new();
+        Write(stream, frame);
+        return stream.ToArray();
+    }
+}
@@ -0,0 +1,6 @@
+namespace AVEVA.Historian.Client.Protocol;
+
+internal enum HistorianMessageType : ushort
+{
+    Unknown = 0
+}
@@ -0,0 +1,9 @@
+namespace AVEVA.Historian.Client.Protocol;
+
+internal static class HistorianProtocolFacts
+{
+    public const int DefaultTcpPort = 32568;
+    public const int DataQueryResultRowSizeBytes = 544;
+    public const int EventQueryFiltersSizeBytes = 72;
+    public const string QueryTimezone = "UTC";
+}