Spring Boot SDK - SSE Live Updates

The SDK can hold 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 triggers an immediate full sync - so the cache is updated within milliseconds of the change, instead of waiting for the next TTL tick.

Auth

Java uses the X-Nexus-API-Key header on all endpoints, including /stream, via Java 11’s stdlib HttpClient. The key is never passed as a ?key= query parameter. (All Nexus SDKs send the key in this header - the browser SDKs do too, using fetch-based streaming rather than the EventSource API.)

Enabling it

The auto-configuration calls connectStream() automatically after the initial sync (controlled by nexus.stream):

nexus:
  base-url: ...
  api-key:  ...
  stream:   true   # default - explicit here for clarity

If you want to run in pure TTL-polling mode, set:

nexus:
  stream: false

What happens under the hood

The SDK opens an HTTP streaming response via HttpClient.send(...) with Accept: text/event-stream and the X-Nexus-API-Key header.
The server immediately sends a resync event, which causes the SDK to call sync() once to align with the current state.
The connection stays open. Every change event triggers another full sync.
While the stream is up, the polling TTL is bumped to 60 s as a safety net.

Reconnection

Any transport error (server restart, TCP drop, network blip) triggers a reconnect with exponential backoff: 1s - 2s - 4s - 8s - 16s - 30s (capped at 30s). After MAX_STREAM_ERRORS consecutive transport errors the SDK does not fall back permanently. Instead it sleeps according to the sseReconnectCooldown schedule and then retries SSE automatically.

nexus: SSE transport error (attempt 1/3)
nexus: SSE transport error (attempt 2/3)
nexus: SSE max errors reached - sleeping 5 min before next reconnect attempt

You can detect the cooldown state via client.isStreamConnected() - it returns false while the SDK is sleeping between reconnect attempts. The reconnect cooldown schedule defaults to [5, 10, 20, 40, 60] minutes and can be tuned with the sseReconnectCooldown config option (see Configuration).

`429 Too Many Requests`

Every project tier has a per-service stream connection limit:

Tier	Connections
`free`	5
`xs`	10
`s`	25
`m`	50
`l`	150
`xl`	500

Behaviour (v0.6.0+)

The SDK’s 429 handling is presence-conditional on Retry-After:

With a parseable Retry-After header - the SDK parses the value, clamps to [5 s, 5 min], fires observer.onFallback("rate-limited") so dashboards can record the rate-limit episode, then Thread.sleeps for the clamped delay (interrupt-aware) and continues the reconnect loop. The 429 does NOT count toward MAX_STREAM_ERRORS.
Without a parseable Retry-After header - the SDK fires observer.onFallback("rate-limited") and schedules a reconnect using the sseReconnectCooldown schedule (default 5 - 10 - 20 - 40 - 60 minutes). SSE is retried automatically after the cooldown; there is no permanent fallback.

No consumer-side code change is required to benefit from the new behaviour - the upgrade is purely internal to NexusClient. Existing NexusStreamObserver implementations will simply observe more onFallback("rate-limited") callbacks during rate-limit episodes, each followed by an automatic reconnect rather than a permanent fallback.

Disabling SSE at runtime

@Service
public class NexusOps {

    private final NexusClient nexus;
    NexusOps(NexusClient nexus) { this.nexus = nexus; }

    public void goOffline() {
        nexus.disconnectStream();
    }

    public void goOnline() {
        nexus.connectStream();
    }
}

What events trigger a sync

Event	secret keys	public keys
`resync`	yes	yes
`config.created` / `.updated` / `.deleted`	yes	yes
`flag.created` / `.updated` / `.toggled` / `.deleted`	yes	yes
`secret.created` / `.updated` / `.deleted`	yes	filtered server-side

Lifecycle

The SSE thread is bound to the NexusClient bean. The auto-configuration registers destroyMethod = "close", so the thread is stopped cleanly when the Spring context shuts down.

Inspecting status

boolean connected = client.isStreamConnected();

Value	Meaning
`true`	The SSE stream is up and pushing events
`false`	Stream is not active - either never started (`stream=false`), sleeping in the `sseReconnectCooldown` schedule before a retry, or `disconnectStream()` was called

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Spring Boot SDK - SSE Live Updates

Auth

Enabling it

What happens under the hood

Reconnection

`429 Too Many Requests`

Behaviour (v0.6.0+)

Disabling SSE at runtime

What events trigger a sync

Lifecycle

Inspecting status

​Auth

​Enabling it

​What happens under the hood

​Reconnection

​429 Too Many Requests

​Behaviour (v0.6.0+)

​Disabling SSE at runtime

​What events trigger a sync

​Lifecycle

​Inspecting status

Auth

Enabling it

What happens under the hood

Reconnection

`429 Too Many Requests`

Behaviour (v0.6.0+)

Disabling SSE at runtime

What events trigger a sync

Lifecycle

Inspecting status