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: theX-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 callsconnectStream() after the initial sync unless the stream is switched off:
client.connectStream().
What happens under the hood
- The SDK opens the stream with
Accept: text/event-streamon its own streamHttpClient, so a short timeout on the client used for other requests cannot cut it. - The server sends a
resyncevent at once, so the cache is aligned with the current state. - The connection stays open. Every change event triggers another full sync; an
auth_expiringevent refreshes the WIF session ahead of the server closing the stream. - 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 - fornexus.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 firesonFallback("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
A403 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-Afterheader (delta-seconds), the SDK firesonFallback("rate-limited"), sleeps the value clamped to [5 s, 5 min], and reconnects. - Without one, it fires
onFallback("rate-limited")and waits the nextsseReconnectCooldownstep before reconnecting. - With a quarantine body (
{"error":"quarantined",...}), it firesonQuarantined(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 theNexusClient bean. The auto-configuration registers destroyMethod = "close", so the stream stops when the Spring context shuts down.