When does the SDK hit the network
PHP-FPM per-request model
In PHP-FPM, each HTTP request boots a fresh PHP process. The in-memory cache is empty at the start of every request and
NexusClient::create makes a blocking network call on every request. The TTL has no effect across requests because there is no shared memory.Recommendation: register the client in a DI container with request scope (the default in Symfony/Laravel) so the cache is built once per request and all service classes share it within that request.ETag / 304 protocol
Every successful sync stores the server’sETag header. The next sync sends If-None-Match: <etag>. If nothing has changed:
304 - the expected answer whenever nothing has changed - keep serving real values.
Background sync errors
A TTL-triggered sync that fails for a transient reason - a network failure, a timeout, an unexpected status - does not surface:- The failure is logged as
nexus: refresh failed, serving the cached snapshotaterrorlevel. - The last known snapshot continues to be served.
- The next read retries automatically.
401 rejected credentials, 402 billing suspended, 404 service not found, and a WIF session that expired and could not be renewed (NexusSessionExpiredException).
A switched-off environment is neither: the key is still valid and nothing is wrong with the client, so the snapshot keeps serving, one warning is logged, and a refresh is attempted once every five minutes - retrying sooner cannot succeed until someone switches the environment back on. The first successful sync clears it.
The snapshot is never cleared
No sync failure empties the snapshot - not a rate limit, not a billing error, not a rejected key. What differs is whether the failure is served from the snapshot or raised: a transient one is served, and the four conditions listed above are raised. Once the condition clears, the next explicitsync() succeeds normally (background retries pause during a 423 service_locked lockdown until an explicit sync() succeeds).
Cache lifetime
The cache lives for the lifetime of theNexusClient object.
- FPM/HTTP workers - cache lives for one request (PHP process is recycled after the response).
- CLI daemons / queue workers - cache lives for the lifetime of the process.
File-type secrets
Secrets withtype = 'file' are materialised on every sync into a directory the client owns:
0700 by mkdir itself, and the files inside are created 0600 with O_EXCL - the mode is applied by the creating syscall, not by a chmod afterwards, which would leave a window where the secret sits on disk at the process umask. O_EXCL also means nothing already at the target path, a symlink included, can redirect the write.
The file name is a SHA-256 hash of the key and nothing in the path is derived from the value, so a path that ends up in a log line, an environment variable or a process listing never reveals the secret. Each client gets its own directory, so two clients holding the same secret - two PHP-FPM workers, for instance - never share a file.
Files are removed when the NexusClient is destroyed (__destruct); in FPM that is the end of each request. A process-exit hook clears anything left behind.
Diagnostics
At debug level the logger receives one record per sync:nexus: sync completed with the counts in its context, or nexus: sync not modified for a 304:
