GET /v1/stream connection open in a background Task. Whenever the Nexus backend emits a change event (config.updated, flag.toggled, secret.created, resync, …), the SDK triggers an immediate full sync - so the cache is updated within milliseconds of the change, instead of waiting for the next TTL tick.
Enabling it
CallConnectStream() after the client is created (or rely on your DI factory to do it):
ConnectStream() is idempotent. Calling it twice is a no-op.
What happens under the hood
- The SDK opens an HTTP streaming response to
<BaseUrl>/v1/streamwithAccept: text/event-streamand theX-Nexus-API-Keyheader. - The server immediately sends a
resyncevent, which causes the SDK to callSyncAsync()once to align with the current state. - The connection stays open. Every change event triggers another full sync.
- While the stream is up, a read inside the TTL is served from the cache as usual; the TTL only matters when the stream is down. Then the client syncs once per TTL on its own until the stream is back, so values read through
IConfigurationor bound options keep refreshing too.
Reconnection
A transport error (server restart, TCP drop, network blip) triggers a reconnect after 1 s, a second consecutive one after 2 s. A successful connection starts the count and the backoff over, so drops separated by healthy connections never add up. AfterMaxStreamErrors consecutive transport errors the SDK does not give up permanently. Instead, it waits for the next interval in the SseReconnectCooldown schedule, syncing once per TTL meanwhile, and then retries SSE automatically. A failure right after the cooldown starts the backoff at 1 s again.
[5, 10, 20, 40, 60] minutes. After the cooldown elapses the SDK resets the transport-error counter and reconnects. Configure the schedule via SseReconnectCooldown in NexusConfig - see Configuration.
429 Too Many Requests
Every project tier has a per-service stream connection limit:
Behaviour
Retry-After parsing uses RetryConditionHeaderValue.Delta with a Date - DateTimeOffset.UtcNow fallback for the HTTP-date form.
The [5 s, 5 min] clamp is deliberate:
- 5 s floor - protects the SDK against a hostile or misconfigured server advertising
Retry-After: 0. - 5 min ceiling - caps the indefinite-stall risk.
Disabling SSE
PassenableStream: false to AddWestyx / builder.AddWestyxNexus, or set EnableStream = false
on NexusOptions, and the client syncs once per TTL instead, so IConfiguration and bound options
still refresh. A client you create yourself and never call ConnectStream() on refreshes when a read
finds the cache older than the TTL.
Lifecycle
The stream is bound to the client and runs until the client is disposed:Dispose() /
DisposeAsync() stops the background task before releasing the HTTP clients. There is no separate
call to stop it.
On the dependency-injection path the container owns the client, so the stream stops when the host
shuts down. A client you create yourself is disposed with await using, or registered with
services.AddSingleton(_ => client) so the container disposes it.
What events trigger a sync
IConfiguration live reload
When the SDK is wired into ASP.NET Core viaAddWestyx(...), the NexusConfigurationProvider calls IConfiguration.Reload() automatically after every sync that returns new data. This means:
IOptionsMonitor<T>.CurrentValueis immediately updated.IOptionsMonitor<T>.OnChange(...)callbacks fire without any manual intervention.- No application restart is required.
Stream deadlines
An SSE read has no deadline of its own, so the SDK applies two:
A deadline elapsing is treated as a transport error, so
OnDisconnected fires and the ordinary
reconnect path runs. Without them a connection reaped by a load balancer would block the read
indefinitely, and because the failure counter only advances on an exception there would be no
reconnect and no fallback.