Skip to main content
The SDK holds a persistent GET /v1/stream connection open in a daemon thread. Whenever the Nexus backend emits a change event (config.updated, flag.toggled, secret.created, resync, …), the SDK runs an immediate full sync - so the cache is updated within milliseconds of the change, instead of waiting for the next TTL.

Auth

The stream authenticates like every other request: the X-Nexus-API-Key header, or Authorization: Bearer <session> with WIF. The key is never sent as a query parameter. Before each connection attempt a WIF session close to expiry is refreshed.

Enabling it

The auto-configuration calls connectStream() after the initial sync unless the stream is switched off:
A plain client starts it with client.connectStream().

What happens under the hood

  1. The SDK opens the stream with Accept: text/event-stream on its own stream HttpClient, so a short timeout on the client used for other requests cannot cut it.
  2. The server sends a resync event at once, so the cache is aligned with the current state.
  3. The connection stays open. Every change event triggers another full sync; an auth_expiring event refreshes the WIF session ahead of the server closing the stream.
  4. While the stream is connected, the background refresh runs no more often than once a minute - the stream delivers the changes.

Idle deadline

The server sends a keepalive comment every 30 seconds. If the connection delivers nothing at all - not even a keepalive - for nexus.stream-idle-timeout (default 90 s), the SDK treats it as dead, closes it and reconnects. A half-open connection, where the network path was lost without either side seeing a close, therefore ends in a reconnect instead of a read that never returns.

Reconnection

A transport error - a server restart, a dropped connection, the idle deadline, an unexpected status - reconnects with exponential backoff: 1 s, 2 s, 4 s, 8 s, 16 s, then 30 s. After 3 consecutive transport errors the SDK fires onFallback("max-errors"), relies on TTL polling, and waits out the sseReconnectCooldown schedule - default [5, 10, 20, 40, 60] minutes, the last entry repeating - before trying the stream again. For transport errors it never gives up on the stream for good; HTTP 423 service_locked (emergency lockdown) stops the stream immediately (onFallback("service-locked")). A successful connection starts the failure count and the backoff afresh, and so does the cooldown: drops hours apart never add up to a fallback, and the attempt after a cooldown waits 1 s again.
client.isStreamConnected() returns false from the moment a connected stream ends, through the backoff and the cooldown, until the next connection succeeds.

Environment switched off

A 403 with environment_disabled on the stream is not a transport failure, so no attempt is counted: the SDK fires onFallback("environment-disabled") and reconnects on the sseReconnectCooldown schedule. Polling is held too, and the first successful sync - once the environment is switched back on - lifts both.

429 Too Many Requests

Every project tier has a per-service stream connection limit: Exceeding the limit returns 429 Too Many Requests. A 429 is a cooperative throttle, not a transport error, so it is not counted toward the three failures:
  • With a parseable Retry-After header (delta-seconds), the SDK fires onFallback("rate-limited"), sleeps the value clamped to [5 s, 5 min], and reconnects.
  • Without one, it fires onFallback("rate-limited") and waits the next sseReconnectCooldown step before reconnecting.
  • With a quarantine body ({"error":"quarantined",...}), it fires onQuarantined(reason, expiresAt), sleeps until the quarantine ends (at most five minutes at a time), and reconnects.

Disabling the stream at runtime

disconnectStream() closes the connection, so the stream thread ends at once even when the server is silent.

What events trigger a sync

Lifecycle

The stream thread belongs to the NexusClient bean. The auto-configuration registers destroyMethod = "close", so the stream stops when the Spring context shuts down.