using ZB.MOM.WW.MxGateway.Contracts.Proto;
namespace ZB.MOM.WW.MxGateway.Client;
///
/// One item yielded by the typed event stream. It is either a normal MXAccess
/// , a reconnect-replay gap sentinel, or — only on a stream
/// that asked for it — the stream-attached sentinel (#227).
///
///
///
/// The gateway emits a single sentinel at the head of a
/// StreamEvents stream that was resumed via
/// StreamEventsRequest.after_worker_sequence when the requested sequence
/// predates the oldest event still retained in the session replay ring — i.e.
/// events were evicted and cannot be replayed. On that sentinel the
/// MxEvent.replay_gap field is set, is
/// , the body oneof is unset, and
/// no per-item fields are populated.
///
///
/// This wrapper makes that sentinel observable instead of forcing the consumer
/// to inspect the raw . It never synthesizes or swallows an
/// event: the gap is exactly the gateway's own sentinel, exposed with
/// set and populated. Every
/// other event flows through unchanged with false.
///
///
/// When is the consumer has
/// missed events and MUST discard local state and re-snapshot. To resume without
/// incurring another gap, reconnect with
/// after_worker_sequence = ReplayGap.OldestAvailableSequence - 1.
///
///
/// When the stream was opened with emit_stream_attached, its first item is the
/// stream-attached sentinel: is and
/// is populated. It means the gateway has registered the stream,
/// so every event published from then on is delivered. Its worker_sequence is 0 and
/// must not be used as a resume cursor.
///
///
public sealed class MxEventStreamItem
{
private MxEventStreamItem(MxEvent gatewayEvent, ReplayGap? replayGap, StreamAttached? streamAttached)
{
Event = gatewayEvent;
ReplayGap = replayGap;
StreamAttached = streamAttached;
}
///
/// The underlying raw . For a normal event this is the
/// MXAccess event itself; for a replay-gap item this is the gateway's
/// sentinel event whose only meaningful payload is .
/// Never .
///
public MxEvent Event { get; }
///
/// The reconnect-replay gap payload when this item is a gap sentinel;
/// otherwise . Read
/// and
/// to learn
/// which events were lost.
///
public ReplayGap? ReplayGap { get; }
///
/// when this item is a reconnect-replay gap sentinel:
/// the consumer missed events and must discard local state and re-snapshot.
/// Resume without another gap by reconnecting with
/// after_worker_sequence = ReplayGap.OldestAvailableSequence - 1.
///
public bool IsReplayGap => ReplayGap is not null;
///
/// The attach acknowledgement when this item is the stream-attached sentinel (#227);
/// otherwise . Only a stream opened with
/// emit_stream_attached carries it, and only as its first item.
///
public StreamAttached? StreamAttached { get; }
///
/// 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.
///
public bool IsStreamAttached => StreamAttached is not null;
///
/// Wraps a raw stream as a typed item, classifying it
/// as a replay-gap sentinel when MxEvent.replay_gap is present.
///
/// The raw event from the StreamEvents stream.
/// A typed item exposing either the normal event or the replay gap.
internal static MxEventStreamItem From(MxEvent gatewayEvent)
{
ArgumentNullException.ThrowIfNull(gatewayEvent);
// For a message-typed proto3 field, presence is a non-null reference.
return new MxEventStreamItem(gatewayEvent, gatewayEvent.ReplayGap, gatewayEvent.StreamAttached);
}
}