Skip to main content
Every public method and property on NexusClient. The read methods - GetConfig, GetAllConfigs, GetSecret, GetSecretFilePath, GetFlag, FindFlag, GetAllFlags - answer from the in-memory cache and never wait on the network. CreateAsync, SyncAsync, EvaluateABAsync and the three write methods make a request.

Construction

NexusClient.CreateAsync(NexusConfig, CancellationToken = default)

Creates a client and runs a blocking initial sync. The returned Task<NexusClient> resolves only after the first sync completes.

Configs

(JsonElement? value, bool found) GetConfig(string key)

Returns the resolved config value as a JsonElement (the wire-level JSON node), and a found boolean.
The value is whatever JSON shape the server stored - string, number, boolean, array, or object.

IReadOnlyDictionary<string, JsonElement> GetAllConfigs()

Read-only map of every config key and value in the cache. It is the same instance until the next sync replaces the snapshot, and does not change when the cache does - read it again after a sync. Public-key clients receive every config and flag the service exposes - visibility is decided server-side, with no per-entry field for a client to reason about.

Feature flags

bool GetFlag(string key, bool defaultValue = false)

Returns the is_active state of a flag, or defaultValue when the key is absent.

bool? FindFlag(string key)

Returns the is_active state of a flag, or null when the flag is not in the cache at all - the case GetFlag folds into its default.

IReadOnlyDictionary<string, bool> GetAllFlags()

Read-only map of every flag key and its is_active state. It is the same instance until the next sync replaces the snapshot, and does not change when the cache does - read it again after a sync.

AB Testing

Task<IReadOnlyDictionary<string, bool>> EvaluateABAsync(IEnumerable<string> keys, string userId, IDictionary<string, string>? attributes, CancellationToken = default)

Evaluates one or more feature flags against the AB Testing add-on. Unlike GetFlag, this method always makes a network call.
attributes may be null - it is serialised as an empty object. Values are strings because cohort rules compare strings: format a number at the call site (age.ToString(CultureInfo.InvariantCulture)) and you know exactly what the rule is matched against.

Secrets (secret key only)

string GetSecret(string key)

Returns the plaintext value of a secret. It reads the in-memory cache and makes no network call, which is why it returns a string rather than a Task<string>; it pairs with GetSecretFilePath, which is synchronous for the same reason.

string? GetSecretFilePath(string key)

Returns the absolute filesystem path of a materialised file-type secret, or null when the key is unknown or refers to a text-type secret. Always non-blocking.

File-type secrets

file-type secrets are materialised during every sync into a directory the client owns:
The directory is created 0700 with an unguessable name, and each file inside it is created exclusively at 0600 with the mode applied by the creating call rather than by a chmod afterwards. Both filename components are the first 16 hex characters of a SHA-256 digest, so neither the key name nor the value appears in the path. Because the value hash is part of the name, the path changes whenever the value changes - a consumer can detect a rotation by polling GetSecretFilePath. The directory component is per client instance, so two clients holding the same secret get separate files and one client’s disposal cannot remove the other’s; do not persist the path beyond the client’s lifetime. Files for secrets that disappear from a sync, or switch back to text, are deleted. The directory and everything in it are removed by Dispose() / DisposeAsync(), and a process-exit hook removes them if the process ends without disposing. On Windows there is no 0600 equivalent: the directory and its files inherit the user-scoped temp ACL.

Secrets - write (secret key only)

Task SetSecretAsync(string key, string value, CancellationToken = default)

Creates or updates a secret with the given key and value.

Task DeleteSecretAsync(string key, CancellationToken = default)

Deletes a secret by key.

Task DeleteSecretVersionAsync(string key, int version, CancellationToken = default)

Deletes a specific version of a secret.

Disposing the client

Always dispose the client via Dispose() / DisposeAsync() (or await using) on shutdown. Disposal:
  • Stops the SSE background task, if ConnectStream() was called.
  • Deletes every temp file written for file-type secrets.
  • Releases the internally-managed HttpClient instances.

Metadata

Sync / lifecycle

Task SyncAsync(CancellationToken = default)

Forces a sync now, bypassing the TTL. Atomically replaces the cache. ETag / If-None-Match is used automatically; a 304 resets the TTL without downloading data. Rarely needed.

void ConnectStream()

Starts the SSE live-update background task. Calling it more than once is a no-op. The task runs until the client is disposed. See SSE live updates.

Dispose() / DisposeAsync()

Stops the SSE background task, deletes any file-type secret temp files, and releases the internally-managed HttpClient. Always call (or use await using) before the application exits.