.NET SDK - Stream Observer

Pass an IStreamObserver via NexusConfig.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 INexusLogger output by substring match. The observer is opt-in. When NexusConfig.Observer is null the SDK uses the internal no-op observer at zero overhead.

The interface

public interface IStreamObserver
{
    void OnConnected();
    void OnDisconnected(Exception? cause);
    void OnEvent(string name);
    void OnReconnectAttempt(int attempt);
    void OnFallback(string reason);
}

Inherit NoopStreamObserver to override only the hooks you care about:

public sealed class MyObserver : NoopStreamObserver
{
    private long _events;
    public long Events => Interlocked.Read(ref _events);
    public override void OnEvent(string name) => Interlocked.Increment(ref _events);
}

Hook semantics

Hook	Fires when	Argument
`OnConnected()`	`GET /v1/stream` returns `200 OK` and the SDK is ready to read events	none
`OnDisconnected(cause)`	An active stream connection ends - clean cancel, transport error, or server-initiated close	`null` for clean shutdown, the underlying exception otherwise
`OnEvent(name)`	A whitelisted SSE event arrives, before the SDK runs the event-triggered sync	event name string (e.g. `"config.updated"`)
`OnReconnectAttempt(n)`	The SDK is about to back off and retry after a transport error	1-based attempt counter (max 3 with current threshold)
`OnFallback(reason)`	The SDK switches to TTL polling or enters a `Retry-After`-driven reconnect wait (v0.3.1+)	`FallbackReason.MaxErrors` or `FallbackReason.RateLimited`

`OnFallback` reasons

public static class FallbackReason
{
    public const string MaxErrors   = "max-errors";
    public const string RateLimited = "rate-limited";
}

Constant	When
`FallbackReason.MaxErrors`	3 consecutive transport errors - backoff exhausted, the SDK gives up and switches to TTL polling for good
`FallbackReason.RateLimited`	server returned `429 Too Many Requests` (tier connection-limit hit) - see active-recovery vs terminate semantics below

`RateLimited` - active recovery vs terminate (v0.3.1+)

As of v0.3.1, FallbackReason.RateLimited no longer implies the stream is dead. It fires in both of these cases:

Active recovery - 429 with a parseable Retry-After header. The SDK fires OnFallback(FallbackReason.RateLimited), await Task.Delay-s the indicated duration (clamped [5 s, 5 min]), then reconnects automatically on the next loop iteration in RunStreamAsync. The episode does NOT increment the transport-failure counter. No action is required from the observer; a subsequent OnConnected() confirms the stream has resumed.
Terminate (legacy) - 429 with no parseable Retry-After. The SDK fires OnFallback(FallbackReason.RateLimited), closes the stream, and returns from RunStreamAsync. TTL polling takes over.

Threading contract

Observer methods are called synchronously from the SDK’s stream-reader Task. They MUST return promptly. The SDK does not protect against blocking observers and does not wrap the calls in Task.Run.

If your observer does anything substantial (network I/O, lock contention, disk writes), copy the argument and dispatch the work to your own pipeline before returning:

public sealed class SlowObserver : NoopStreamObserver
{
    private readonly Channel<string> _queue;
    public override void OnEvent(string name)
    {
        // Drop on overflow - applying backpressure to the SDK Task would
        // block sync() and stall reads.
        _queue.Writer.TryWrite(name);
    }
}

Counter pattern

public sealed class CounterObserver : NoopStreamObserver
{
    private long _events, _reconnects, _fallbacks;
    public long Events     => Interlocked.Read(ref _events);
    public long Reconnects => Interlocked.Read(ref _reconnects);
    public long Fallbacks  => Interlocked.Read(ref _fallbacks);

    public override void OnEvent(string _)            => Interlocked.Increment(ref _events);
    public override void OnReconnectAttempt(int _)    => Interlocked.Increment(ref _reconnects);
    public override void OnFallback(string _)         => Interlocked.Increment(ref _fallbacks);
}

var obs = new CounterObserver();
await using var client = await NexusClient.CreateAsync(new NexusConfig
{
    BaseUrl  = "...",
    ApiKey   = "...",
    Observer = obs,
});

Active-connection gauge pattern

public sealed class GaugeObserver : NoopStreamObserver
{
    public bool Connected { get; private set; }
    public override void OnConnected()                  => Connected = true;
    public override void OnDisconnected(Exception? _)   => Connected = false;
    public override void OnFallback(string _)           => Connected = false;
}

OnFallback is included because after a MaxErrors fallback the SDK will not reconnect - the gauge should stay false until you call ConnectStream() again on a new client. For RateLimited with Retry-After (v0.3.1+) the SDK reconnects on its own; the subsequent OnConnected() re-arms the gauge to true automatically.

Per-event-type counter

public sealed class PerEventObserver : NoopStreamObserver
{
    private readonly ConcurrentDictionary<string, long> _counts = new();
    public IReadOnlyDictionary<string, long> Counts => _counts;
    public override void OnEvent(string name) =>
        _counts.AddOrUpdate(name, 1, (_, n) => n + 1);
}

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

.NET SDK - Stream Observer

The interface

Hook semantics

`OnFallback` reasons

`RateLimited` - active recovery vs terminate (v0.3.1+)

Threading contract

Counter pattern

Active-connection gauge pattern

Per-event-type counter

​The interface

​Hook semantics

​OnFallback reasons

​RateLimited - active recovery vs terminate (v0.3.1+)

​Threading contract

​Counter pattern

​Active-connection gauge pattern

​Per-event-type counter

The interface

Hook semantics

`OnFallback` reasons

`RateLimited` - active recovery vs terminate (v0.3.1+)

Threading contract

Counter pattern

Active-connection gauge pattern

Per-event-type counter