Node.js SDK - Stream Observer

Pass a StreamObserver via NexusConfig.streamObserver to receive structured callbacks for every SSE lifecycle transition. The observer is the canonical way to wire SDK state into ops dashboards, custom telemetry, or load-test tooling - far more reliable than scraping console output by substring match. The observer is opt-in. When NexusConfig.streamObserver is undefined the SDK uses NOOP_STREAM_OBSERVER at zero overhead.

The interface

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

interface StreamObserver {
  onConnected?(): void;
  onDisconnected?(cause: unknown | null): void;
  onEvent?(name: string): void;
  onReconnectAttempt?(attempt: number): void;
  onFallback?(reason: string): void;
  onQuarantined?(reason: string, expiresAt: Date): void;  // v0.4.0+
}

Every method is optional - the SDK calls only the ones you set. You can write { onEvent: (n) => count(n) } and ignore the rest.

Hook semantics

Hook	Fires when	Argument
`onConnected()`	`GET /v1/stream` returns `200 OK` and the SDK is ready to read events	none
`onDisconnected(cause)`	An active stream connection ends - clean disconnect, transport error, or server-initiated close	`null` for clean shutdown, the underlying error otherwise
`onEvent(name)`	A whitelisted SSE event arrives, before the SDK runs the event-triggered sync	event name string (e.g. `"config.updated"`)
`onReconnectAttempt(n)`	The SDK is about to back off and retry after a transport error	1-based attempt counter (max 3 with current threshold)
`onFallback(reason)`	The SDK gives up and switches to TTL polling	`FALLBACK_REASON_MAX_ERRORS` or `FALLBACK_REASON_RATE_LIMITED`
`onQuarantined(reason, expiresAt)` (v0.4.0)	The stream received a quarantine `429` - the SDK will sleep until `expiresAt` and reconnect	server-supplied reason string + expiry `Date`

What counts as a “whitelisted event”

onEvent fires only for events on the SDK’s documented event-type list:

resync
config.created / config.updated / config.deleted
flag.created / flag.updated / flag.toggled / flag.deleted
secret.created / secret.updated / secret.deleted

Unknown events (or the WIF auth_expiring control event) do NOT trigger onEvent.

`onFallback` reasons

import {
  FALLBACK_REASON_MAX_ERRORS,
  FALLBACK_REASON_RATE_LIMITED,
} from '@westyx-nexus/sdk-nodejs';

Constant	When
`'max-errors'`	3 consecutive transport errors - backoff exhausted, the SDK gives up
`'rate-limited'`	server returned `429 Too Many Requests` (tier connection-limit hit) - see dual-semantics note below

`FALLBACK_REASON_RATE_LIMITED` - dual semantics (v0.3.1+)

As of v0.3.1, 'rate-limited' fires in both of the following situations:

Terminate case (no Retry-After) - the server returned 429 without a parseable Retry-After header. The SDK closes the stream, sets client.streamStatus to 'fallback', and does NOT reconnect. This is the legacy behaviour, preserved as-is.
Cooperative-reconnect case (with Retry-After) - the server returned 429 with a parseable Retry-After header (clamped to [5 s, 5 min]). The SDK fires onFallback('rate-limited') for the metric, then schedules an automatic reconnect after the indicated delay. The Retry-After delay does NOT count toward MAX_FAILURES.

Quarantine 429 (v0.4.0+, body {"error":"quarantined",...}) does NOT fire onFallback - it fires onQuarantined instead. The stream reconnects automatically at expiresAt.

In other words, onFallback('rate-limited') is per rate-limit episode - not a one-shot “the SDK has given up” signal. If you need to distinguish the two cases, inspect client.streamStatus shortly after the callback returns: it will be 'fallback' in the terminate case and either 'connected' or transitioning back to 'connected' in the cooperative-reconnect case.

const observer: StreamObserver = {
  onFallback(reason) {
    if (reason === FALLBACK_REASON_RATE_LIMITED) {
      metrics.increment('nexus.sse.rate_limited');
      // gauge update - defer one tick so the SDK has finished its state
      // transition before we read streamStatus
      setImmediate(() => {
        gauge.set('nexus.sse.connected', client.streamStatus === 'connected' ? 1 : 0);
      });
    }
  },
};

Threading contract

Observer methods are called synchronously from the SDK’s stream-reader event loop. They MUST return promptly.

If your observer does anything substantial (network I/O, mutex contention, disk writes), copy the argument and dispatch the work via setImmediate, queueMicrotask, or your own queue before returning:

const queue: string[] = [];
const observer: StreamObserver = {
  onEvent(name) {
    queue.push(name);
    setImmediate(processQueue);
  },
};

Counter pattern

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

const counters = { events: 0, reconnects: 0, fallbacks: 0 };
const observer: StreamObserver = {
  onEvent: () => counters.events++,
  onReconnectAttempt: () => counters.reconnects++,
  onFallback: () => counters.fallbacks++,
};

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

// later ...
console.log('SSE:', counters);

Active-connection gauge pattern

let connected = false;
const observer: StreamObserver = {
  onConnected:    () => { connected = true; },
  onDisconnected: () => { connected = false; },
  onFallback:     () => { connected = false; },
};

onFallback is included because in the terminate cases the SDK will not reconnect on its own - the gauge should stay false until you call connectStream() again. In the v0.3.1+ cooperative rate-limited path (server sent a Retry-After), the SDK will reconnect automatically and onConnected will fire again when the stream comes back.

Independence from the logger

The observer is independent of any logging output. The two are complementary:

The SDK’s console.* output carries human-readable text for operators.
StreamObserver carries structured metrics for tooling.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Node.js SDK - Stream Observer

The interface

Hook semantics

What counts as a “whitelisted event”

`onFallback` reasons

`FALLBACK_REASON_RATE_LIMITED` - dual semantics (v0.3.1+)

Threading contract

Counter pattern

Active-connection gauge pattern

Independence from the logger

​The interface

​Hook semantics

​What counts as a “whitelisted event”

​onFallback reasons

​FALLBACK_REASON_RATE_LIMITED - dual semantics (v0.3.1+)

​Threading contract

​Counter pattern

​Active-connection gauge pattern

​Independence from the logger

The interface

Hook semantics

What counts as a “whitelisted event”

`onFallback` reasons

`FALLBACK_REASON_RATE_LIMITED` - dual semantics (v0.3.1+)

Threading contract

Counter pattern

Active-connection gauge pattern

Independence from the logger