feat(events): opt-in stream-attached acknowledgement on StreamEvents (#227)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m28s
ci / java (push) Failing after 2m21s
ci / portable (push) Failing after 3m33s

A fresh StreamEvents is never replayed, so an initial value published before
the gateway registers the stream's subscriber is lost (lmxopcua#865 —
slow-changing ScanState). Clients had nothing deterministic to wait on.

Contract (additive, proto3):
- StreamEventsRequest.emit_stream_attached = 3 (bool, default false)
- MxEvent.stream_attached = 15 (optional StreamAttached)
- message StreamAttached { uint64 live_after_sequence = 1; }
- OpenSessionReply capability "stream-events-attached-ack"
  (GatewayCapabilities.StreamEventsAttachedAck)

When requested, EventStreamService yields the sentinel as the FIRST message,
after AttachEventSubscriber/AttachEventSubscriberWithReplay has returned, so
receipt implies registration; refused attaches never see it. It precedes the
ReplayGap sentinel and replay on a resume. Shape mirrors ReplayGap: family
UNSPECIFIED, no body, worker_sequence 0.

Opt-in rather than always-on: ScadaBridge's MxGateway adapter stores every
streamed event's worker_sequence as its resume cursor, so an unrequested
sentinel would reset it to 0. Default wire behaviour is unchanged.

.NET client: StreamEventsAsync/StreamEventItemsAsync(after, emitStreamAttached),
MxEventStreamItem.IsStreamAttached, MxGatewaySession.SupportsStreamAttachedAck,
and OpenEventStreamAsync -> MxGatewayEventStream (awaits the sentinel, with
attach timeout; refuses older gateways).

Regenerated Contracts/Generated, the client protoset, Go and Python bindings
(also picks up comment-only drift already on main), synced the Rust vendored
proto and set emit_stream_attached in the Rust StreamEventsRequest literals.
No package versions bumped.

