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:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user