StreamObserver via NexusConfig.streamObserver to receive structured callbacks for every SSE lifecycle transition. The observer is the canonical way to wire SDK state into ops dashboards, custom telemetry, or load-test tooling - far more reliable than matching substrings in log output.
The observer is opt-in. When NexusConfig.streamObserver is undefined the SDK uses NOOP_STREAM_OBSERVER at zero overhead.
The interface
{ onEvent: (n) => count(n) } and ignore the rest.
Hook semantics
What counts as a “whitelisted event”
onEvent fires only for events on the SDK’s documented event-type list:
resyncconfig.created/config.updated/config.deletedflag.created/flag.updated/flag.toggled/flag.deletedsecret.created/secret.updated/secret.deleted
auth_expiring control event) do NOT trigger onEvent.
onFallback reasons
A successful connection starts the failure count and the backoff over, so failures before it never add up to a fallback.
FALLBACK_REASON_RATE_LIMITED - two cases
'rate-limited' fires in both of the following situations, and the stream recovers by itself in both:
- Without
Retry-After- the server returned429without a parseableRetry-Afterheader. The SDK setsclient.streamStatusto'fallback'and reconnects on thesseReconnectCooldownschedule. - With
Retry-After- the header’s delay (clamped to[5 s, 5 min]) is honoured:client.streamStatusis'disconnected'while the SDK waits, then it reconnects. The delay does not count as a transport failure.
A quarantine
429 (body {"error":"quarantined",...}) does NOT fire onFallback - it fires onQuarantined instead. The stream reconnects automatically at expiresAt.onFallback('rate-limited') is per rate-limit episode, not a “the SDK has given up” signal. To tell the two cases apart, read client.streamStatus on the next tick: 'fallback' without Retry-After, 'disconnected' while a Retry-After delay runs.
Threading contract
If your observer does anything substantial (network I/O, mutex contention, disk writes), copy the argument and dispatch the work viasetImmediate, queueMicrotask, or your own queue before returning:
Counter pattern
Active-connection gauge pattern
onFallback is included because the stream is down while it waits out a cooldown or a Retry-After delay (or has exited on service-locked). For every reason except service-locked, the SDK reconnects on its own and onConnected fires again when the stream comes back.
Independence from the logger
The observer is independent of any logging output. The two are complementary:- The SDK’s logger carries human-readable text for operators, with structured fields.
StreamObservercarries structured metrics for tooling.
