Skip to main content
The SDK can hold a persistent 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 the X-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).
To run in pure TTL-polling mode:

What happens under the hood

  1. The SDK opens an HTTP streaming response via httpx.Client.stream("GET", ...) (or AsyncClient.stream for async) with Accept: text/event-stream and the X-Nexus-API-Key header.
  2. The server immediately sends a resync event, which causes the SDK to call sync() once to align with the current state.
  3. The connection stays open. Every change event triggers another full sync.
  4. While the stream is up, the TTL is at least 60 s - the stream carries every change - and it returns to ttl_seconds as 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’s on_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.
  • 403 with {"error":"environment_disabled"} - the project has switched the environment off. The stream calls on_fallback("environment-disabled"), logs a warning and retries on the cooldown schedule, without counting a transport failure.
  • 423 with {"error":"service_locked"} - the service is in emergency lockdown. The stream calls on_fallback("service-locked") then on_disconnected(NexusServiceLockedError("stream")) and exits immediately without reconnecting; background sync retries also halt until an explicit sync() succeeds.
Any other 403 is a transport error.
The reconnect schedule is configurable via 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 of Retry-After:
  • With a parseable Retry-After: the SDK parses the delta-seconds value, clamps it to [5, 300] seconds, fires observer.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 fires observer.on_fallback(FALLBACK_REASON_RATE_LIMITED) and schedules a reconnect using the sse_reconnect_cooldown schedule (default 5 - 10 - 20 - 40 - 60 minutes). TTL polling covers the gap during the cooldown, and the stream retries automatically.
Both clients implement the same logic using their respective sleep primitives:
  • AsyncNexusClient - await asyncio.wait_for(self._stream_stop.wait(), timeout=retry_after), so an in-flight close() / disconnect_stream() wakes the sleeping task immediately.
  • NexusClient (sync) - self._stream_stop.wait(timeout=retry_after) on a threading.Event, with the same prompt-shutdown property.

Disabling SSE at runtime

Reconnect later with 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. Calling close() stops it cleanly along with the rest of the client teardown. Always call close() on shutdown:

Inspecting status