Skip to main content
Pass a nexus.StreamObserver via Config.Observer 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 Logger output by substring match. The observer is opt-in. When Config.Observer == nil the SDK uses NoopStreamObserver at zero overhead.

The interface

Embed nexus.NoopStreamObserver to override only the hooks you care about:

Hook semantics

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

A successful connection starts the failure count and the backoff over, so failures before it never add up to a fallback. A quarantine is not a fallback: it calls OnQuarantined instead of OnFallback. The exported FallbackReasonQuarantined ("quarantined") is never passed to OnFallback; it exists so an application can tag its own log lines for a quarantine with the same vocabulary.

FallbackReasonRateLimited - recovery

FallbackReasonRateLimited is dispatched in both of the following situations:
  • No Retry-After - the server returned 429 without a parseable Retry-After header. The SDK closes the stream, TTL polling carries on, and the stream reconnects on the SSEReconnectCooldown schedule.
  • Retry-After present - the server returned 429 with a parseable Retry-After header. The SDK fires OnFallback("rate-limited") for visibility, then sleeps the indicated delay (clamped [5 s, 5 min]) and reconnects automatically. RunStream does NOT return, the transport-failure counter is NOT incremented, and the stream resumes without intervention.
In both cases a later OnConnected() confirms the stream is back.

OnQuarantined - quarantine semantics

OnQuarantined(reason string, expiresAt time.Time) fires when the backend returns 429 Too Many Requests with a structured quarantine body:
SDK behaviour while quarantined:
  • Background sync (ensureFresh) is skipped entirely - no requests are sent to the backend.
  • The in-memory cache continues to be served for all reads (GetConfig, GetSecret, GetFlag).
  • The quarantine state clears automatically when expiresAt passes.

Threading contract

Observer methods are called synchronously from the SDK’s own goroutine. They MUST return promptly. The SDK does not protect against blocking observers.A panic, by contrast, is contained. Every call goes through one guard that recovers, logs the hook name and a stack trace, and carries on; the stream stays up and the hook is skipped for that event. This matters more in Go than the equivalent guard does elsewhere: a panic can only be recovered on the goroutine that raised it, and these calls happen on a goroutine the SDK started - so without the guard a panic in your callback would take the whole process down, with no opportunity for the application to intervene.
If your observer does anything substantial (network I/O, mutex contention, disk writes), copy the argument and dispatch the work to your own goroutine before returning:

Counter pattern

The most common use - counting events for a dashboard or load-test report:

Active-connection gauge pattern

Maintain a live “is the SDK connected” gauge:
OnFallback is included because the stream is not delivering while it waits out a fallback; the SDK reconnects on its own, and the next OnConnected flips the gauge back to true.

Per-event-type counter

Independence from Logger

The observer is independent of Logger. The two are complementary:
  • Logger carries human-readable text for operators ("nexus: SSE stream connected").
  • StreamObserver carries structured metrics for tooling.
A consumer can set both, neither, or just one. Setting only the observer is the right choice when you don’t want any text output from the SDK.

Compatibility note

Prefer the observer over matching on log output to count reconnects or fallbacks: message wording is not a stable contract and may change between releases, while the observer’s hook names and reason codes are.