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