Skip to main content
The public API lives in dev.westyx.nexus (the client, its configuration and exceptions), dev.westyx.nexus.json (JsonValue and the codecs) and dev.westyx.nexus.spring (the auto-configuration). The auto-configuration creates the NexusClient bean and starts the stream - for most applications the read methods (getConfig, getFlag, getSecret) are the entire surface.

Construction

NexusClient.create(NexusConfig config)

Creates a client and runs a blocking initial sync. The auto-configuration calls it; call it yourself outside Spring or in a bean of your own.
NexusConfig.Builder.build() itself throws NullPointerException when neither an API key nor an enabled WIFConfig is set.

Configs

Optional<JsonValue> getConfig(String key)

Returns the config value as a JsonValue, or Optional.empty() when the key is absent.

<T> Optional<T> getConfigAs(String key, Class<T> type)

Returns the config value bound to the given type through the client’s JSON codec - in a Spring application, your own ObjectMapper. A value that cannot be bound throws NexusException.

Map<String, JsonValue> getAllConfigs()

A copy of every config in the cache. A public (wxp_) key receives all configs and flags, the same set a secret key sees; it does not receive secrets.

Feature flags

boolean getFlag(String key) / boolean getFlag(String key, boolean defaultValue)

Returns the is_active state of a flag, or defaultValue (false for the one-argument form) when the key is absent.

Optional<Boolean> findFlag(String key)

Returns the is_active state, or an empty Optional when the flag is not defined. getFlag cannot tell “the flag does not exist” from “it exists and is off” - both are false. The OpenFeature provider uses it to report FLAG_NOT_FOUND, and it is why an unknown key is never sent to evaluateAB: the endpoint answers false for a key it does not know.

Map<String, Boolean> getAllFlags()

A copy of every flag in the cache.

AB Testing

Map<String, Boolean> evaluateAB(List<String> keys, String userId, Map<String, String> attributes)

Batch-evaluates feature flags with AB Testing semantics: POST /v1/flags/evaluate-ab, returning the server’s results map. At most 200 keys per call. Unlike getFlag, this method always makes a network call, and it blocks; run it off the request thread if your handler is latency-sensitive.
Attribute values are strings. The endpoint binds them as a string-to-string map and cohort conditions compare them as strings, so formatting the value at the call site is what lets you control exactly what the rule is matched against. A null value is treated as unset and dropped - sent as "" it could satisfy an eq "" condition.

Secrets (secret key only)

String getSecret(String key)

Returns the plaintext value of a secret.

Optional<String> getSecretFilePath(String key)

Returns the absolute path of the file the SDK wrote for a type="file" secret, or Optional.empty() when the key is unknown or the secret is type="text". The file is created owner-only (0600), rewritten when the value changes, and removed on close().

Write API

For secret keys only; a public key throws NexusPublicKeyException without a network call. The cache is not updated by a write - call sync() to see the change at once.

State

SyncError is a record: code(), resourceType(), key(), secret() (the secret a config referenced, or null) and detail().

Sync and lifecycle

void sync()

Syncs now, regardless of the TTL, and atomically replaces the cache. If-None-Match is sent automatically; a 304 keeps the cache and resets the TTL. Concurrent calls apply one at a time, so an older response never replaces a newer one. It throws the same exceptions as the requests above.

void connectStream() / void disconnectStream()

Start or stop the stream thread; both are idempotent. The auto-configuration calls connectStream() unless nexus.stream=false.

void close()

Stops the stream, removes the files written for type="file" secrets, and releases the HTTP clients the SDK built. The auto-configuration registers it as the bean’s destroy method. NexusClient is AutoCloseable:

Extension points

Exceptions: see Error handling.