Skip to main content
Pass a 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

Every method is optional - the SDK calls only the ones you set. You can write { 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:
  • resync
  • config.created / config.updated / config.deleted
  • flag.created / flag.updated / flag.toggled / flag.deleted
  • secret.created / secret.updated / secret.deleted
Unknown events (or the WIF 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:
  1. Without Retry-After - the server returned 429 without a parseable Retry-After header. The SDK sets client.streamStatus to 'fallback' and reconnects on the sseReconnectCooldown schedule.
  2. With Retry-After - the header’s delay (clamped to [5 s, 5 min]) is honoured: client.streamStatus is '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.
In other words, 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

Observer methods are called synchronously from the SDK’s stream-reader event loop. They MUST return promptly.
If your observer does anything substantial (network I/O, mutex contention, disk writes), copy the argument and dispatch the work via setImmediate, 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.
  • StreamObserver carries structured metrics for tooling.