Skip to main content
The SDK can hold a persistent 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

Call ConnectStream() 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

  1. The SDK opens an HTTP streaming response to <BaseUrl>/v1/stream with Accept: text/event-stream and the X-Nexus-API-Key header.
  2. The server immediately sends a resync event, which causes the SDK to call SyncAsync() once to align with the current state.
  3. The connection stays open. Every change event triggers another full sync.
  4. 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 IConfiguration or 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. After MaxStreamErrors 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.
Every wait is lengthened by up to 20% at random, so a fleet that lost its connections together does not reconnect in lockstep. The reconnect schedule defaults to [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

Pass enableStream: 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 via AddWestyx(...), the NexusConfigurationProvider calls IConfiguration.Reload() automatically after every sync that returns new data. This means:
  • IOptionsMonitor<T>.CurrentValue is immediately updated.
  • IOptionsMonitor<T>.OnChange(...) callbacks fire without any manual intervention.
  • No application restart is required.
The reload fires only when new data arrives (HTTP 200 with a changed payload). A 304 Not Modified response does not trigger a reload. See ASP.NET Core configuration for the full setup guide.

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.