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:
@@ -1424,6 +1424,11 @@ Resolved for v1:
|
||||
- Reconnectable sessions: clients reconnect by re-issuing `StreamEvents` with
|
||||
`after_worker_sequence`; the gateway replays the retained ring tail and emits
|
||||
a `ReplayGap` sentinel when events were evicted. See `docs/Sessions.md`.
|
||||
- Attach acknowledgement (#227): a client that sets
|
||||
`StreamEventsRequest.emit_stream_attached` receives a `StreamAttached`
|
||||
sentinel first, once the stream's subscriber is registered, so it can advise
|
||||
items without racing the first event. Opt-in; advertised as the
|
||||
`stream-events-attached-ack` capability. See `docs/Sessions.md`.
|
||||
- Multi-subscriber event fan-out: multiple concurrent `StreamEvents` callers on
|
||||
the same session are supported; single-subscriber mode uses fail-fast
|
||||
backpressure, multi-subscriber mode disconnects only the slow consumer. See
|
||||
|
||||
Reference in New Issue
Block a user