feat(events): opt-in stream-attached acknowledgement on StreamEvents (#227)
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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user