StreamObserver via NexusConfig.stream_observer 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 scraping NexusLogger output by substring match.
The observer is opt-in. When NexusConfig.stream_observer is None the SDK uses NOOP_STREAM_OBSERVER at zero overhead.
The interface
getattr, so consumers may omit any method they don’t care about (the SDK handles missing-attribute cases gracefully).
Hook semantics
on_fallback reasons
The stream reconnects on its own after every reason except
'service-locked'.
rate-limited fires in both of these situations:
- Server included a parseable
Retry-Afterheader. The SDK fireson_fallback(FALLBACK_REASON_RATE_LIMITED), sleeps the indicated delay clamped to[5, 300]seconds, and then reconnects automatically. The 429 does not count as a transport failure. Expect a matchingon_connected()shortly after the sleep window. - No parseable
Retry-After. The SDK fireson_fallback(FALLBACK_REASON_RATE_LIMITED)and reconnects on thesse_reconnect_cooldownschedule; TTL polling covers the gap.
Threading contract
For the synchronousNexusClient, observer methods are called synchronously from the SDK’s stream thread. For the async AsyncNexusClient, observer methods are called synchronously from the asyncio task running the stream - they are NOT awaited even if you define them as coroutines.
If your observer does anything substantial (network I/O, lock contention, disk writes), copy the argument and dispatch the work to your own thread / task before returning:
If your observer raises
An exception from an observer method is caught and absorbed - a faulty observer can never break the stream, stall a sync, or propagate into your own code paths. It is also logged. The SDK reports it throughNexusLogger at error level, naming the hook that failed and attaching the original exception as the cause:
logger=, it goes to the westyx_nexus stdlib logger.
This follows the OpenTelemetry error-handling specification, which covers the same situation from both sides: “API methods that accept external callbacks MUST handle all errors”, and “whenever the library suppresses an error that would otherwise have been exposed to the user, the library SHOULD log the error”.
A missing hook is not a fault: at runtime the SDK skips any callback the object does not have, so an observer may implement only the ones it needs. A type checker reads StreamObserver as a full Protocol, though, so an object passed as stream_observer= type-checks only when it has all six - write the ones you do not need as no-ops, as the counter below does.
Counter pattern
Active-connection gauge pattern
on_fallback 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 the gauge flips back to True on the next on_connected().