feat(events): opt-in stream-attached acknowledgement on StreamEvents (#227)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m28s
ci / java (push) Failing after 2m21s
ci / portable (push) Failing after 3m33s

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:
Joseph Doherty
2026-11-12 07:26:49 -05:00
parent 892bdc1a19
commit afd504d5ae
28 changed files with 2329 additions and 1005 deletions
+57 -5
View File
@@ -84,6 +84,20 @@ message CloseSessionReply {
message StreamEventsRequest {
string session_id = 1;
uint64 after_worker_sequence = 2;
// Opt-in attach acknowledgement (mxaccessgw#227). When true, the gateway emits
// one StreamAttached sentinel MxEvent (MxEvent.stream_attached) as the FIRST
// message of this stream, sent only after this stream's subscriber is
// registered on the session. Every event the session publishes after that
// registration is delivered to this stream (subject only to the
// after_worker_sequence filter and the backpressure policy), so a client that
// waits for the sentinel before issuing AddItem/Advise/SubscribeBulk cannot
// lose the initial value to the attach race.
// Default false keeps the pre-#227 wire behaviour: no sentinel. It is opt-in
// because existing consumers treat every streamed MxEvent's worker_sequence as
// a resume cursor and would read the sentinel's 0 as one. A gateway that
// predates this field ignores it and never sends the sentinel; such a gateway
// does not list "stream-events-attached-ack" in OpenSessionReply.capabilities.
bool emit_stream_attached = 3;
}
message MxCommandRequest {
@@ -405,6 +419,9 @@ message AcknowledgeAlarmCommand {
string operator_user = 3;
string operator_node = 4;
string operator_domain = 5;
// Accepted for wire compatibility but NOT propagated to MXAccess: the 8-arg
// AlarmAckByName that carried it returns -55. operator_domain IS used (the
// AuthenticateUser identity is "<operator_domain>\<operator_user>").
string operator_full_name = 6;
// Operator credential used for AuthenticateUser before the AckMsg write.
// Implementations must keep this field out of logs, metrics labels, command
@@ -435,6 +452,9 @@ message AcknowledgeAlarmByNameCommand {
string operator_user = 5;
string operator_node = 6;
string operator_domain = 7;
// Accepted for wire compatibility but NOT propagated to MXAccess: the 8-arg
// AlarmAckByName that carried it returns -55. operator_domain IS used (the
// AuthenticateUser identity is "<operator_domain>\<operator_user>").
string operator_full_name = 8;
// Operator credential used for AuthenticateUser before the AckMsg write.
// Implementations must keep this field out of logs, metrics labels, command
@@ -518,11 +538,15 @@ message WriteSecured2BulkEntry {
// reply returns the cached value WITHOUT modifying the existing
// subscription (was_cached = true).
// - Otherwise the worker takes the snapshot lifecycle itself: AddItem +
// Advise, wait up to `timeout_ms` for the first OnDataChange, then
// UnAdvise + RemoveItem before returning. The session is left exactly
// as it was before the call (was_cached = false).
// Advise, wait for the first OnDataChange, then UnAdvise + RemoveItem
// before returning. The session is left exactly as it was before the
// call (was_cached = false).
//
// `timeout_ms == 0` uses the gateway-configured default (1000 ms).
// `timeout_ms` is one deadline shared by the whole command, not a per-tag
// budget: the worker adds and advises every uncached tag, waits once for all
// of them, then tears them all down. A tag that has not delivered by the
// deadline gets its own was_successful = false result.
// `timeout_ms == 0` uses the worker's default (1000 ms).
message ReadBulkCommand {
int32 server_handle = 1;
repeated string tag_addresses = 2;
@@ -549,6 +573,7 @@ message ShutdownWorkerCommand {
message MxCommandReply {
string session_id = 1;
// Echoes the request's client_correlation_id.
string correlation_id = 2;
MxCommandKind kind = 3;
ProtocolStatus protocol_status = 4;
@@ -790,6 +815,18 @@ message MxEvent {
// Additive (proto3): existing clients that ignore this field continue to
// deserialize the stream unchanged.
optional ReplayGap replay_gap = 14;
// Gateway-synthesized attach acknowledgement (mxaccessgw#227). Set ONLY on the
// single sentinel MxEvent the gateway emits as the FIRST message of a
// StreamEvents stream whose request set emit_stream_attached = true. It is
// sent after the stream's subscriber is registered, so every event the
// session publishes after it reaches this stream. On a resumed stream it
// precedes the ReplayGap sentinel (if any) and the replayed events.
// On that sentinel, `family` is UNSPECIFIED, the `body` oneof is unset,
// `worker_sequence` is 0, and no per-item fields are populated: it is a
// control signal, not an MXAccess event, and its worker_sequence MUST NOT be
// used as a resume cursor. Never set on a stream that did not opt in, and
// ALWAYS unset on events in DrainEventsReply.
optional StreamAttached stream_attached = 15;
oneof body {
OnDataChangeEvent on_data_change = 20;
@@ -827,6 +864,19 @@ message ReplayGap {
uint64 oldest_available_sequence = 2;
}
// Attach acknowledgement carried by a sentinel MxEvent (MxEvent.stream_attached)
// at the head of a StreamEvents stream that requested it
// (StreamEventsRequest.emit_stream_attached). Its arrival means the stream is
// registered on the session: any event published from then on is delivered.
message StreamAttached {
// Live events on this stream are those with worker_sequence strictly greater
// than this value. 0 on a fresh stream (after_worker_sequence = 0). On a
// resumed stream it is the last sequence the replay batch that follows
// covers (or the requested after_worker_sequence when nothing is replayed),
// so it equals the watermark the gateway applies to live events.
uint64 live_after_sequence = 1;
}
enum MxEventFamily {
MX_EVENT_FAMILY_UNSPECIFIED = 0;
MX_EVENT_FAMILY_ON_DATA_CHANGE = 1;
@@ -880,7 +930,7 @@ message OnAlarmTransitionEvent {
// When the alarm originally entered the active state. Preserved across
// acknowledge transitions so the Part 9 condition keeps the original raise
// time. Unset on retrigger from a previously-cleared condition.
// time. Unset when the raise time is unknown (RETRIGGER is reserved and never produced).
google.protobuf.Timestamp original_raise_timestamp = 6;
// When this specific transition occurred (raise time on Raise, ack time on
@@ -930,6 +980,8 @@ enum AlarmTransitionKind {
ALARM_TRANSITION_KIND_RAISE = 1;
ALARM_TRANSITION_KIND_ACKNOWLEDGE = 2;
ALARM_TRANSITION_KIND_CLEAR = 3;
// Reserved: never produced by the gateway or worker. Retained so the numeric
// value is not reused.
ALARM_TRANSITION_KIND_RETRIGGER = 4;
}