GET /v1/stream connection open in a goroutine. 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.
Auto-start
NewClient starts RunStream automatically in a background goroutine. No manual call is needed.
The goroutine runs (reading the SSE stream and triggering syncs) until client.Close() is
called. It is deliberately not tied to the context passed to NewClient, which may be
request-scoped or carry a deadline; that context bounds only the initial sync.
In a typical service, defer client.Close() is the only shutdown call needed - it cancels the internal stream goroutine and cleans up file-type secret temp files.
What happens under the hood
- The SDK opens an HTTP streaming response to
<BaseURL>/v1/streamwithAccept: text/event-streamand eitherX-Nexus-API-Key: <key>orAuthorization: Bearer <session_jwt>(when WIF is enabled). - The server immediately sends a
resyncevent, which causes the SDK to callSync(ctx)once to align with the current state. - The connection stays open. Every change event triggers another full sync.
- The TTL keeps running alongside it as a safety net; while the stream is up, a refresh usually answers
304 Not Modified.
Config.HTTPClient - the SDK clones your client at construction time and zeros the Timeout. This is why you can use a familiar http.Client{Timeout: 10*time.Second} for /sync without that timeout killing the long-lived SSE connection. See Configuration.
Observer hooks
Pass aStreamObserver via Config.Observer to receive structured callbacks for every SSE lifecycle transition (OnConnected / OnDisconnected / OnEvent(name) / OnReconnectAttempt(n) / OnFallback(reason) / OnQuarantined(reason, expiresAt)). See Stream observer for the full contract.
auth_expiring control event (WIF)
When WIF is enabled, the backend emits an auth_expiring SSE control event ~5 minutes before the session JWT expires. The SDK reacts by triggering a non-blocking session refresh - it does NOT call /sync, and the event is NOT surfaced through OnEvent. When the server force-closes the stream at expiry, the SDK reconnects with the freshly-issued bearer.
Reconnection
A transport error (server restart, TCP drop, network blip) triggers a reconnect after 1 s, a second consecutive one after 2 s. The third consecutive transport error moves the stream to the reconnect schedule: the SDK waits the next interval and reconnects automatically. A connection that comes up in between starts the count and the backoff over. By default the schedule progresses 5 → 10 → 20 → 40 → 60 minutes (capped at 60 min on each subsequent fallback). TheObserver.OnFallback hook fires when the stream enters this state.
Configure a different schedule with SSEReconnectCooldown in Config:
Environment switched off
A403 with environment_disabled on the stream is not a transport failure, so no attempt is counted: the SDK fires OnFallback(FallbackReasonEnvironmentDisabled) and reconnects on the SSEReconnectCooldown schedule. It recovers on its own once the project switches the environment back on.
A 423 with service_locked on the stream indicates emergency lockdown: RunStream fires OnFallback(FallbackReasonServiceLocked) and OnDisconnected(ErrServiceLocked) and returns immediately without reconnecting. Background sync retries also halt until an explicit Sync succeeds after the lockdown is lifted.
429 Too Many Requests
Every project tier has a per-service stream connection limit:
Exceeding the limit returns
429 Too Many Requests, typically with a Retry-After header indicating when the client should try again.
Behaviour
The SDK applies a presence-conditional refinement onRetry-After:
- With a parseable
Retry-Afterheader (delta-seconds): the SDK parses the value, clamps it to[5 s, 5 min], firesOnFallback(FallbackReasonRateLimited)once for observability, then sleeps the indicated delay and reconnects automatically insideRunStream. The reconnect attempt does not increment the transport-failure counter -Retry-Afteris a cooperative throttle from the server, not a transport error, so it does not consume one of the three reconnect strikes that lead to themax-errorsfallback. - Without a parseable
Retry-Afterheader: the SDK firesOnFallback(FallbackReasonRateLimited)then schedules an SSE reconnect using theSSEReconnectCooldownschedule (default 5 → 10 → 20 → 40 → 60 minutes). No manual recovery is needed.
Retry-After: 1. The ceiling of 5 min prevents a malicious or accidental large value from stalling the live-update channel indefinitely.
ctx is cancelled during the wait, RunStream returns promptly instead of waiting for the full Retry-After window.
Idle detection
A dropped connection is not always a closed one. A load balancer or NAT reaping an idle flow, a route disappearing, a server wedged mid-stream: in each case the TCP connection stays open as far as the client is concerned and the read simply never returns anything. An SSE read has no deadline of its own, so the SDK applies one. The backend sends a keepalive comment every 30 seconds, which makes liveness directly observable. The SDK arms a timer forConfig.StreamIdleTimeout (default 90 s, three
missed keepalives) and resets it on every line - events and keepalives alike. If it
fires, the request is cancelled, the failure is reported to OnDisconnected as a
transport error, and the normal reconnect path runs.
StreamConnected() reports the current
state at any time.
SSE is always on
NewClient always starts the stream goroutine. Pure TTL-polling mode is not supported - the goroutine runs until Close() is called.
Lifecycle
client.Close() stops the stream goroutine, waits for any background sync in flight, and removes the file-type secret directory. Cancelling the context passed to NewClient does not stop it.
What events trigger a sync
The SDK does not apply event payloads directly to the cache - every event triggers a full re-sync that returns the current authoritative state. This avoids any drift between the SDK’s view and the backend.
