Skip to main content
The SDK can hold a persistent GET /v1/stream connection open. 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.

FPM warning

connectStream() blocks the calling PHP process indefinitely. Never call it from a PHP-FPM request handler. Blocking a worker means it cannot serve any further HTTP requests until the method returns (which may be never). Use connectStream() only in long-running CLI scripts, queue consumers (php artisan queue:work, php bin/console messenger:consume), or Swoole/ReactPHP-based workers.

Enabling it

Call connectStream() after NexusClient::create returns:
When $maxErrors consecutive errors occur, the SDK falls back to TTL polling for the reconnect cooldown, then retries the stream on its own. The process never needs to be restarted for this to work.

Custom max errors

What happens under the hood

  1. The SDK opens an HTTP streaming response to <baseUrl>/v1/stream with Accept: text/event-stream and either X-Nexus-API-Key: <key> or Authorization: Bearer <session_jwt> (when WIF is enabled).
  2. The server immediately sends a resync event, which causes the SDK to call sync() to align with the current state.
  3. The connection stays open. Every change event triggers another full sync.
  4. The connection carries two deadlines: sseConnectTimeout (10 s) bounds establishing it, and sseIdleTimeout (60 s) bounds the time between bytes. Every byte resets the idle deadline, keepalive comments included, so a connection silently dropped by a load balancer is detected and reconnected instead of reading as healthy.

Events table

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.

Reconnection and backoff

A connection that ends - a server restart, a TCP drop, the idle deadline - is reconnected. When it stayed up for at least 30 seconds, the reconnect is immediate and the error count and the backoff start again, however it ended. A connection that fails, or ends within 30 seconds of connecting, counts as an error and waits before the next attempt: The 30-second rule is what keeps a flapping endpoint - one that accepts the connection and drops it at once - from being reconnected in a tight loop: it backs off and falls back to polling like any other failure.

Max errors behaviour

After $maxErrors consecutive errors, the SDK falls back to TTL polling and enters the reconnect cooldown schedule. It then retries SSE automatically - no manual restart or wrapper loop is needed:
  • Your application is never notified; reads continue to be served from the cache during the cooldown.
  • The only visible effect during the cooldown is that propagation latency increases from milliseconds to the TTL.
  • Once the cooldown elapses, the SDK re-opens the stream and changes propagate within milliseconds again.
The reconnect cooldown schedule is controlled by $sseReconnectCooldown. The default schedule is [5, 10, 20, 40, 60] minutes - each successive fallback waits longer before retrying. Pass an int for a fixed interval or an array for a custom schedule (the last value is reused indefinitely).

auth_expiring event (WIF)

When WIF is enabled, the backend emits an auth_expiring event about 5 minutes before the session expires, and the SDK refreshes the session then. A refresh that fails while the session is still valid is logged as a warning and the stream stays open; the next request tries again. When the server closes the stream at expiry, the SDK reconnects with the new session.

Refusals

A refused stream raises the same exception a request would - see Error handling - and the loop treats them by kind:

Disabling SSE

Just don’t call connectStream(). The SDK runs in pure TTL-polling mode. For most PHP-FPM applications this is the correct choice - the TTL is short enough that changes appear within one polling interval.

Laravel queue worker example

Run with php artisan nexus:daemon under a process supervisor (Supervisor, systemd) that restarts it if it ends - which it only does on a rejected key or a suspended account.