M2: implement SendEventAsync — event-send rides WCF AddS2, not the storage pipe

Roadmap Milestone 2 (event sending). Capture disproved the assumption that event delivery uses the non-WCF storage-engine pipe (which would block it like revision writes): a native AddStreamedValue(HistorianEvent) leaves over WCF as AddS2 (IHistoryServiceContract2.AddStreamValues2). CM_EVENT is a built-in registered tag, so the 129 TagNotFoundInCache gate that blocks AddS2 for user tags does not apply. - R2.1: NativeTraceHarness "event-send" scenario + Capture-EventSend.ps1; two captures diffed to separate constant framing from value-dependent fields. - R2.2: HistorianEventWriteProtocol serializes the AddS2 pBuf (storage sample buffer wrapping the event VTQ) — golden-byte tested. Decoded "OS" sig + length fields + CM_EVENT tag id + EventTime/ReceivedTime FILETIMEs + Opc 192 + 0x118D descriptor + event Id + Namespace + EventType + version 5 + typed property bag. - R2.3/R2.4: HistorianWcfEventOrchestrator.SendEventAsync (Open2 event-mode 0x501 -> reuse CM_EVENT RTag2/EnsT2 -> AddStreamValues2) + HistorianClient.SendEventAsync. - R2.5: gated live test; server accepts the AddS2 (success, empty error buffer). Server requires delivered byte[].Length == declared packet length (uint32@0x04); the native relies on the MDAS encoder adding a pad byte, so the SDK emits an explicit trailing 0x00 (else AddS2 rejects with "CValuStream buffer size vs packet length mismatch"). Original events only (RevisionVersion=0) with string properties; other property types + revision/update/delete throw ProtocolEvidenceMissingException. Caveat (documented): accepted events are not persisted on the local dev box; the native client behaves identically (event ingestion pipeline inactive) — not an SDK gap. 212 unit tests pass; 16/16 event tests pass live. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC
2026-06-20 18:00:52 -04:00
parent 1a7519c803
commit f1e23a3a02
11 changed files with 920 additions and 16 deletions
@@ -0,0 +1,92 @@
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Wcf;
+
+namespace AVEVA.Historian.Client.Tests;
+
+public sealed class WcfEventWriteProtocolTests
+{
+    // Golden bytes captured from a native AddStreamedValue(HistorianEvent) over WCF (AddS2.pBuf),
+    // instrument-wcf-writemessage, event-send capture A (Type="User.Write").
+    private const string CaptureAddS2PBufBase64 =
+        "T1MBANMAAADJAEWBOzXwXUZNolOHGu9JsyHwZ9L7+QDdAcAAwACNEbJ2OdoXacNJkFutCzR+krSAst37" +
+        "+QDdAQkSAFJldGVzdFNka0V2ZW50U2VuZAkKAFVzZXIuV3JpdGUFAAIACQYAU291cmNlQyYAEgBSAGUA" +
+        "dABlAHMAdABTAGQAawBFAHYAZQBuAHQAUwBlAG4AZAAJCgBUZXN0TWFya2VyQyoAFABoAGkAcwB0AHMA" +
+        "ZABrAC0AUgAyAC4AMQAtAGMAYQBwAHQAdQByAGUA";
+
+    [Fact]
+    public void SerializeAddStreamValuesBufferMatchesInstrumentedNativeEventSend()
+    {
+        // Exact field values recovered from capture A's pBuf.
+        Guid eventId = new("da3976b2-6917-49c3-905b-ad0b347e92b4");
+        DateTime eventTimeUtc = DateTime.FromFileTimeUtc(134264637562710000L);
+        DateTime receivedTimeUtc = DateTime.FromFileTimeUtc(134264637563449984L);
+
+        HistorianEvent evt = new(
+            Id: eventId,
+            EventTimeUtc: eventTimeUtc,
+            ReceivedTimeUtc: receivedTimeUtc,
+            Type: "User.Write",
+            SourceName: string.Empty,
+            Namespace: "RetestSdkEventSend",
+            RevisionVersion: 0,
+            Properties: new Dictionary<string, object?>
+            {
+                ["Source"] = "RetestSdkEventSend",
+                ["TestMarker"] = "histsdk-R2.1-capture",
+            });
+
+        // The capture's MDAS length marker excluded the final trailing pad byte, so the golden
+        // bytes are the 210-byte deterministic content; the serializer appends one pad byte
+        // (total 211) to satisfy the server's packet-length == buffer-size check.
+        byte[] expectedContent = Convert.FromBase64String(CaptureAddS2PBufBase64);
+        byte[] actual = HistorianEventWriteProtocol.SerializeAddStreamValuesBuffer(evt, receivedTimeUtc);
+
+        Assert.Equal(expectedContent.Length + 1, actual.Length);
+        Assert.Equal(expectedContent, actual[..expectedContent.Length]);
+        Assert.Equal(0, actual[^1]);
+        // The declared packet length (UInt32 @0x04) equals the delivered buffer length.
+        Assert.Equal((uint)actual.Length, BitConverter.ToUInt32(actual, 4));
+    }
+
+    [Fact]
+    public void BufferFramingFieldsAreDerivedFromValueBlobLength()
+    {
+        HistorianEvent evt = new(
+            Id: new("da3976b2-6917-49c3-905b-ad0b347e92b4"),
+            EventTimeUtc: DateTime.FromFileTimeUtc(134264637562710000L),
+            ReceivedTimeUtc: DateTime.FromFileTimeUtc(134264637563449984L),
+            Type: "User.Write",
+            SourceName: string.Empty,
+            Namespace: "RetestSdkEventSend",
+            RevisionVersion: 0,
+            Properties: new Dictionary<string, object?> { ["Source"] = "RetestSdkEventSend", ["TestMarker"] = "histsdk-R2.1-capture" });
+
+        byte[] buf = HistorianEventWriteProtocol.SerializeAddStreamValuesBuffer(evt, evt.ReceivedTimeUtc);
+
+        Assert.Equal(0x534F, BitConverter.ToUInt16(buf, 0)); // "OS"
+        Assert.Equal(1, BitConverter.ToUInt16(buf, 2));      // sampleCount
+        // Declared packet length (UInt32 @0x04) equals the delivered buffer length (incl. pad).
+        Assert.Equal((uint)buf.Length, BitConverter.ToUInt32(buf, 4));
+        // Inner length (UInt16 @0x08) = buffer length - 10.
+        Assert.Equal((ushort)(buf.Length - 10), BitConverter.ToUInt16(buf, 8));
+        // CM_EVENT tag id at the head of the value blob.
+        Assert.Equal(HistorianEventWriteProtocol.CmEventTagId, new Guid(buf.AsSpan(10, 16).ToArray()));
+    }
+
+    [Fact]
+    public void NonStringPropertyValueThrowsProtocolEvidenceMissing()
+    {
+        HistorianEvent evt = new(
+            Id: Guid.NewGuid(),
+            EventTimeUtc: new DateTime(2026, 6, 20, 12, 0, 0, DateTimeKind.Utc),
+            ReceivedTimeUtc: new DateTime(2026, 6, 20, 12, 0, 0, DateTimeKind.Utc),
+            Type: "User.Write",
+            SourceName: string.Empty,
+            Namespace: "ns",
+            RevisionVersion: 0,
+            Properties: new Dictionary<string, object?> { ["Count"] = 5 });
+
+        Assert.Throws<ProtocolEvidenceMissingException>(
+            () => HistorianEventWriteProtocol.SerializeAddStreamValuesBuffer(evt, evt.ReceivedTimeUtc));
+    }
+}