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

The protocol is structural - any object with the matching method signatures qualifies. Methods are looked up via 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-After header. The SDK fires on_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 matching on_connected() shortly after the sleep window.
  • No parseable Retry-After. The SDK fires on_fallback(FALLBACK_REASON_RATE_LIMITED) and reconnects on the sse_reconnect_cooldown schedule; TTL polling covers the gap.

Threading contract

For the synchronous NexusClient, 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.
In both cases observer methods MUST return promptly. The SDK does not protect against blocking observers.
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 through NexusLogger at error level, naming the hook that failed and attaching the original exception as the cause:
Without a 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().