GET /v1/stream connection open in the background. 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.
Both NexusClient and AsyncNexusClient support SSE; they just use different concurrency primitives (a daemon thread vs an asyncio.Task).
Auth
Python uses theX-Nexus-API-Key header on all endpoints, including /stream, via httpx’s streaming support. 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.)
Enabling it
The stream starts automatically after the initial sync (stream=True is the default in NexusConfig).
What happens under the hood
- The SDK opens an HTTP streaming response via
httpx.Client.stream("GET", ...)(orAsyncClient.streamfor async) withAccept: text/event-streamand theX-Nexus-API-Keyheader. - The server immediately sends a
resyncevent, which causes the SDK to callsync()once to align with the current state. - The connection stays open. Every change event triggers another full sync.
- While the stream is up, the TTL is at least 60 s - the stream carries every change - and it returns to
ttl_secondsas soon as the stream is not connected.
Liveness deadline
The stream carries an idle deadline (stream_idle_timeout, default 90 s): the longest silence - no events, no keepalives - before the connection is declared dead. The server sends a : ping keepalive comment every 30 s, and every received line resets the deadline, so a healthy stream is never torn down. A connection silently reaped by a load balancer, which would otherwise block the read forever while looking healthy, surfaces as a transport error and goes through the normal reconnect path below.
Reconnection
A transport error (server restart, TCP drop, network blip, an expired liveness deadline, a non-200 response) triggers a reconnect after 1 s, a second consecutive one after 2 s. A successful connection starts the count and the backoff over, so drops separated by healthy connections never add up. After three consecutive transport errors the SDK does not fall back permanently. It calls the observer’son_fallback("max-errors"), logs it, sleeps the sse_reconnect_cooldown schedule (default 5 - 10 - 20 - 40 - 60 minutes, staying at 60 minutes thereafter) and then retries the SSE connection automatically; stream_connected stays False meanwhile. A failure right after the cooldown starts the backoff at 1 s again, and the schedule position resets on a successful connect.
Refusals that retrying soon cannot fix
401- the key or the session was rejected. The stream waits out the cooldown schedule (on_fallback("max-errors")) and tries again; with WIF, it refreshes the session before the next attempt.403with{"error":"environment_disabled"}- the project has switched the environment off. The stream callson_fallback("environment-disabled"), logs a warning and retries on the cooldown schedule, without counting a transport failure.423with{"error":"service_locked"}- the service is in emergency lockdown. The stream callson_fallback("service-locked")thenon_disconnected(NexusServiceLockedError("stream"))and exits immediately without reconnecting; background sync retries also halt until an explicitsync()succeeds.
403 is a transport error.
sse_reconnect_cooldown in NexusConfig. See Configuration for details.
429 Too Many Requests
Every project tier has a per-service stream connection limit:
Behaviour
The Python SDK handles 429 with presence-conditional refinement ofRetry-After:
- With a parseable
Retry-After: the SDK parses the delta-seconds value, clamps it to[5, 300]seconds, firesobserver.on_fallback(FALLBACK_REASON_RATE_LIMITED), sleeps the indicated delay on the stream’s stop event, and then resumes the reconnect loop. The 429 does not count toward_MAX_STREAM_ERRORS. - Without a parseable
Retry-After: the SDK firesobserver.on_fallback(FALLBACK_REASON_RATE_LIMITED)and schedules a reconnect using thesse_reconnect_cooldownschedule (default 5 - 10 - 20 - 40 - 60 minutes). TTL polling covers the gap during the cooldown, and the stream retries automatically.
AsyncNexusClient-await asyncio.wait_for(self._stream_stop.wait(), timeout=retry_after), so an in-flightclose()/disconnect_stream()wakes the sleeping task immediately.NexusClient(sync) -self._stream_stop.wait(timeout=retry_after)on athreading.Event, with the same prompt-shutdown property.
Disabling SSE at runtime
connect_stream() (sync) or nexus.connect_stream() (async).
What events trigger a sync
Lifecycle
The SSE thread (sync) or task (async) is bound to the client. Callingclose() stops it cleanly along with the rest of the client teardown. Always call close() on shutdown:
