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).
164 lines
6.3 KiB
C#
164 lines
6.3 KiB
C#
using System.Runtime.CompilerServices;
|
|
using ZB.MOM.WW.MxGateway.Contracts.Proto;
|
|
|
|
namespace ZB.MOM.WW.MxGateway.Client;
|
|
|
|
/// <summary>
|
|
/// An event stream the gateway has confirmed attached (#227), returned by
|
|
/// <see cref="MxGatewaySession.OpenEventStreamAsync"/>. Its existence is the attach signal:
|
|
/// every event the session publishes after it was created reaches <see cref="ReadAllAsync"/>.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The stream-attached sentinel is consumed when the stream opens and is not yielded again.
|
|
/// A replay-gap sentinel on a resumed stream is a normal stream item and is yielded as-is
|
|
/// (inspect <see cref="MxEvent.ReplayGap"/>, or wrap with
|
|
/// <see cref="MxEventStreamExtensions.AsStreamItemsAsync"/>). Dispose to end the call.
|
|
/// </remarks>
|
|
public sealed class MxGatewayEventStream : IAsyncDisposable
|
|
{
|
|
private readonly IAsyncEnumerator<MxEvent> _enumerator;
|
|
private readonly CancellationTokenSource _lifetime;
|
|
private int _readStarted;
|
|
private int _disposed;
|
|
|
|
private MxGatewayEventStream(
|
|
IAsyncEnumerator<MxEvent> enumerator,
|
|
CancellationTokenSource lifetime,
|
|
StreamAttached attached)
|
|
{
|
|
_enumerator = enumerator;
|
|
_lifetime = lifetime;
|
|
Attached = attached;
|
|
}
|
|
|
|
/// <summary>
|
|
/// The gateway's attach acknowledgement. Live events on this stream have a
|
|
/// <c>worker_sequence</c> strictly greater than <see cref="StreamAttached.LiveAfterSequence"/>.
|
|
/// </summary>
|
|
public StreamAttached Attached { get; }
|
|
|
|
/// <summary>
|
|
/// Reads the events that follow the attach acknowledgement. May be enumerated once.
|
|
/// </summary>
|
|
/// <param name="cancellationToken">Cancels the enumeration and ends the stream.</param>
|
|
/// <returns>The remaining events, in gateway order.</returns>
|
|
/// <exception cref="InvalidOperationException">The stream was already enumerated.</exception>
|
|
public async IAsyncEnumerable<MxEvent> ReadAllAsync(
|
|
[EnumeratorCancellation] CancellationToken cancellationToken = default)
|
|
{
|
|
ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) != 0, this);
|
|
if (Interlocked.Exchange(ref _readStarted, 1) != 0)
|
|
{
|
|
throw new InvalidOperationException("The event stream can be enumerated only once.");
|
|
}
|
|
|
|
using CancellationTokenRegistration registration = cancellationToken.Register(
|
|
static state => ((CancellationTokenSource)state!).Cancel(),
|
|
_lifetime);
|
|
|
|
while (await _enumerator.MoveNextAsync().ConfigureAwait(false))
|
|
{
|
|
yield return _enumerator.Current;
|
|
}
|
|
}
|
|
|
|
/// <summary>Cancels the underlying call and releases it.</summary>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
public async ValueTask DisposeAsync()
|
|
{
|
|
if (Interlocked.Exchange(ref _disposed, 1) != 0)
|
|
{
|
|
return;
|
|
}
|
|
|
|
await _lifetime.CancelAsync().ConfigureAwait(false);
|
|
try
|
|
{
|
|
await _enumerator.DisposeAsync().ConfigureAwait(false);
|
|
}
|
|
finally
|
|
{
|
|
_lifetime.Dispose();
|
|
}
|
|
}
|
|
|
|
// Opens the stream and consumes the first message, which must be the stream-attached
|
|
// sentinel. Anything else means the gateway ignored the request (it predates #227): the
|
|
// stream is closed rather than handed out, because it cannot keep the attach promise.
|
|
internal static async Task<MxGatewayEventStream> OpenAsync(
|
|
Func<CancellationToken, IAsyncEnumerable<MxEvent>> openStream,
|
|
string sessionId,
|
|
TimeSpan? attachTimeout,
|
|
CancellationToken cancellationToken)
|
|
{
|
|
CancellationTokenSource lifetime = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
|
|
IAsyncEnumerator<MxEvent> enumerator = openStream(lifetime.Token).GetAsyncEnumerator(lifetime.Token);
|
|
Task<bool>? first = null;
|
|
bool handedOff = false;
|
|
try
|
|
{
|
|
first = enumerator.MoveNextAsync().AsTask();
|
|
bool hasFirst;
|
|
try
|
|
{
|
|
hasFirst = attachTimeout is { } timeout
|
|
? await first.WaitAsync(timeout, cancellationToken).ConfigureAwait(false)
|
|
: await first.WaitAsync(cancellationToken).ConfigureAwait(false);
|
|
}
|
|
catch (TimeoutException) when (!first.IsCompleted)
|
|
{
|
|
throw new TimeoutException(
|
|
$"The gateway did not acknowledge the event-stream attach for session {sessionId} within {attachTimeout}.");
|
|
}
|
|
|
|
if (!hasFirst)
|
|
{
|
|
throw new MxGatewayException(
|
|
$"The gateway ended the event stream for session {sessionId} before acknowledging the attach.");
|
|
}
|
|
|
|
if (enumerator.Current.StreamAttached is not { } attached)
|
|
{
|
|
throw new NotSupportedException(
|
|
$"The gateway's first event-stream message for session {sessionId} was not the attach "
|
|
+ "acknowledgement; the gateway does not support emit_stream_attached.");
|
|
}
|
|
|
|
MxGatewayEventStream stream = new(enumerator, lifetime, attached);
|
|
handedOff = true;
|
|
return stream;
|
|
}
|
|
finally
|
|
{
|
|
if (!handedOff)
|
|
{
|
|
await lifetime.CancelAsync().ConfigureAwait(false);
|
|
|
|
// An async iterator cannot be disposed while a MoveNext is in flight (the timeout
|
|
// and caller-cancel paths leave one pending), so let the cancelled read unwind first.
|
|
// Its outcome is irrelevant: the failure being thrown is what the caller needs.
|
|
if (first is not null)
|
|
{
|
|
try
|
|
{
|
|
await first.ConfigureAwait(false);
|
|
}
|
|
catch (Exception)
|
|
{
|
|
// Swallowed deliberately; see above.
|
|
}
|
|
}
|
|
|
|
try
|
|
{
|
|
await enumerator.DisposeAsync().ConfigureAwait(false);
|
|
}
|
|
finally
|
|
{
|
|
lifetime.Dispose();
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|