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:
@@ -4,7 +4,8 @@ namespace ZB.MOM.WW.MxGateway.Client;
|
||||
|
||||
/// <summary>
|
||||
/// One item yielded by the typed event stream. It is either a normal MXAccess
|
||||
/// <see cref="MxEvent"/> or a reconnect-replay <em>gap sentinel</em>.
|
||||
/// <see cref="MxEvent"/>, a reconnect-replay <em>gap sentinel</em>, or — only on a stream
|
||||
/// that asked for it — the <em>stream-attached sentinel</em> (#227).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
@@ -30,13 +31,21 @@ namespace ZB.MOM.WW.MxGateway.Client;
|
||||
/// incurring another gap, reconnect with
|
||||
/// <c>after_worker_sequence = ReplayGap.OldestAvailableSequence - 1</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// When the stream was opened with <c>emit_stream_attached</c>, its first item is the
|
||||
/// stream-attached sentinel: <see cref="IsStreamAttached"/> is <see langword="true"/> and
|
||||
/// <see cref="StreamAttached"/> is populated. It means the gateway has registered the stream,
|
||||
/// so every event published from then on is delivered. Its <c>worker_sequence</c> is 0 and
|
||||
/// must not be used as a resume cursor.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class MxEventStreamItem
|
||||
{
|
||||
private MxEventStreamItem(MxEvent gatewayEvent, ReplayGap? replayGap)
|
||||
private MxEventStreamItem(MxEvent gatewayEvent, ReplayGap? replayGap, StreamAttached? streamAttached)
|
||||
{
|
||||
Event = gatewayEvent;
|
||||
ReplayGap = replayGap;
|
||||
StreamAttached = streamAttached;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
@@ -64,6 +73,20 @@ public sealed class MxEventStreamItem
|
||||
/// </summary>
|
||||
public bool IsReplayGap => ReplayGap is not null;
|
||||
|
||||
/// <summary>
|
||||
/// The attach acknowledgement when this item is the stream-attached sentinel (#227);
|
||||
/// otherwise <see langword="null"/>. Only a stream opened with
|
||||
/// <c>emit_stream_attached</c> carries it, and only as its first item.
|
||||
/// </summary>
|
||||
public StreamAttached? StreamAttached { get; }
|
||||
|
||||
/// <summary>
|
||||
/// <see langword="true"/> when this item is the stream-attached sentinel: the gateway has
|
||||
/// registered the stream, so an advise issued after this point cannot lose its initial value
|
||||
/// to the attach race.
|
||||
/// </summary>
|
||||
public bool IsStreamAttached => StreamAttached is not null;
|
||||
|
||||
/// <summary>
|
||||
/// Wraps a raw stream <see cref="MxEvent"/> as a typed item, classifying it
|
||||
/// as a replay-gap sentinel when <c>MxEvent.replay_gap</c> is present.
|
||||
@@ -75,8 +98,6 @@ public sealed class MxEventStreamItem
|
||||
ArgumentNullException.ThrowIfNull(gatewayEvent);
|
||||
|
||||
// For a message-typed proto3 field, presence is a non-null reference.
|
||||
return gatewayEvent.ReplayGap is { } replayGap
|
||||
? new MxEventStreamItem(gatewayEvent, replayGap)
|
||||
: new MxEventStreamItem(gatewayEvent, replayGap: null);
|
||||
return new MxEventStreamItem(gatewayEvent, gatewayEvent.ReplayGap, gatewayEvent.StreamAttached);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user