Tests: ordering (sentinel first, then events), race proof (event fanned right
after the sentinel is delivered — mutation-checked: fails when the sentinel is
yielded before registration), resume-with-gap order, refused attach emits no
sentinel, default emits none, contract field numbers, capability, and .NET
client wire tests (await, no-capability, older gateway, timeout).
This commit is contained in:
Joseph Doherty
2026-11-12 07:26:49 -05:00
parent 892bdc1a19
commit afd504d5ae
28 changed files with 2329 additions and 1005 deletions
@@ -223,6 +223,47 @@ public sealed class MxGatewayClientSessionTests
Assert.Equal("session-fixture", request.SessionId);
}
/// <summary>
/// #227: the default stream call leaves emit_stream_attached unset (the pre-#227 wire shape);
/// the opt-in overload sets it and surfaces the sentinel as a typed item.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StreamEventItemsAsync_OptIn_SurfacesStreamAttachedSentinel()
{
FakeGatewayTransport transport = CreateTransport();
transport.AddEvent(new MxEvent
{
SessionId = "session-fixture",
StreamAttached = new StreamAttached { LiveAfterSequence = 0 },
});
transport.AddEvent(new MxEvent
{
SessionId = "session-fixture",
Family = MxEventFamily.OnDataChange,
WorkerSequence = 1,
});
await using MxGatewayClient client = CreateClient(transport);
MxGatewaySession session = await client.OpenSessionAsync();
await foreach (MxEvent _ in session.StreamEventsAsync())
{
}
List<MxEventStreamItem> items = [];
await foreach (MxEventStreamItem item in session.StreamEventItemsAsync(0, emitStreamAttached: true))
{
items.Add(item);
}
Assert.False(transport.StreamEventsCalls[0].Request.EmitStreamAttached);
Assert.True(transport.StreamEventsCalls[1].Request.EmitStreamAttached);
Assert.True(items[0].IsStreamAttached);
Assert.False(items[0].IsReplayGap);
Assert.False(items[1].IsStreamAttached);
Assert.Equal(1UL, items[1].Event.WorkerSequence);
}
/// <summary>
/// Verifies that a reconnect-replay gap sentinel is surfaced as a typed
/// <see cref="MxEventStreamItem"/> with the gap populated, while normal
@@ -130,6 +130,87 @@ public sealed class MxGatewayClientWireTests
Assert.Equal(3ul, server.Service.StreamEventsRequest?.AfterWorkerSequence);
}
/// <summary>
/// #227: <see cref="MxGatewaySession.OpenEventStreamAsync"/> asks for the attach
/// acknowledgement, completes on the sentinel, and yields only the events after it.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OpenEventStreamAsync_AwaitsTheAttachSentinel_ThenYieldsLaterEvents()
{
await using WireFakeGatewayServer server = await WireFakeGatewayServer.StartAsync(service =>
service.SupportsStreamAttached = true);
await using MxGatewayClient client = server.CreateClient(ApiKey);
MxGatewaySession session = await client.OpenSessionAsync(new OpenSessionRequest());
Assert.True(session.SupportsStreamAttachedAck);
await using MxGatewayEventStream stream = await session.OpenEventStreamAsync(
attachTimeout: TimeSpan.FromSeconds(10));
Assert.True(server.Service.StreamEventsRequest?.EmitStreamAttached);
Assert.Equal(0ul, stream.Attached.LiveAfterSequence);
List<MxEvent> events = [];
await foreach (MxEvent gatewayEvent in stream.ReadAllAsync())
{
events.Add(gatewayEvent);
}
MxEvent only = Assert.Single(events);
Assert.Null(only.StreamAttached);
Assert.Equal(9ul, only.WorkerSequence);
}
/// <summary>
/// #227: a session whose gateway does not advertise the capability fails fast with
/// <see cref="NotSupportedException"/> and never opens a stream.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OpenEventStreamAsync_OnGatewayWithoutCapability_ThrowsWithoutStreaming()
{
await using WireFakeGatewayServer server = await WireFakeGatewayServer.StartAsync();
await using MxGatewayClient client = server.CreateClient(ApiKey);
MxGatewaySession session = await client.OpenSessionAsync(new OpenSessionRequest());
Assert.False(session.SupportsStreamAttachedAck);
await Assert.ThrowsAsync<NotSupportedException>(() => session.OpenEventStreamAsync());
Assert.Null(server.Service.StreamEventsRequest);
}
/// <summary>
/// #227: a session bound with AttachSession (no capability list) against an older gateway
/// sees a normal event first and is refused rather than handed an unacknowledged stream.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OpenEventStreamAsync_AttachedSessionOnOlderGateway_RejectsNonSentinelFirstMessage()
{
await using WireFakeGatewayServer server = await WireFakeGatewayServer.StartAsync();
await using MxGatewayClient client = server.CreateClient(ApiKey);
MxGatewaySession session = client.AttachSession(WireFakeGatewayServer.FakeGatewayService.SessionId);
await Assert.ThrowsAsync<NotSupportedException>(
() => session.OpenEventStreamAsync(attachTimeout: TimeSpan.FromSeconds(10)));
Assert.True(server.Service.StreamEventsRequest?.EmitStreamAttached);
}
/// <summary>
/// #227: against a quiet older gateway nothing arrives; the attach timeout bounds the wait.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OpenEventStreamAsync_WhenNoSentinelArrives_TimesOut()
{
await using WireFakeGatewayServer server = await WireFakeGatewayServer.StartAsync(service =>
service.StallStream = true);
await using MxGatewayClient client = server.CreateClient(ApiKey);
MxGatewaySession session = client.AttachSession(WireFakeGatewayServer.FakeGatewayService.SessionId);
await Assert.ThrowsAsync<TimeoutException>(
() => session.OpenEventStreamAsync(attachTimeout: TimeSpan.FromMilliseconds(200)));
}
/// <summary>
/// Verifies a genuine <c>PERMISSION_DENIED</c> status maps to the typed client
/// exception rather than a bare RpcException.
@@ -155,6 +155,19 @@ internal sealed class WireFakeGatewayServer : IAsyncDisposable
/// </summary>
public ReplayGap? ReplayGap { get; set; }
/// <summary>
/// Gets or sets whether this fake behaves as a #227 gateway: it advertises the
/// attach-acknowledgement capability and, when a request asks for it, writes the
/// stream-attached sentinel first. False models a gateway that predates #227.
/// </summary>
public bool SupportsStreamAttached { get; set; }
/// <summary>
/// Gets or sets whether the stream stalls (until the call is cancelled) instead of
/// writing the canned data-change event — a quiet session on an older gateway.
/// </summary>
public bool StallStream { get; set; }
/// <summary>
/// Gets the last <c>Invoke</c> request the client sent, as decoded from the wire.
/// </summary>
@@ -176,7 +189,7 @@ internal sealed class WireFakeGatewayServer : IAsyncDisposable
ServerCallContext context)
{
Record(context);
return Task.FromResult(new OpenSessionReply
OpenSessionReply reply = new()
{
SessionId = SessionId,
BackendName = "fake-backend",
@@ -185,7 +198,13 @@ internal sealed class WireFakeGatewayServer : IAsyncDisposable
GatewayProtocolVersion = 3,
Capabilities = { "events", "invoke" },
ProtocolStatus = Ok(),
});
};
if (SupportsStreamAttached)
{
reply.Capabilities.Add(ZB.MOM.WW.MxGateway.Contracts.GatewayCapabilities.StreamEventsAttachedAck);
}
return Task.FromResult(reply);
}
/// <inheritdoc />
@@ -230,6 +249,21 @@ internal sealed class WireFakeGatewayServer : IAsyncDisposable
Record(context);
StreamEventsRequest = request;
if (SupportsStreamAttached && request.EmitStreamAttached)
{
// The #227 sentinel shape: family unspecified, body unset, worker_sequence 0.
await responseStream.WriteAsync(new MxEvent
{
SessionId = request.SessionId,
StreamAttached = new StreamAttached { LiveAfterSequence = request.AfterWorkerSequence },
}).ConfigureAwait(false);
}
if (StallStream)
{
await Task.Delay(Timeout.InfiniteTimeSpan, context.CancellationToken).ConfigureAwait(false);
}
if (ReplayGap is not null)
{
// The sentinel shape the gateway emits: family unspecified, body unset,