perf(worker): batch frames skip per-frame TCS; stream the alarm-poll XML (mxaccessgw#177)

R21-K12: WorkerFrameWriter.WriteBatchAsync allocated a TaskCompletionSource
(plus its Task) per frame on the event drain hot path. PendingFrame now holds
its terminal state itself (Interlocked pending/succeeded/faulted/canceled) and
only single-frame WriteAsync frames, which race their completion against the
write lock, get a TCS. A batch caller reads each frame's outcome after its own
drain pass: every frame a pass claims is terminal before that pass releases the
lock, so nothing is left to await. First-failure-in-batch-order, tombstoning,
claim/cancel interlock and flush coalescing are unchanged.

R21-K13: WnWrapAlarmConsumer.ParseSnapshotXml streams the GetXmlCurrentAlarms2
payload with an XmlTextReader (same defaults XmlDocument.LoadXml uses:
Normalization off, DTDs parsed, no resolver; Significant whitespace only)
instead of building a full XmlDocument every 500 ms poll.

Behaviour is pinned by new tests: batch first-failure ordering (own drain and
drained by another lock holder), batch cancellation tombstoning, batch flush
failure, and a differential test running the replaced XmlDocument parser as an
oracle over a 48-payload corpus (CRLF, CDATA, entities, DTD, namespaces,
nesting, malformed). Mutation checks on windev: 8 of 8 injected regressions
(whitespace, normalization, DTD, namespace, CDATA, batch last-failure, batch
ignored failures, ignored tombstone) fail the new tests.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 13:10:16 -05:00
parent 7d44ecd62d
commit 29d9510b4e
5 changed files with 790 additions and 69 deletions
+1 -1
View File
@@ -511,7 +511,7 @@ behavior.
| `MxGateway:Alarms:DefaultArea` | _(empty)_ | Area name used to compose a default subscription when `SubscriptionExpression` is empty. If both are empty while `Enabled` is `true`, the monitor faults with a configuration diagnostic. | | `MxGateway:Alarms:DefaultArea` | _(empty)_ | Area name used to compose a default subscription when `SubscriptionExpression` is empty. If both are empty while `Enabled` is `true`, the monitor faults with a configuration diagnostic. |
| `MxGateway:Alarms:ReconcileIntervalSeconds` | `30` | How often the monitor re-resolves and, on material change, hot-swaps the subtag fallback watch-list, then reconciles its in-process alarm cache against the worker's authoritative active-alarm snapshot. The acknowledged watch-list fingerprint advances only after an OK worker reply. Floored at 5 seconds. | | `MxGateway:Alarms:ReconcileIntervalSeconds` | `30` | How often the monitor re-resolves and, on material change, hot-swaps the subtag fallback watch-list, then reconciles its in-process alarm cache against the worker's authoritative active-alarm snapshot. The acknowledged watch-list fingerprint advances only after an OK worker reply. Floored at 5 seconds. |
| `MxGateway:Alarms:PollIntervalMilliseconds` | `500` | Cadence at which the worker's STA polls the AVEVA alarm consumer (`GetXmlCurrentAlarms2`) for the active-alarm snapshot the live feed diffs. Must be between `100` and `3600000` (one hour): every poll is a COM call plus an XML parse on the same STA that serves reads and writes, so a tighter cadence starves the command path, while a value above an hour stops being a cadence and silently disables alarm polling. The gateway conveys the value to the worker via the `MXGATEWAY_ALARM_POLL_INTERVAL_MS` environment variable; a missing or out-of-range value leaves the worker on the 500 ms default rather than failing the session. | | `MxGateway:Alarms:PollIntervalMilliseconds` | `500` | Cadence at which the worker's STA polls the AVEVA alarm consumer (`GetXmlCurrentAlarms2`) for the active-alarm snapshot the live feed diffs. Must be between `100` and `3600000` (one hour): every poll is a COM call plus an XML parse on the same STA that serves reads and writes, so a tighter cadence starves the command path, while a value above an hour stops being a cadence and silently disables alarm polling. The gateway conveys the value to the worker via the `MXGATEWAY_ALARM_POLL_INTERVAL_MS` environment variable; a missing or out-of-range value leaves the worker on the 500 ms default rather than failing the session. |
| `MxGateway:Alarms:MaxAlarmsPerFetch` | `1024` | Cap the worker passes to `GetXmlCurrentAlarms2`'s `maxAlmCnt`. Must be between `64` and `65536` — the worker is a 32-bit process that materializes each reply as one BSTR plus a full `XmlDocument`, so an unbounded cap faults the STA with an out-of-memory rather than merely slowing it. It doubles as the **truncation threshold**: a fetch returning exactly this many records is treated as truncated, because the COM API caps its reply with no "more available" flag. On a truncated poll the worker retains the alarms the capped reply could not mention instead of letting their absence read as a clear, and logs a rate-limited `AlarmSnapshotTruncated` warning to its stderr (identifiers and counts only). **Remediation when you see that warning: raise this value** so the steady-state active-alarm count fits inside one fetch. A galaxy permanently above the cap holds stale entries in the snapshot until a sub-cap poll, and loses clear→re-raise cycles that happen entirely out of window (see `docs/DesignDecisions.md`). Conveyed to the worker via the `MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH` environment variable; a missing or out-of-range value leaves the worker on the 1024 default. | | `MxGateway:Alarms:MaxAlarmsPerFetch` | `1024` | Cap the worker passes to `GetXmlCurrentAlarms2`'s `maxAlmCnt`. Must be between `64` and `65536` — the worker is a 32-bit process that materializes each reply as one BSTR (streamed into one record per alarm, not a DOM), so an unbounded cap faults the STA with an out-of-memory rather than merely slowing it. It doubles as the **truncation threshold**: a fetch returning exactly this many records is treated as truncated, because the COM API caps its reply with no "more available" flag. On a truncated poll the worker retains the alarms the capped reply could not mention instead of letting their absence read as a clear, and logs a rate-limited `AlarmSnapshotTruncated` warning to its stderr (identifiers and counts only). **Remediation when you see that warning: raise this value** so the steady-state active-alarm count fits inside one fetch. A galaxy permanently above the cap holds stale entries in the snapshot until a sub-cap poll, and loses clear→re-raise cycles that happen entirely out of window (see `docs/DesignDecisions.md`). Conveyed to the worker via the `MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH` environment variable; a missing or out-of-range value leaves the worker on the 1024 default. |
| `MxGateway:Alarms:AckClientName` | `MxGateway` | MXAccess client name the alarm worker's ack writer registers with; the Historian records it as each acknowledgement's OperatorNode. 1-64 printable characters. Conveyed via `MXGATEWAY_ALARM_ACK_CLIENT_NAME`. | | `MxGateway:Alarms:AckClientName` | `MxGateway` | MXAccess client name the alarm worker's ack writer registers with; the Historian records it as each acknowledgement's OperatorNode. 1-64 printable characters. Conveyed via `MXGATEWAY_ALARM_ACK_CLIENT_NAME`. |
The alarm monitor is independent of client sessions: `AcknowledgeAlarm` and The alarm monitor is independent of client sessions: `AcknowledgeAlarm` and
@@ -912,6 +912,146 @@ public sealed class WorkerFrameProtocolTests
Assert.Equal(WorkerEnvelope.BodyOneofCase.WorkerEvent, f4.BodyCase); Assert.Equal(WorkerEnvelope.BodyOneofCase.WorkerEvent, f4.BodyCase);
} }
/// <summary>
/// A batch with per-frame rejections surfaces the first failure in <em>batch</em> order, not in
/// completion order, and still writes every acceptable frame with contiguous sequences. Run in
/// both orders so a writer that reported the last failure, or a fixed failure kind, cannot pass.
/// Pins the batch-completion contract the per-frame-TCS removal (#177) must keep.
/// </summary>
/// <param name="oversizedFirst">Whether the oversized frame precedes the body-less one.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(true)]
[InlineData(false)]
public async Task WriteBatchAsync_WithPerFrameRejections_SurfacesFirstFailureInBatchOrder(bool oversizedFirst)
{
WorkerFrameProtocolOptions options = CreateBatchRejectionOptions();
using FlushCountingStream stream = new();
WorkerFrameWriter writer = new(stream, options);
WorkerEnvelope[] batch = CreateBatchWithTwoRejections(oversizedFirst);
WorkerFrameProtocolException exception = await Assert.ThrowsAsync<WorkerFrameProtocolException>(
async () => await writer.WriteBatchAsync(batch, WorkerFrameWritePriority.Event));
Assert.Equal(
oversizedFirst ? WorkerFrameProtocolErrorCode.MessageTooLarge : WorkerFrameProtocolErrorCode.InvalidEnvelope,
exception.ErrorCode);
await AssertBatchSurvivorsWrittenAsync(stream, options);
Assert.Equal(1, stream.FlushCount);
}
/// <summary>
/// The batch caller does not have to drain its own frames: when a concurrent single-frame caller
/// holds the write lock as the batch is queued, that caller's pass claims and writes the batch.
/// The batch call must still report the first rejection in batch order and return only after
/// its frames are on the wire — the case that relies on every claimed frame being terminal before
/// its drainer releases the lock (#177).
/// </summary>
/// <param name="oversizedFirst">Whether the oversized frame precedes the body-less one.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(true)]
[InlineData(false)]
public async Task WriteBatchAsync_DrainedByAnotherLockHolder_StillSurfacesFirstFailureInBatchOrder(bool oversizedFirst)
{
WorkerFrameProtocolOptions options = CreateBatchRejectionOptions();
using GatedWriteStream stream = new();
WorkerFrameWriter writer = new(stream, options);
// A control writer takes the lock and parks inside its stream write.
Task controlWrite = writer.WriteAsync(CreateGatewayHelloEnvelope(), WorkerFrameWritePriority.Control);
await AwaitWithTimeoutAsync(stream.FirstWriteStarted);
Task batchWrite = writer.WriteBatchAsync(
CreateBatchWithTwoRejections(oversizedFirst),
WorkerFrameWritePriority.Event);
await Task.Delay(50);
Assert.False(batchWrite.IsCompleted);
stream.ReleaseFirstWrite();
await AwaitWithTimeoutAsync(controlWrite);
WorkerFrameProtocolException exception = await Assert.ThrowsAsync<WorkerFrameProtocolException>(
async () => await AwaitWithTimeoutAsync(batchWrite));
Assert.Equal(
oversizedFirst ? WorkerFrameProtocolErrorCode.MessageTooLarge : WorkerFrameProtocolErrorCode.InvalidEnvelope,
exception.ErrorCode);
stream.Position = 0;
WorkerFrameReader reader = new(stream, options);
WorkerEnvelope hello = await reader.ReadAsync();
Assert.Equal(WorkerEnvelope.BodyOneofCase.GatewayHello, hello.BodyCase);
WorkerEnvelope first = await reader.ReadAsync();
WorkerEnvelope second = await reader.ReadAsync();
Assert.Equal(new ulong[] { 1, 2, 3 }, new[] { hello.Sequence, first.Sequence, second.Sequence });
Assert.Equal(11UL, first.WorkerEvent.Event.WorkerSequence);
Assert.Equal(12UL, second.WorkerEvent.Event.WorkerSequence);
Assert.Equal(stream.Length, stream.Position);
}
/// <summary>
/// A batch cancelled while waiting for the write lock is tombstoned whole: none of its frames
/// reach the wire and the sequence stays contiguous for the next writer.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WriteBatchAsync_CancelledWhileWaitingForLock_WritesNoneOfTheBatch()
{
WorkerFrameProtocolOptions options = CreateOptions();
using GatedWriteStream stream = new();
WorkerFrameWriter writer = new(stream, options);
Task firstWrite = writer.WriteAsync(CreateGatewayHelloEnvelope(), WorkerFrameWritePriority.Control);
await AwaitWithTimeoutAsync(stream.FirstWriteStarted);
using CancellationTokenSource cts = new();
Task cancelledBatch = writer.WriteBatchAsync(
new[] { CreateEventEnvelope(1), CreateEventEnvelope(2), CreateEventEnvelope(3) },
WorkerFrameWritePriority.Event,
cts.Token);
await Task.Delay(50);
cts.Cancel();
await Assert.ThrowsAnyAsync<OperationCanceledException>(async () => await cancelledBatch);
stream.ReleaseFirstWrite();
await AwaitWithTimeoutAsync(firstWrite);
await writer.WriteAsync(CreateShutdownAckEnvelope(), WorkerFrameWritePriority.Control);
stream.Position = 0;
WorkerFrameReader reader = new(stream, options);
WorkerEnvelope frame1 = await reader.ReadAsync();
WorkerEnvelope frame2 = await reader.ReadAsync();
Assert.Equal(WorkerEnvelope.BodyOneofCase.GatewayHello, frame1.BodyCase);
Assert.Equal(WorkerEnvelope.BodyOneofCase.WorkerShutdownAck, frame2.BodyCase);
Assert.Equal(new ulong[] { 1, 2 }, new[] { frame1.Sequence, frame2.Sequence });
Assert.Equal(stream.Length, stream.Position);
}
/// <summary>
/// A batch whose end-of-pass flush fails surfaces that stream failure — not success and not a
/// different frame's outcome — because no frame of an unflushed batch may count as delivered.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WriteBatchAsync_WhenFlushFails_SurfacesTheStreamFailure()
{
string marker = $"batch-flush-{Guid.NewGuid():N}";
WorkerFrameProtocolOptions options = CreateOptions();
using FlushFaultingGatedStream stream = new(marker);
WorkerFrameWriter writer = new(stream, options);
Task batchWrite = writer.WriteBatchAsync(
new[] { CreateEventEnvelope(1), CreateEventEnvelope(2), CreateEventEnvelope(3) },
WorkerFrameWritePriority.Event);
await AwaitWithTimeoutAsync(stream.FirstWriteStarted);
stream.ReleaseFirstWrite();
IOException exception = await Assert.ThrowsAsync<IOException>(
async () => await AwaitWithTimeoutAsync(batchWrite));
Assert.Equal(marker, exception.Message);
}
/// <summary> /// <summary>
/// Frame-writer lock-parking, closed. The class-boundary flush made a control frame's <em>delivery /// Frame-writer lock-parking, closed. The class-boundary flush made a control frame's <em>delivery
/// point</em> honest, but the caller that lost the write-lock race still could not observe it: it /// point</em> honest, but the caller that lost the write-lock race still could not observe it: it
@@ -1155,6 +1295,48 @@ public sealed class WorkerFrameProtocolTests
}; };
} }
private static WorkerFrameProtocolOptions CreateBatchRejectionOptions()
{
return new WorkerFrameProtocolOptions(
SessionId,
GatewayContractInfo.WorkerProtocolVersion,
Nonce,
maxMessageBytes: 512);
}
// Two acceptable events (worker sequences 11 and 12) around two per-frame rejections: one
// oversized frame (MessageTooLarge) and one body-less frame (InvalidEnvelope), in either order.
private static WorkerEnvelope[] CreateBatchWithTwoRejections(bool oversizedFirst)
{
WorkerEnvelope oversized = CreateEventEnvelope(99);
oversized.WorkerEvent.Event.RawStatus = new string('x', 2048);
WorkerEnvelope bodyless = new()
{
ProtocolVersion = GatewayContractInfo.WorkerProtocolVersion,
SessionId = SessionId,
};
return new[]
{
CreateEventEnvelope(11),
oversizedFirst ? oversized : bodyless,
CreateEventEnvelope(12),
oversizedFirst ? bodyless : oversized,
};
}
private static async Task AssertBatchSurvivorsWrittenAsync(Stream stream, WorkerFrameProtocolOptions options)
{
stream.Position = 0;
WorkerFrameReader reader = new(stream, options);
WorkerEnvelope first = await reader.ReadAsync();
WorkerEnvelope second = await reader.ReadAsync();
Assert.Equal(11UL, first.WorkerEvent.Event.WorkerSequence);
Assert.Equal(12UL, second.WorkerEvent.Event.WorkerSequence);
Assert.Equal(new ulong[] { 1, 2 }, new[] { first.Sequence, second.Sequence });
Assert.Equal(stream.Length, stream.Position);
}
// net48 has no Task.WaitAsync(TimeSpan); fail the test rather than hang if the writer misbehaves. // net48 has no Task.WaitAsync(TimeSpan); fail the test rather than hang if the writer misbehaves.
private static async Task AwaitWithTimeoutAsync(Task task) private static async Task AwaitWithTimeoutAsync(Task task)
{ {
@@ -0,0 +1,344 @@
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Reflection;
using System.Text;
using System.Xml;
using ZB.MOM.WW.MxGateway.Worker.MxAccess;
namespace ZB.MOM.WW.MxGateway.Worker.Tests.MxAccess;
/// <summary>
/// Differential tests for <see cref="WnWrapAlarmConsumer.ParseSnapshotXml(string, out int)"/>:
/// the streaming parser that replaced the per-poll <see cref="XmlDocument"/> (#177) must
/// produce exactly what the DOM-based parser produced — same records, same field text, same
/// raw <c>ALARM</c> count, and an exception of the same type for a payload the DOM rejected.
/// <see cref="LegacyParse"/> is a verbatim copy of the replaced implementation and is the
/// oracle; it must not be "tidied" to match the production code, or the comparison proves
/// nothing.
/// </summary>
public sealed class WnWrapAlarmConsumerXmlParityTests
{
private const string Guid1 = "BCC4705395424D65BDAABCDEA6A32A73";
private const string Guid2 = "0123456789ABCDEF0123456789ABCDEF";
/// <summary>Gets the payload corpus, each case named so a divergence points at its shape.</summary>
public static IEnumerable<object[]> Payloads()
{
yield return Case("captured-single", Alarm(Guid1, "<ALARM_COMMENT>Test alarm #1</ALARM_COMMENT>"));
yield return Case("two-records", Alarm(Guid1) + Alarm(Guid2, "<STATE>ACK_RTN</STATE>"));
yield return Case("duplicate-guid-last-wins", Alarm(Guid1, "<VALUE>a</VALUE>") + Alarm(Guid1, "<VALUE>b</VALUE>"));
yield return Case("bad-guid-counted", Alarm("not-a-guid") + Alarm(Guid2));
yield return Case("empty-alarm-element", "<ALARM/>" + Alarm(Guid1));
yield return Case("empty-alarm-pair", "<ALARM></ALARM>");
yield return Case("crlf-in-comment", Alarm(Guid1, "<ALARM_COMMENT>line1\r\nline2\rline3\nline4</ALARM_COMMENT>"));
yield return Case("crlf-char-refs", Alarm(Guid1, "<ALARM_COMMENT>a&#13;&#10;b</ALARM_COMMENT>"));
yield return Case("leading-trailing-spaces", Alarm(Guid1, "<TAGNAME> Tank.Level </TAGNAME>"));
yield return Case("whitespace-only-field", Alarm(Guid1, "<ALARM_COMMENT> </ALARM_COMMENT>"));
yield return Case("whitespace-only-preserved", Alarm(Guid1, "<ALARM_COMMENT xml:space=\"preserve\"> </ALARM_COMMENT>"));
yield return Case("indented-pretty-print", "\r\n <ALARM>\r\n <GUID>" + Guid1 + "</GUID>\r\n <VALUE>1</VALUE>\r\n </ALARM>\r\n");
yield return Case("cdata", Alarm(Guid1, "<ALARM_COMMENT><![CDATA[<raw> & stuff]]></ALARM_COMMENT>"));
yield return Case("cdata-whitespace", Alarm(Guid1, "<ALARM_COMMENT><![CDATA[ ]]></ALARM_COMMENT>"));
yield return Case("mixed-text-cdata", Alarm(Guid1, "<ALARM_COMMENT>a<![CDATA[b]]>c</ALARM_COMMENT>"));
yield return Case("entities", Alarm(Guid1, "<ALARM_COMMENT>&lt;&gt;&amp;&quot;&apos;&#x41;&#66;</ALARM_COMMENT>"));
yield return Case("control-char-ref", Alarm(Guid1, "<ALARM_COMMENT>a&#x1;b</ALARM_COMMENT>"));
yield return Case("nested-element-in-field", Alarm(Guid1, "<ALARM_COMMENT>a<b>c<d>e</d></b> f</ALARM_COMMENT>"));
yield return Case("nested-with-whitespace", Alarm(Guid1, "<ALARM_COMMENT> <b>c</b> </ALARM_COMMENT>"));
yield return Case("comment-and-pi-in-field", Alarm(Guid1, "<ALARM_COMMENT>a<!-- x -->b<?pi y?>c</ALARM_COMMENT>"));
yield return Case("comments-between-fields", "<ALARM><!-- c --><GUID>" + Guid1 + "</GUID>text<?pi?><VALUE>1</VALUE></ALARM>");
yield return Case("duplicate-field-first-wins", Alarm(Guid1, "<VALUE>first</VALUE><VALUE>second</VALUE>"));
yield return Case("empty-first-duplicate", Alarm(Guid1, "<VALUE/><VALUE>second</VALUE>"));
yield return Case("wrong-case-field", Alarm(Guid1, "<value>lower</value>"));
yield return Case("unknown-field", Alarm(Guid1, "<EXTRA>x<VALUE>inner</VALUE></EXTRA>"));
yield return Case("field-with-attributes", Alarm(Guid1, "<VALUE unit=\"m\">5</VALUE>"));
yield return Case("default-ns-field", Alarm(Guid1, "<VALUE xmlns=\"urn:x\">ns</VALUE>"));
yield return Case("prefixed-field", Alarm(Guid1, "<p:VALUE xmlns:p=\"urn:x\">ns</p:VALUE>"));
yield return Case("prefixed-alarm", "<p:ALARM xmlns:p=\"urn:x\"><GUID>" + Guid1 + "</GUID></p:ALARM>");
yield return Case("default-ns-alarm", "<ALARM xmlns=\"urn:x\"><GUID>" + Guid1 + "</GUID></ALARM>");
yield return Case("alarm-nested-deeper", "<GROUPED>" + Alarm(Guid1) + "</GROUPED>" + Alarm(Guid2));
yield return Case("alarm-inside-alarm", "<ALARM><GUID>" + Guid1 + "</GUID>" + Alarm(Guid2) + "</ALARM>");
yield return Case("all-ack-fields",
Alarm(Guid1,
"<ACK_COMMENT>ok</ACK_COMMENT><ACK_OPERATOR_NAME>bob</ACK_OPERATOR_NAME>" +
"<ACK_DOMAIN_NAME>CORP</ACK_DOMAIN_NAME><ACK_OPERATOR_NODE>HMI1</ACK_OPERATOR_NODE>" +
"<OPERATOR_NODE>n</OPERATOR_NODE><OPERATOR_NAME>o</OPERATOR_NAME>"));
yield return Case("non-numeric-priority", Alarm(Guid1, "<PRIORITY>high</PRIORITY><GMTOFFSET>x</GMTOFFSET>"));
yield return Case("unicode", Alarm(Guid1, "<ALARM_COMMENT>Tänk ☃ 温度</ALARM_COMMENT>"));
yield return Raw("wrong-root", "<?xml version=\"1.0\"?><OTHER>" + Alarm(Guid1) + "</OTHER>");
yield return Raw("namespaced-root", "<ALARM_RECORDS xmlns=\"urn:x\">" + Alarm(Guid1) + "</ALARM_RECORDS>");
yield return Raw("no-declaration", "<ALARM_RECORDS>" + Alarm(Guid1) + "</ALARM_RECORDS>");
yield return Raw("utf16-declaration", "<?xml version=\"1.0\" encoding=\"UTF-16\"?><ALARM_RECORDS>" + Alarm(Guid1) + "</ALARM_RECORDS>");
yield return Raw("leading-whitespace-and-trailing-comment", " \r\n<ALARM_RECORDS>" + Alarm(Guid1) + "</ALARM_RECORDS><!-- end -->\r\n");
yield return Raw("internal-dtd-entity",
"<?xml version=\"1.0\"?><!DOCTYPE ALARM_RECORDS [<!ENTITY who \"Operator 7\">]>" +
"<ALARM_RECORDS>" + Alarm(Guid1, "<ALARM_COMMENT>by &who;!</ALARM_COMMENT>") + "</ALARM_RECORDS>");
yield return Raw("malformed-unclosed", "<ALARM_RECORDS>" + Alarm(Guid1));
yield return Raw("malformed-tail-after-records", "<ALARM_RECORDS>" + Alarm(Guid1) + "</ALARM_RECORDS><junk>");
yield return Raw("malformed-mismatched-tag", "<ALARM_RECORDS><ALARM><GUID>" + Guid1 + "</VALUE></ALARM></ALARM_RECORDS>");
yield return Raw("malformed-bad-entity", "<ALARM_RECORDS>" + Alarm(Guid1, "<VALUE>&nope;</VALUE>") + "</ALARM_RECORDS>");
yield return Raw("malformed-not-xml", "this is not xml");
yield return Raw("raw-control-char", "<ALARM_RECORDS>" + Alarm(Guid1, "<VALUE>a\u0001b</VALUE>") + "</ALARM_RECORDS>");
yield return Raw("large-capped-fetch", "<ALARM_RECORDS>" + ManyAlarms(1024) + "</ALARM_RECORDS>");
}
/// <summary>
/// Verifies the streaming parser and the replaced DOM parser agree on every corpus payload:
/// the same exception type when the DOM threw, otherwise the same raw count and records.
/// </summary>
/// <param name="name">Case name, for the test report.</param>
/// <param name="xml">Payload under test.</param>
[Theory]
[MemberData(nameof(Payloads))]
public void ParseSnapshotXml_MatchesReplacedXmlDocumentParser(string name, string xml)
{
Exception? legacyException = null;
Dictionary<Guid, MxAlarmSnapshotRecord>? legacy = null;
int legacyCount = 0;
try
{
legacy = LegacyParse(xml, out legacyCount);
}
catch (Exception exception)
{
legacyException = exception;
}
if (legacyException is not null)
{
Exception actual = Assert.ThrowsAny<Exception>(() => WnWrapAlarmConsumer.ParseSnapshotXml(xml, out _));
Assert.True(
legacyException.GetType() == actual.GetType(),
$"{name}: legacy threw {legacyException.GetType().Name}, streaming threw {actual.GetType().Name} ({actual.Message})");
return;
}
Dictionary<Guid, MxAlarmSnapshotRecord> streamed = WnWrapAlarmConsumer.ParseSnapshotXml(xml, out int streamedCount);
Assert.Equal(legacyCount, streamedCount);
Assert.Equal(Describe(legacy!), Describe(streamed));
}
/// <summary>
/// Guards the corpus itself: a differential test whose corpus never exercises a path proves
/// nothing about it, so pin that the oracle really parses records, really rejects the
/// malformed payloads, and really sees the CRLF and DTD text the streaming reader must keep.
/// </summary>
[Fact]
public void Corpus_ExercisesRecordsRejectionsAndTextEdgeCases()
{
Dictionary<string, string> corpus = Payloads().ToDictionary(row => (string)row[0], row => (string)row[1]);
Assert.Equal(2, LegacyParse(corpus["two-records"], out _).Count);
Assert.Equal(1024, LegacyParse(corpus["large-capped-fetch"], out int largeCount).Count);
Assert.Equal(1024, largeCount);
Assert.Empty(LegacyParse(corpus["wrong-root"], out _));
Assert.Throws<XmlException>(() => LegacyParse(corpus["malformed-tail-after-records"], out _));
Assert.Throws<XmlException>(() => LegacyParse(corpus["malformed-not-xml"], out _));
Guid guid1 = ParseGuid(Guid1);
Assert.Equal("by Operator 7!", LegacyParse(corpus["internal-dtd-entity"], out _)[guid1].AlarmComment);
Assert.Equal("ace f", LegacyParse(corpus["nested-element-in-field"], out _)[guid1].AlarmComment);
Assert.Equal(string.Empty, LegacyParse(corpus["whitespace-only-field"], out _)[guid1].AlarmComment);
Assert.Equal(" ", LegacyParse(corpus["whitespace-only-preserved"], out _)[guid1].AlarmComment);
}
private static object[] Case(string name, string alarms)
{
return Raw(name, "<?xml version=\"1.0\"?><ALARM_RECORDS COUNT=\"1\">" + alarms + "</ALARM_RECORDS>");
}
private static object[] Raw(string name, string xml)
{
return new object[] { name, xml };
}
private static string Alarm(string guid, string extraFields = "")
{
return "<ALARM><GUID>" + guid + "</GUID>" +
"<DATE>2026/5/1</DATE><TIME>13:26:14.709</TIME>" +
"<GMTOFFSET>240</GMTOFFSET><DSTADJUST>0</DSTADJUST>" +
"<PROVIDER_NODE>NODE1</PROVIDER_NODE><PROVIDER_NAME>Galaxy</PROVIDER_NAME>" +
"<GROUP>Area</GROUP><TAGNAME>Machine.Alarm</TAGNAME>" +
"<TYPE>DSC</TYPE><VALUE>true</VALUE><LIMIT>true</LIMIT>" +
"<PRIORITY>500</PRIORITY><STATE>UNACK_ALM</STATE>" +
extraFields +
"</ALARM>";
}
private static string ManyAlarms(int count)
{
StringBuilder builder = new();
for (int index = 0; index < count; index++)
{
builder.Append(Alarm(index.ToString("X32", CultureInfo.InvariantCulture), "<ALARM_COMMENT>c" + index + "</ALARM_COMMENT>"));
}
return builder.ToString();
}
private static Guid ParseGuid(string hex)
{
Assert.True(WnWrapAlarmConsumer.TryParseHexGuid(hex, out Guid guid));
return guid;
}
private static string Describe(Dictionary<Guid, MxAlarmSnapshotRecord> records)
{
PropertyInfo[] properties = typeof(MxAlarmSnapshotRecord)
.GetProperties(BindingFlags.Public | BindingFlags.Instance)
.OrderBy(property => property.Name, StringComparer.Ordinal)
.ToArray();
// Dictionary enumeration order is insertion order here, and both parsers insert in document
// order, so the order is part of what is compared.
StringBuilder builder = new();
foreach (KeyValuePair<Guid, MxAlarmSnapshotRecord> entry in records)
{
builder.Append(entry.Key.ToString("N")).Append(" {");
foreach (PropertyInfo property in properties)
{
object? value = property.GetValue(entry.Value);
string text = value is DateTime dateTime
? dateTime.ToString("O", CultureInfo.InvariantCulture) + "/" + dateTime.Kind
: Convert.ToString(value, CultureInfo.InvariantCulture) ?? "<null>";
builder.Append(' ').Append(property.Name).Append("=[").Append(Escape(text)).Append(']');
}
builder.Append(" }\n");
}
return builder.ToString();
}
private static string Escape(string text)
{
StringBuilder builder = new();
foreach (char character in text)
{
if (character < ' ' || character > '~')
{
builder.Append("\\u").Append(((int)character).ToString("X4", CultureInfo.InvariantCulture));
}
else
{
builder.Append(character);
}
}
return builder.ToString();
}
// Code-identical copy (comments dropped) of WnWrapAlarmConsumer.ParseSnapshotXml(string, out int) as of 0c0c7b86, before
// the streaming rewrite. The oracle for the differential test above; do not modify.
private static Dictionary<Guid, MxAlarmSnapshotRecord> LegacyParse(
string xml,
out int alarmRecordCount)
{
Dictionary<Guid, MxAlarmSnapshotRecord> records =
new Dictionary<Guid, MxAlarmSnapshotRecord>();
alarmRecordCount = 0;
if (string.IsNullOrWhiteSpace(xml)) return records;
XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);
XmlNodeList? alarmNodes = doc.SelectNodes("/ALARM_RECORDS/ALARM");
if (alarmNodes is null) return records;
alarmRecordCount = alarmNodes.Count;
foreach (XmlNode alarmNode in alarmNodes)
{
string? guidHex = null;
string? xmlDate = null;
string? xmlTime = null;
string? gmtOffset = null;
string? dstAdjust = null;
string? providerNode = null;
string? providerName = null;
string? group = null;
string? tagName = null;
string? type = null;
string? value = null;
string? limit = null;
string? priority = null;
string? state = null;
string? operatorNode = null;
string? operatorName = null;
string? alarmComment = null;
string? ackComment = null;
string? ackOperatorName = null;
string? ackOperatorDomain = null;
string? ackOperatorNode = null;
foreach (XmlNode child in alarmNode.ChildNodes)
{
if (child.NodeType != XmlNodeType.Element) continue;
switch (child.Name)
{
case "GUID": guidHex ??= child.InnerText; break;
case "DATE": xmlDate ??= child.InnerText; break;
case "TIME": xmlTime ??= child.InnerText; break;
case "GMTOFFSET": gmtOffset ??= child.InnerText; break;
case "DSTADJUST": dstAdjust ??= child.InnerText; break;
case "PROVIDER_NODE": providerNode ??= child.InnerText; break;
case "PROVIDER_NAME": providerName ??= child.InnerText; break;
case "GROUP": group ??= child.InnerText; break;
case "TAGNAME": tagName ??= child.InnerText; break;
case "TYPE": type ??= child.InnerText; break;
case "VALUE": value ??= child.InnerText; break;
case "LIMIT": limit ??= child.InnerText; break;
case "PRIORITY": priority ??= child.InnerText; break;
case "STATE": state ??= child.InnerText; break;
case "OPERATOR_NODE": operatorNode ??= child.InnerText; break;
case "OPERATOR_NAME": operatorName ??= child.InnerText; break;
case "ALARM_COMMENT": alarmComment ??= child.InnerText; break;
case "ACK_COMMENT": ackComment ??= child.InnerText; break;
case "ACK_OPERATOR_NAME": ackOperatorName ??= child.InnerText; break;
case "ACK_DOMAIN_NAME": ackOperatorDomain ??= child.InnerText; break;
case "ACK_OPERATOR_NODE": ackOperatorNode ??= child.InnerText; break;
}
}
if (!WnWrapAlarmConsumer.TryParseHexGuid(guidHex, out Guid guid)) continue;
DateTime tsUtc = AlarmRecordTransitionMapper.ParseTransitionTimestampUtc(
xmlDate ?? string.Empty,
xmlTime ?? string.Empty,
LegacyParseInt(gmtOffset ?? string.Empty),
LegacyParseInt(dstAdjust ?? string.Empty));
records[guid] = new MxAlarmSnapshotRecord
{
AlarmGuid = guid,
TransitionTimestampUtc = tsUtc,
ProviderNode = providerNode ?? string.Empty,
ProviderName = providerName ?? string.Empty,
Group = group ?? string.Empty,
TagName = tagName ?? string.Empty,
Type = type ?? string.Empty,
Value = value ?? string.Empty,
Limit = limit ?? string.Empty,
Priority = LegacyParseInt(priority ?? string.Empty),
State = AlarmRecordTransitionMapper.ParseStateKind(state ?? string.Empty),
OperatorNode = operatorNode ?? string.Empty,
OperatorName = operatorName ?? string.Empty,
AlarmComment = alarmComment ?? string.Empty,
AckComment = ackComment ?? string.Empty,
AckOperatorName = ackOperatorName ?? string.Empty,
AckOperatorDomain = ackOperatorDomain ?? string.Empty,
AckOperatorNode = ackOperatorNode ?? string.Empty,
};
}
return records;
}
private static int LegacyParseInt(string text)
{
return int.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out int n)
? n : 0;
}
}
@@ -27,14 +27,37 @@ public sealed class WorkerFrameWriter
{ {
private sealed class PendingFrame private sealed class PendingFrame
{ {
private const int StatePending = 0;
private const int StateSucceeded = 1;
private const int StateFaulted = 2;
private const int StateCanceled = 3;
// A single-frame caller awaits its frame — racing that completion against the write lock —
// so it needs a Task and gets a TaskCompletionSource. A WriteBatchAsync frame never does: the
// batch caller holds the write lock for its own drain pass, and every frame a pass claims
// reaches a terminal state before that pass releases the lock, so once the caller's drain
// returns it only has to read each frame's outcome. Skipping the per-frame TCS (plus its
// Task) on the event drain loop's hot path is the batch allocation saving (#177). The
// terminal state lives in _state either way, so both kinds share one claim/tombstone/
// complete protocol and DequeueNext, FailAllQueued, and the drain pass treat them alike.
private readonly TaskCompletionSource<bool>? _completion;
private int _state;
private Exception? _fault;
/// <summary>Initializes a new instance of the PendingFrame class.</summary> /// <summary>Initializes a new instance of the PendingFrame class.</summary>
/// <param name="envelope">Worker envelope awaiting write.</param> /// <param name="envelope">Worker envelope awaiting write.</param>
/// <param name="priority">Priority class the frame was queued at.</param> /// <param name="priority">Priority class the frame was queued at.</param>
public PendingFrame(WorkerEnvelope envelope, WorkerFrameWritePriority priority) /// <param name="awaitable">
/// <see langword="true"/> for a frame whose caller awaits <see cref="Completion"/>;
/// <see langword="false"/> for a batch frame whose caller reads <see cref="TryGetFault"/>.
/// </param>
public PendingFrame(WorkerEnvelope envelope, WorkerFrameWritePriority priority, bool awaitable)
{ {
Envelope = envelope; Envelope = envelope;
IsControl = priority != WorkerFrameWritePriority.Event; IsControl = priority != WorkerFrameWritePriority.Event;
Completion = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously); _completion = awaitable
? new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously)
: null;
} }
/// <summary>Gets the worker envelope awaiting write.</summary> /// <summary>Gets the worker envelope awaiting write.</summary>
@@ -48,8 +71,21 @@ public sealed class WorkerFrameWriter
/// </summary> /// </summary>
public bool IsControl { get; } public bool IsControl { get; }
/// <summary>Gets the completion source signaled once the frame has been written or has failed.</summary> /// <summary>
public TaskCompletionSource<bool> Completion { get; } /// Gets the task signaled once the frame has been written or has failed. Only an awaitable
/// (single-frame) frame has one; reading it on a batch frame is a programming error.
/// </summary>
public Task Completion => _completion?.Task
?? throw new InvalidOperationException("A batch frame has no awaitable completion.");
/// <summary>Gets a value indicating whether the frame has an awaitable <see cref="Completion"/>.</summary>
public bool HasCompletion => _completion is not null;
/// <summary>Gets a value indicating whether a cancelled caller tombstoned this frame.</summary>
public bool IsCanceled => Volatile.Read(ref _state) == StateCanceled;
/// <summary>Gets a value indicating whether the frame has reached a terminal state.</summary>
public bool IsCompleted => Volatile.Read(ref _state) != StatePending;
/// <summary> /// <summary>
/// Set to <c>true</c> by <see cref="DequeueNext"/> — under <c>_gate</c> — at the instant the /// Set to <c>true</c> by <see cref="DequeueNext"/> — under <c>_gate</c> — at the instant the
@@ -60,6 +96,63 @@ public sealed class WorkerFrameWriter
/// Mutated only under <c>_gate</c>. /// Mutated only under <c>_gate</c>.
/// </summary> /// </summary>
public bool Claimed; public bool Claimed;
/// <summary>Marks the frame written and flushed; a no-op once terminal.</summary>
public void TrySetResult()
{
if (TryTransition(StateSucceeded))
{
_completion?.TrySetResult(true);
}
}
/// <summary>Marks the frame failed; a no-op once terminal.</summary>
/// <param name="exception">Failure to surface to the frame's caller.</param>
public void TrySetException(Exception exception)
{
// _fault is published before the state flips, so a reader that observes StateFaulted
// (through the Interlocked fence) also observes the exception.
if (Volatile.Read(ref _state) != StatePending)
{
return;
}
Exception? previous = Interlocked.CompareExchange(ref _fault, exception, null);
if (previous is not null)
{
return;
}
if (TryTransition(StateFaulted))
{
_completion?.TrySetException(exception);
}
}
/// <summary>Tombstones the frame; a no-op once terminal.</summary>
/// <param name="cancellationToken">Token whose cancellation tombstoned the frame.</param>
public void TrySetCanceled(CancellationToken cancellationToken)
{
if (TryTransition(StateCanceled))
{
_completion?.TrySetCanceled(cancellationToken);
}
}
/// <summary>
/// Returns the failure a terminal batch frame ended with, or <see langword="null"/> when it
/// succeeded or was tombstoned.
/// </summary>
/// <returns>The frame's failure, or <see langword="null"/>.</returns>
public Exception? TryGetFault()
{
return Volatile.Read(ref _state) == StateFaulted ? Volatile.Read(ref _fault) : null;
}
private bool TryTransition(int terminalState)
{
return Interlocked.CompareExchange(ref _state, terminalState, StatePending) == StatePending;
}
} }
private readonly WorkerFrameProtocolOptions _options; private readonly WorkerFrameProtocolOptions _options;
@@ -132,7 +225,7 @@ public sealed class WorkerFrameWriter
throw new ArgumentNullException(nameof(envelope)); throw new ArgumentNullException(nameof(envelope));
} }
PendingFrame frame = new PendingFrame(envelope, priority); PendingFrame frame = new PendingFrame(envelope, priority, awaitable: true);
lock (_gate) lock (_gate)
{ {
if (priority == WorkerFrameWritePriority.Event) if (priority == WorkerFrameWritePriority.Event)
@@ -153,7 +246,7 @@ public sealed class WorkerFrameWriter
// the winner's release; the acquisition it then walks away from is detached, never dropped, so // the winner's release; the acquisition it then walks away from is detached, never dropped, so
// no drain responsibility leaves with it. // no drain responsibility leaves with it.
Task lockWait = _writeLock.WaitAsync(cancellationToken); Task lockWait = _writeLock.WaitAsync(cancellationToken);
Task completion = frame.Completion.Task; Task completion = frame.Completion;
await Task.WhenAny(completion, lockWait).ConfigureAwait(false); await Task.WhenAny(completion, lockWait).ConfigureAwait(false);
if (lockWait.Status != TaskStatus.RanToCompletion) if (lockWait.Status != TaskStatus.RanToCompletion)
@@ -253,7 +346,7 @@ public sealed class WorkerFrameWriter
{ {
WorkerEnvelope envelope = envelopes[index] WorkerEnvelope envelope = envelopes[index]
?? throw new ArgumentException("Batch envelopes must not contain null.", nameof(envelopes)); ?? throw new ArgumentException("Batch envelopes must not contain null.", nameof(envelopes));
frames[index] = new PendingFrame(envelope, priority); frames[index] = new PendingFrame(envelope, priority, awaitable: false);
} }
lock (_gate) lock (_gate)
@@ -284,19 +377,21 @@ public sealed class WorkerFrameWriter
_writeLock.Release(); _writeLock.Release();
} }
// Await every completion so no per-frame rejection faults unobserved, but surface the first // Surface the first failure (in batch order) to the caller — the drain loop maps it back to
// failure (in batch order) to the caller — the drain loop maps it back to the offending event. // the offending event. Every batch frame is terminal here without waiting: this caller's own
// pass drained whatever of the batch was still queued, and any frame an earlier lock-holder
// claimed was completed or failed inside that holder's pass, before it released the lock this
// caller then acquired. Batch frames carry no Task, so there is nothing left to observe.
Exception? firstFailure = null; Exception? firstFailure = null;
foreach (PendingFrame frame in frames) foreach (PendingFrame frame in frames)
{ {
try if (!frame.IsCompleted)
{ {
await frame.Completion.Task.ConfigureAwait(false); throw new InvalidOperationException(
} "A batch frame was still pending after its caller's drain pass released the write lock.");
catch (Exception exception)
{
firstFailure ??= exception;
} }
firstFailure ??= frame.TryGetFault();
} }
if (firstFailure is not null) if (firstFailure is not null)
@@ -311,7 +406,7 @@ public sealed class WorkerFrameWriter
{ {
if (!frame.Claimed) if (!frame.Claimed)
{ {
frame.Completion.TrySetCanceled(cancellationToken); frame.TrySetCanceled(cancellationToken);
} }
} }
@@ -326,7 +421,7 @@ public sealed class WorkerFrameWriter
{ {
if (!frame.Claimed) if (!frame.Claimed)
{ {
frame.Completion.TrySetCanceled(cancellationToken); frame.TrySetCanceled(cancellationToken);
} }
} }
} }
@@ -349,7 +444,11 @@ public sealed class WorkerFrameWriter
/// <param name="frame">Frame whose completion may fault without an awaiter.</param> /// <param name="frame">Frame whose completion may fault without an awaiter.</param>
private static void ObserveAbandonedFault(PendingFrame frame) private static void ObserveAbandonedFault(PendingFrame frame)
{ {
ObserveFault(frame.Completion.Task); // A batch frame has no Task, so a later failure has nothing to go unobserved on.
if (frame.HasCompletion)
{
ObserveFault(frame.Completion);
}
} }
/// <summary> /// <summary>
@@ -497,7 +596,7 @@ public sealed class WorkerFrameWriter
// flush that guarantees delivery failed, so the pipe is broken. Fail the frame just // flush that guarantees delivery failed, so the pipe is broken. Fail the frame just
// claimed (it is out of its queue and nothing else will ever complete it), every // claimed (it is out of its queue and nothing else will ever complete it), every
// written-but-unflushed frame, and everything still queued, then stop draining. // written-but-unflushed frame, and everything still queued, then stop draining.
frame.Completion.TrySetException(exception); frame.TrySetException(exception);
FailFrames(written, exception); FailFrames(written, exception);
FailAllQueued(exception); FailAllQueued(exception);
return; return;
@@ -520,14 +619,14 @@ public sealed class WorkerFrameWriter
// Validation, empty-payload, and oversized-frame errors are specific to this frame and // Validation, empty-payload, and oversized-frame errors are specific to this frame and
// do not damage the stream; fail only this frame and keep draining the rest. Nothing was // do not damage the stream; fail only this frame and keep draining the rest. Nothing was
// written for it, so it needs no flush. // written for it, so it needs no flush.
frame.Completion.TrySetException(exception); frame.TrySetException(exception);
} }
catch (Exception exception) catch (Exception exception)
{ {
// A stream write failure means the pipe is broken; fail this frame, every frame already // A stream write failure means the pipe is broken; fail this frame, every frame already
// written this batch but not yet flushed, and every frame still queued so no caller // written this batch but not yet flushed, and every frame still queued so no caller
// awaits forever, then stop draining. // awaits forever, then stop draining.
frame.Completion.TrySetException(exception); frame.TrySetException(exception);
FailFrames(written, exception); FailFrames(written, exception);
FailAllQueued(exception); FailAllQueued(exception);
return; return;
@@ -560,7 +659,7 @@ public sealed class WorkerFrameWriter
{ {
foreach (PendingFrame frame in frames) foreach (PendingFrame frame in frames)
{ {
frame.Completion.TrySetResult(true); frame.TrySetResult();
} }
} }
@@ -568,7 +667,7 @@ public sealed class WorkerFrameWriter
{ {
foreach (PendingFrame frame in frames) foreach (PendingFrame frame in frames)
{ {
frame.Completion.TrySetException(exception); frame.TrySetException(exception);
} }
} }
@@ -591,7 +690,7 @@ public sealed class WorkerFrameWriter
while (_controlFrames.Count > 0) while (_controlFrames.Count > 0)
{ {
PendingFrame frame = _controlFrames.Dequeue(); PendingFrame frame = _controlFrames.Dequeue();
if (frame.Completion.Task.IsCanceled) if (frame.IsCanceled)
{ {
continue; continue;
} }
@@ -603,7 +702,7 @@ public sealed class WorkerFrameWriter
while (_eventFrames.Count > 0) while (_eventFrames.Count > 0)
{ {
PendingFrame frame = _eventFrames.Dequeue(); PendingFrame frame = _eventFrames.Dequeue();
if (frame.Completion.Task.IsCanceled) if (frame.IsCanceled)
{ {
continue; continue;
} }
@@ -622,12 +721,12 @@ public sealed class WorkerFrameWriter
{ {
while (_controlFrames.Count > 0) while (_controlFrames.Count > 0)
{ {
_controlFrames.Dequeue().Completion.TrySetException(exception); _controlFrames.Dequeue().TrySetException(exception);
} }
while (_eventFrames.Count > 0) while (_eventFrames.Count > 0)
{ {
_eventFrames.Dequeue().Completion.TrySetException(exception); _eventFrames.Dequeue().TrySetException(exception);
} }
} }
} }
@@ -2,7 +2,9 @@ using System;
using System.Collections.Generic; using System.Collections.Generic;
using System.Diagnostics; using System.Diagnostics;
using System.Globalization; using System.Globalization;
using System.IO;
using System.Runtime.InteropServices; using System.Runtime.InteropServices;
using System.Text;
using System.Xml; using System.Xml;
using WNWRAPCONSUMERLib; using WNWRAPCONSUMERLib;
using ZB.MOM.WW.MxGateway.Contracts; using ZB.MOM.WW.MxGateway.Contracts;
@@ -73,7 +75,7 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
/// Ceiling on the resolved per-fetch cap. Mirrors the gateway-side /// Ceiling on the resolved per-fetch cap. Mirrors the gateway-side
/// <c>MxGateway:Alarms:MaxAlarmsPerFetch</c> maximum. The worker is a /// <c>MxGateway:Alarms:MaxAlarmsPerFetch</c> maximum. The worker is a
/// 32-bit process: every poll materializes the whole reply as one BSTR /// 32-bit process: every poll materializes the whole reply as one BSTR
/// and then a full <see cref="XmlDocument"/> over it, so an unbounded /// and then streams it into one record per alarm, so an unbounded
/// cap (<see cref="int.MaxValue"/> passed startup validation before /// cap (<see cref="int.MaxValue"/> passed startup validation before
/// this existed) is an out-of-memory fault on the STA, not a slow poll. /// this existed) is an out-of-memory fault on the STA, not a slow poll.
/// </summary> /// </summary>
@@ -685,22 +687,58 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
if (string.IsNullOrWhiteSpace(xml)) return records; if (string.IsNullOrWhiteSpace(xml)) return records;
XmlDocument doc = new XmlDocument(); // Streamed with a forward-only XmlTextReader instead of materializing a
doc.LoadXml(xml); // full XmlDocument: the poll runs every 500 ms on the STA and at the
XmlNodeList? alarmNodes = doc.SelectNodes("/ALARM_RECORDS/ALARM"); // per-fetch cap the DOM was the dominant steady allocation (#177).
if (alarmNodes is null) return records; //
// Parity with the XmlDocument + XPath reading this replaces, which the
alarmRecordCount = alarmNodes.Count; // differential tests in WnWrapAlarmConsumerXmlTests pin against a copy
// of the old code:
foreach (XmlNode alarmNode in alarmNodes) // * XmlDocument.LoadXml reads through an XmlTextReader with its
// defaults (DTDs parsed, Normalization off — so CRLF inside a
// comment field survives — and no character checking); this reader
// keeps those defaults and only nulls the resolver, which
// XmlDocument also leaves unset. The whole document is read to its
// end, so a malformed payload still throws XmlException rather than
// returning the records before the fault.
// * "/ALARM_RECORDS/ALARM" is an unprefixed XPath name test: local
// name match in the empty namespace, document element then its
// direct children only.
// * XmlDocument (PreserveWhitespace off) drops insignificant
// whitespace nodes and keeps significant ones; WhitespaceHandling
// .Significant makes the reader do the same, so InnerText
// concatenation below sees the same text nodes the DOM held.
using StringReader textReader = new StringReader(xml);
using XmlTextReader reader = new XmlTextReader(textReader)
{ {
XmlResolver = null,
DtdProcessing = DtdProcessing.Parse,
EntityHandling = EntityHandling.ExpandEntities,
WhitespaceHandling = WhitespaceHandling.Significant,
};
bool rootIsAlarmRecords = false;
while (reader.Read())
{
if (reader.NodeType != XmlNodeType.Element) continue;
if (reader.Depth == 0)
{
rootIsAlarmRecords = IsUnqualified(reader, "ALARM_RECORDS");
continue;
}
if (!rootIsAlarmRecords || reader.Depth != 1 || !IsUnqualified(reader, "ALARM")) continue;
alarmRecordCount++;
// One pass over the child elements instead of 17 SelectSingleNode // One pass over the child elements instead of 17 SelectSingleNode
// XPath evaluations per record. At the 1024-record cap that is the // XPath evaluations per record. At the 1024-record cap that is the
// difference between ~17k XPath expression compilations plus child // difference between ~17k XPath expression compilations plus child
// walks and one walk per record, on the STA that also serves reads // walks and one walk per record, on the STA that also serves reads
// and writes. // and writes.
// //
// Parity with the XPath it replaces: SelectSingleNode(name) picks // Parity with the XPath this replaced: SelectSingleNode(name) picks
// the FIRST child ELEMENT of that name (ordinal, case-sensitive) // the FIRST child ELEMENT of that name (ordinal, case-sensitive)
// and yields its InnerText; an absent child yields string.Empty, // and yields its InnerText; an absent child yields string.Empty,
// and so does a present-but-empty one. Hence: element nodes only, // and so does a present-but-empty one. Hence: element nodes only,
@@ -708,12 +746,14 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
// coalesce to string.Empty at the end — which keeps the absent and // coalesce to string.Empty at the end — which keeps the absent and
// empty cases indistinguishable exactly as before. // empty cases indistinguishable exactly as before.
// //
// One theoretical divergence: XmlNode.Name is the QName, so a child // One theoretical divergence from that XPath, kept from the DOM
// carrying its own default-namespace declaration (<GUID xmlns="...">) // walk that preceded this reader: reader.Name is the QName, so a
// matches here where the unprefixed XPath name test would not. It is // child carrying its own default-namespace declaration
// theoretical — wnwrap emits no namespaces, and a namespaced ALARM // (<GUID xmlns="...">) matches here where the unprefixed XPath
// wrapper makes the outer SelectNodes return nothing either way — and // name test would not. It is theoretical — wnwrap emits no
// it errs permissive (field populated rather than silently dropped). // namespaces, and a namespaced ALARM wrapper is skipped either
// way — and it errs permissive (field populated rather than
// silently dropped).
string? guidHex = null; string? guidHex = null;
string? xmlDate = null; string? xmlDate = null;
string? xmlTime = null; string? xmlTime = null;
@@ -736,33 +776,40 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
string? ackOperatorDomain = null; string? ackOperatorDomain = null;
string? ackOperatorNode = null; string? ackOperatorNode = null;
foreach (XmlNode child in alarmNode.ChildNodes) if (!reader.IsEmptyElement)
{ {
if (child.NodeType != XmlNodeType.Element) continue; while (reader.Read() && !(reader.NodeType == XmlNodeType.EndElement && reader.Depth == 1))
{
if (reader.NodeType != XmlNodeType.Element || reader.Depth != 2) continue;
switch (child.Name) // Read the name before the text: reading the text moves the
// reader to the element's end tag.
string name = reader.Name;
string text = ReadElementInnerText(reader);
switch (name)
{ {
case "GUID": guidHex ??= child.InnerText; break; case "GUID": guidHex ??= text; break;
case "DATE": xmlDate ??= child.InnerText; break; case "DATE": xmlDate ??= text; break;
case "TIME": xmlTime ??= child.InnerText; break; case "TIME": xmlTime ??= text; break;
case "GMTOFFSET": gmtOffset ??= child.InnerText; break; case "GMTOFFSET": gmtOffset ??= text; break;
case "DSTADJUST": dstAdjust ??= child.InnerText; break; case "DSTADJUST": dstAdjust ??= text; break;
case "PROVIDER_NODE": providerNode ??= child.InnerText; break; case "PROVIDER_NODE": providerNode ??= text; break;
case "PROVIDER_NAME": providerName ??= child.InnerText; break; case "PROVIDER_NAME": providerName ??= text; break;
case "GROUP": group ??= child.InnerText; break; case "GROUP": group ??= text; break;
case "TAGNAME": tagName ??= child.InnerText; break; case "TAGNAME": tagName ??= text; break;
case "TYPE": type ??= child.InnerText; break; case "TYPE": type ??= text; break;
case "VALUE": value ??= child.InnerText; break; case "VALUE": value ??= text; break;
case "LIMIT": limit ??= child.InnerText; break; case "LIMIT": limit ??= text; break;
case "PRIORITY": priority ??= child.InnerText; break; case "PRIORITY": priority ??= text; break;
case "STATE": state ??= child.InnerText; break; case "STATE": state ??= text; break;
case "OPERATOR_NODE": operatorNode ??= child.InnerText; break; case "OPERATOR_NODE": operatorNode ??= text; break;
case "OPERATOR_NAME": operatorName ??= child.InnerText; break; case "OPERATOR_NAME": operatorName ??= text; break;
case "ALARM_COMMENT": alarmComment ??= child.InnerText; break; case "ALARM_COMMENT": alarmComment ??= text; break;
case "ACK_COMMENT": ackComment ??= child.InnerText; break; case "ACK_COMMENT": ackComment ??= text; break;
case "ACK_OPERATOR_NAME": ackOperatorName ??= child.InnerText; break; case "ACK_OPERATOR_NAME": ackOperatorName ??= text; break;
case "ACK_DOMAIN_NAME": ackOperatorDomain ??= child.InnerText; break; case "ACK_DOMAIN_NAME": ackOperatorDomain ??= text; break;
case "ACK_OPERATOR_NODE": ackOperatorNode ??= child.InnerText; break; case "ACK_OPERATOR_NODE": ackOperatorNode ??= text; break;
}
} }
} }
@@ -799,6 +846,55 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
return records; return records;
} }
private static bool IsUnqualified(XmlReader reader, string localName)
{
return reader.NamespaceURI.Length == 0
&& string.Equals(reader.LocalName, localName, StringComparison.Ordinal);
}
/// <summary>
/// Returns what <see cref="XmlNode.InnerText"/> returned for the
/// element the reader is on — every text, CDATA and significant
/// whitespace node in its subtree, concatenated in document order,
/// comments and processing instructions excluded — and leaves the
/// reader on the element's end tag (or on the element itself when it
/// is empty). The single-text-node case, which is every wnwrap field,
/// returns the reader's string without a builder.
/// </summary>
/// <param name="reader">Reader positioned on an element start tag.</param>
/// <returns>The concatenated inner text, or <see cref="string.Empty"/>.</returns>
private static string ReadElementInnerText(XmlReader reader)
{
if (reader.IsEmptyElement) return string.Empty;
int depth = reader.Depth;
string? first = null;
StringBuilder? builder = null;
while (reader.Read())
{
XmlNodeType nodeType = reader.NodeType;
if (nodeType == XmlNodeType.EndElement && reader.Depth == depth) break;
if (nodeType is XmlNodeType.Text
or XmlNodeType.CDATA
or XmlNodeType.Whitespace
or XmlNodeType.SignificantWhitespace)
{
if (first is null)
{
first = reader.Value;
}
else
{
builder ??= new StringBuilder(first);
builder.Append(reader.Value);
}
}
}
return builder?.ToString() ?? first ?? string.Empty;
}
private static int ParseInt(string text) private static int ParseInt(string text)
{ {
return int.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out int n) return int.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out int n)