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:
@@ -1,4 +1,5 @@
|
||||
using Grpc.Core;
|
||||
using ZB.MOM.WW.MxGateway.Contracts;
|
||||
using ZB.MOM.WW.MxGateway.Contracts.Proto;
|
||||
|
||||
namespace ZB.MOM.WW.MxGateway.Client;
|
||||
@@ -1518,7 +1519,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
|
||||
|
||||
/// <summary>
|
||||
/// Drains events queued in the worker through the diagnostic command path. This removes
|
||||
/// events from the worker queue; it is not a substitute for <see cref="StreamEventsAsync"/>
|
||||
/// events from the worker queue; it is not a substitute for <see cref="StreamEventsAsync(ulong, CancellationToken)"/>
|
||||
/// and is not retried automatically. The reply is bounded by server-side caps, so call
|
||||
/// repeatedly until it returns an empty list.
|
||||
/// </summary>
|
||||
@@ -1572,6 +1573,111 @@ public sealed class MxGatewaySession : IAsyncDisposable
|
||||
cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Streams events, optionally asking the gateway for the stream-attached sentinel (#227).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// With <paramref name="emitStreamAttached"/> set, a gateway that advertises
|
||||
/// <see cref="SupportsStreamAttachedAck"/> sends one sentinel <see cref="MxEvent"/> first, with
|
||||
/// <see cref="MxEvent.StreamAttached"/> populated, after it has registered the stream. Consumers
|
||||
/// that advise items only after seeing it cannot lose an initial value to the attach race. The
|
||||
/// sentinel's <c>worker_sequence</c> is 0 and must not be used as a resume cursor. Use
|
||||
/// <see cref="OpenEventStreamAsync"/> to await the sentinel instead of inspecting the stream.
|
||||
/// </remarks>
|
||||
/// <param name="afterWorkerSequence">The sequence number to stream from; 0 for a fresh stream.</param>
|
||||
/// <param name="emitStreamAttached">Whether to ask the gateway for the stream-attached sentinel.</param>
|
||||
/// <param name="cancellationToken">Cancellation token.</param>
|
||||
/// <returns>An async enumerable of events.</returns>
|
||||
public IAsyncEnumerable<MxEvent> StreamEventsAsync(
|
||||
ulong afterWorkerSequence,
|
||||
bool emitStreamAttached,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
return _client.StreamEventsAsync(
|
||||
new StreamEventsRequest
|
||||
{
|
||||
SessionId = SessionId,
|
||||
AfterWorkerSequence = afterWorkerSequence,
|
||||
EmitStreamAttached = emitStreamAttached,
|
||||
},
|
||||
cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Typed-item variant of <see cref="StreamEventsAsync(ulong, bool, CancellationToken)"/>: the
|
||||
/// stream-attached sentinel arrives as an item with <see cref="MxEventStreamItem.IsStreamAttached"/> set.
|
||||
/// </summary>
|
||||
/// <param name="afterWorkerSequence">The sequence number to stream from; 0 for a fresh stream.</param>
|
||||
/// <param name="emitStreamAttached">Whether to ask the gateway for the stream-attached sentinel.</param>
|
||||
/// <param name="cancellationToken">Cancellation token.</param>
|
||||
/// <returns>An async enumerable of typed event items.</returns>
|
||||
public IAsyncEnumerable<MxEventStreamItem> StreamEventItemsAsync(
|
||||
ulong afterWorkerSequence,
|
||||
bool emitStreamAttached,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
return StreamEventsAsync(afterWorkerSequence, emitStreamAttached, cancellationToken)
|
||||
.AsStreamItemsAsync(cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// <see langword="true"/> when the gateway listed
|
||||
/// <see cref="GatewayCapabilities.StreamEventsAttachedAck"/> in this session's
|
||||
/// <see cref="OpenSessionReply"/>, i.e. it honours the stream-attached request (#227).
|
||||
/// <see langword="false"/> for an older gateway, and also for a session bound with
|
||||
/// <see cref="MxGatewayClient.AttachSession"/>, whose reply carries no capabilities.
|
||||
/// </summary>
|
||||
public bool SupportsStreamAttachedAck =>
|
||||
OpenSessionReply.Capabilities.Contains(GatewayCapabilities.StreamEventsAttachedAck);
|
||||
|
||||
/// <summary>
|
||||
/// Opens the session's event stream and completes once the gateway confirms it is attached
|
||||
/// (#227). Advise items after this returns: every event the session publishes from then on
|
||||
/// reaches the returned stream, so no initial value is lost to the attach race.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// The returned <see cref="MxGatewayEventStream"/> owns the call; read the remaining events
|
||||
/// with <see cref="MxGatewayEventStream.ReadAllAsync"/> (the sentinel itself is consumed here)
|
||||
/// and dispose it to end the stream. <paramref name="cancellationToken"/> governs the whole
|
||||
/// stream's lifetime, not only the wait; bound the wait with <paramref name="attachTimeout"/>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// When the session's reply lists capabilities but not the attach acknowledgement, the gateway
|
||||
/// predates #227 and this throws <see cref="NotSupportedException"/> without opening a stream.
|
||||
/// A session bound with <see cref="MxGatewayClient.AttachSession"/> has no capability list, so
|
||||
/// the request is sent anyway; against an older gateway the first message is then a normal
|
||||
/// event (or nothing), which ends the stream with <see cref="NotSupportedException"/> or
|
||||
/// <see cref="TimeoutException"/>.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <param name="afterWorkerSequence">The sequence number to stream from; 0 for a fresh stream.</param>
|
||||
/// <param name="attachTimeout">Upper bound on the wait for the sentinel; <see langword="null"/> waits indefinitely.</param>
|
||||
/// <param name="cancellationToken">Cancels the wait and, afterwards, the stream.</param>
|
||||
/// <returns>The attached stream.</returns>
|
||||
/// <exception cref="NotSupportedException">The gateway does not send the attach acknowledgement.</exception>
|
||||
/// <exception cref="TimeoutException">No sentinel arrived within <paramref name="attachTimeout"/>.</exception>
|
||||
public async Task<MxGatewayEventStream> OpenEventStreamAsync(
|
||||
ulong afterWorkerSequence = 0,
|
||||
TimeSpan? attachTimeout = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
if (OpenSessionReply.Capabilities.Count > 0 && !SupportsStreamAttachedAck)
|
||||
{
|
||||
throw new NotSupportedException(
|
||||
$"The gateway for session {SessionId} does not advertise "
|
||||
+ $"'{GatewayCapabilities.StreamEventsAttachedAck}'; it cannot acknowledge an event-stream attach.");
|
||||
}
|
||||
|
||||
return await MxGatewayEventStream
|
||||
.OpenAsync(
|
||||
token => StreamEventsAsync(afterWorkerSequence, emitStreamAttached: true, token),
|
||||
SessionId,
|
||||
attachTimeout,
|
||||
cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Streams events as typed <see cref="MxEventStreamItem"/> values, surfacing
|
||||
/// the gateway's reconnect-replay gap sentinel as an observable, typed signal.
|
||||
@@ -1586,7 +1692,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
|
||||
/// incurring another gap, reconnect with
|
||||
/// <c>afterWorkerSequence = item.ReplayGap.OldestAvailableSequence - 1</c>.
|
||||
/// All other events pass through with <see cref="MxEventStreamItem.IsReplayGap"/>
|
||||
/// false. Use <see cref="StreamEventsAsync"/> when raw generated
|
||||
/// false. Use <see cref="StreamEventsAsync(ulong, CancellationToken)"/> when raw generated
|
||||
/// <see cref="MxEvent"/> messages are needed instead.
|
||||
/// </remarks>
|
||||
/// <param name="afterWorkerSequence">The sequence number to stream from. Defaults to 0.</param>
|
||||
|
||||
Reference in New Issue
Block a user