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
@@ -912,6 +912,146 @@ public sealed class WorkerFrameProtocolTests
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>
/// 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
@@ -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.
private static async Task AwaitWithTimeoutAsync(Task task)
{