Node.js SDK - SSE Live Updates

The SDK opens a persistent GET /v1/stream connection after the initial sync completes. Whenever the Nexus backend emits a change event (config.updated, flag.toggled, secret.created, resync, …), the SDK triggers an immediate full re-sync - so the in-memory cache is updated within milliseconds of a change, instead of waiting for the next TTL tick.

Auth

Node.js uses the X-Nexus-API-Key header on all endpoints, including /stream, via the native http/https modules. 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.)

What happens under the hood

The SDK opens an HTTP streaming response to <endpoint>/v1/stream 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 interval 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 three consecutive transport errors the SDK closes the stream and enters a reconnect cooldown. Reads continue to be served from the cache (propagation latency increases to the polling TTL), but the stream is not abandoned permanently. The SDK sleeps for the next interval in the sseReconnectCooldown schedule (default: 5 min, then 10, 20, 40, 60 min, staying at 60 min thereafter) and then automatically reopens /v1/stream.

client.streamStatus === 'fallback'   // SSE is in cooldown; TTL polling is active

The reconnect schedule is controlled by the sseReconnectCooldown config field (unit: minutes). The default schedule [5, 10, 20, 40, 60] means the first retry happens after 5 minutes, the second after 10, and so on - capping at 60 minutes for all subsequent attempts. Pass a single number for a fixed interval, or a custom array for a different progression. See Configuration for the full field reference.

`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

Exceeding the limit returns 429 Too Many Requests. Behaviour depends on whether the response carries a parseable Retry-After header.

Behaviour (v0.6.0+)

Quarantine 429 ({"error":"quarantined","reason":"...","expires_at":"..."} body):

The SDK reads the response body and detects the quarantine payload.
It fires observer.onQuarantined(reason, expiresAt) - NOT onFallback.
It schedules an automatic reconnect at expiresAt (minimum 5 s). This path does not count toward MAX_FAILURES.
When the timer fires, the SDK reopens /v1/stream normally.

Rate-limit 429 with a parseable Retry-After header (delta-seconds, e.g. Retry-After: 30):

The SDK parses the header and clamps the delay to the range [5 s, 5 min].
It fires observer.onFallback(FALLBACK_REASON_RATE_LIMITED) so dashboards and load-test tooling can record the episode.
It schedules a single setTimeout-based reconnect after the clamped delay. This path does not touch backoffMs or failedAttempts - Retry-After is cooperative back-pressure, not a transport error, so it does NOT count toward MAX_FAILURES.
When the timer fires, the SDK reopens /v1/stream normally.

Without a parseable Retry-After header:

The SDK fires observer.onFallback(FALLBACK_REASON_RATE_LIMITED).
client.streamStatus becomes 'fallback' and the stream is closed.
The SDK schedules a reconnect using the sseReconnectCooldown schedule (default: 5 min → 10 → 20 → 40 → 60 min). When the timer fires, the SDK reopens /v1/stream normally.

import {
  NexusClient,
  FALLBACK_REASON_RATE_LIMITED,
  type StreamObserver,
} from '@westyx-nexus/sdk-nodejs';

const observer: StreamObserver = {
  onFallback(reason) {
    if (reason === FALLBACK_REASON_RATE_LIMITED) {
      // fires on BOTH the cooperative-reconnect path AND the terminate path
      metrics.increment('nexus.sse.rate_limited');
    }
  },
};

const client = await NexusClient.create({
  endpoint: 'https://...',
  apiKey:   'wxs_...',
  streamObserver: observer,
});

Disabling SSE

client.disconnectStream();

Useful if you want to react to a “go offline” / “reduce traffic” signal without disposing the whole client. Reconnect later with client.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 stream is bound to the NexusClient instance. client.close() cancels the connection along with the polling timer and the temp-file cleanup. Always call close() on shutdown:

process.on('SIGTERM', async () => {
  await client.close();
  process.exit(0);
});

Inspecting status

client.streamStatus    // 'connected' | 'fallback' | 'disconnected'

Value	Meaning
`'connected'`	The SSE stream is up and pushing events
`'fallback'`	3 consecutive transport errors; SSE is in reconnect cooldown and TTL polling is active
`'disconnected'`	Stream is not active (either never started or `disconnectStream()` was called)

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Node.js SDK - SSE Live Updates

Auth

What happens under the hood

Reconnection

`429 Too Many Requests`

Behaviour (v0.6.0+)

Disabling SSE

What events trigger a sync

Lifecycle

Inspecting status

​Auth

​What happens under the hood

​Reconnection

​429 Too Many Requests

​Behaviour (v0.6.0+)

​Disabling SSE

​What events trigger a sync

​Lifecycle

​Inspecting status

Auth

What happens under the hood

Reconnection

`429 Too Many Requests`

Behaviour (v0.6.0+)

Disabling SSE

What events trigger a sync

Lifecycle

Inspecting status