afd504d5ae
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).
41 lines
1.8 KiB
C#
41 lines
1.8 KiB
C#
using System.Runtime.CompilerServices;
|
|
using ZB.MOM.WW.MxGateway.Contracts.Proto;
|
|
|
|
namespace ZB.MOM.WW.MxGateway.Client;
|
|
|
|
/// <summary>
|
|
/// Extension methods that project a raw <see cref="MxEvent"/> stream into the
|
|
/// typed <see cref="MxEventStreamItem"/> surface, making the gateway's
|
|
/// reconnect-replay gap sentinel observable.
|
|
/// </summary>
|
|
public static class MxEventStreamExtensions
|
|
{
|
|
/// <summary>
|
|
/// Projects a raw <see cref="MxEvent"/> stream (e.g.
|
|
/// <see cref="MxGatewaySession.StreamEventsAsync(ulong, CancellationToken)"/> or
|
|
/// <see cref="MxGatewayClient.StreamEventsAsync"/>) into typed
|
|
/// <see cref="MxEventStreamItem"/> values. Normal events pass through with
|
|
/// <see cref="MxEventStreamItem.IsReplayGap"/> false; the gateway's
|
|
/// reconnect-replay gap sentinel is surfaced with
|
|
/// <see cref="MxEventStreamItem.IsReplayGap"/> true and
|
|
/// <see cref="MxEventStreamItem.ReplayGap"/> populated. The stream is
|
|
/// forwarded faithfully — no event is synthesized or dropped.
|
|
/// </summary>
|
|
/// <param name="source">The raw event stream to wrap.</param>
|
|
/// <param name="cancellationToken">Cancellation token for the enumeration.</param>
|
|
/// <returns>The same events, each wrapped as an <see cref="MxEventStreamItem"/>.</returns>
|
|
public static async IAsyncEnumerable<MxEventStreamItem> AsStreamItemsAsync(
|
|
this IAsyncEnumerable<MxEvent> source,
|
|
[EnumeratorCancellation] CancellationToken cancellationToken = default)
|
|
{
|
|
ArgumentNullException.ThrowIfNull(source);
|
|
|
|
await foreach (MxEvent gatewayEvent in source
|
|
.WithCancellation(cancellationToken)
|
|
.ConfigureAwait(false))
|
|
{
|
|
yield return MxEventStreamItem.From(gatewayEvent);
|
|
}
|
|
}
|
|
}
|