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
Enabling it
CallconnectStream() after NexusClient::create returns:
$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
- 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()to align with the current state. - The connection stays open. Every change event triggers another full sync.
- The connection carries two deadlines:
sseConnectTimeout(10 s) bounds establishing it, andsseIdleTimeout(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.
$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 callconnectStream(). 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
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.