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:
@@ -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;
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user