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
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:
resyncconfig.created/config.updated/config.deletedflag.created/flag.updated/flag.toggled/flag.deletedsecret.created/secret.updated/secret.deleted
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 parseableRetry-Afterheader. The SDK closes the stream, TTL polling carries on, and the stream reconnects on theSSEReconnectCooldownschedule. Retry-Afterpresent - the server returned 429 with a parseableRetry-Afterheader. The SDK firesOnFallback("rate-limited")for visibility, then sleeps the indicated delay (clamped[5 s, 5 min]) and reconnects automatically.RunStreamdoes NOT return, the transport-failure counter is NOT incremented, and the stream resumes without intervention.
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:
- 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
expiresAtpasses.
Threading contract
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:
Loggercarries human-readable text for operators ("nexus: SSE stream connected").StreamObservercarries structured metrics for tooling.
