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
+40
View File
@@ -137,6 +137,46 @@ gateway's own sentinel observable. Normal events pass through with
`IsReplayGap == false` and `ReplayGap == null`. The gap is only ever produced by
`StreamEvents`; the diagnostic drain path never emits it. If you already consume
the raw `StreamEventsAsync` (or the client-level stream), the
### Waiting For The Stream To Attach
A fresh stream (`afterWorkerSequence == 0`) is never replayed, so an initial value
the session publishes before the gateway has registered the stream is lost. That
matters for an advise whose only interesting event is its first one (a slow-changing
attribute such as `ScanState`). Opening the stream and then waiting an arbitrary
interval only narrows the race. `OpenEventStreamAsync` closes it: it asks the
gateway for the opt-in **stream-attached sentinel** (`emit_stream_attached`, #227)
and completes only when that sentinel arrives, which the gateway sends after it has
registered the stream.
```csharp
await using MxGatewayEventStream stream = await session.OpenEventStreamAsync(
attachTimeout: TimeSpan.FromSeconds(5));
// The stream is attached: an advise issued now cannot lose its initial value.
await session.SubscribeBulkAsync(addresses);
await foreach (MxEvent gatewayEvent in stream.ReadAllAsync(cancellationToken))
{
HandleEvent(gatewayEvent);
}
```
The sentinel is consumed by `OpenEventStreamAsync`; `ReadAllAsync` yields only what
follows it (a replay-gap sentinel on a resumed stream is still yielded). The method
throws `NotSupportedException` without streaming when the session's
`OpenSessionReply` lists capabilities but not `stream-events-attached-ack`
(`SupportsStreamAttachedAck` is `false`), i.e. the gateway predates #227. A session
bound with `AttachSession` carries no capability list, so the request is sent anyway;
an older gateway then answers with a normal event (`NotSupportedException`) or nothing
(`TimeoutException` once `attachTimeout` elapses).
Callers that run their own stream loop can use
`StreamEventsAsync(afterWorkerSequence, emitStreamAttached: true)` or the typed
`StreamEventItemsAsync(afterWorkerSequence, emitStreamAttached: true)` and watch for
`MxEvent.StreamAttached` / `MxEventStreamItem.IsStreamAttached`. The sentinel's
`WorkerSequence` is `0`: do not store it as the resume cursor. Without
`emitStreamAttached` the stream is exactly the pre-#227 shape.
### Caller-owned channels, resuming sessions, diagnostics
`MxGatewayClient.Create(GrpcChannel, MxGatewayClientOptions)` and