Kotlin SDK - Configuration

NexusConfig is the single configuration object passed to NexusClient.create(). All fields are immutable after construction. Every field is validated once, at create. A rejected value raises NexusConfigException naming the option, the offending value and - for a list option - the index. Nothing is coerced: a coerced mistake resurfaces days later as unexplained load or a stalled stream with nothing pointing at the cause.

NexusConfig

data class NexusConfig(
    val baseUrl:              String,
    val apiKey:               String?       = null,
    val ttl:                  Duration      = 60.seconds,
    val wif:                  WifConfig?    = null,
    val observer:             NexusObserver = NoopNexusObserver,
    val sseReconnectCooldown: IntArray?     = null,
    val logger:               Logger        = LoggerFactory.getLogger("dev.westyx.nexus"),
)

Field reference

Field	Type	Default	Description
`baseUrl`	`String`	-	Base URL of your Westyx Nexus service, for example `https://my-service.westyx.dev`. Trailing slash is stripped automatically. Must be `https`; plain `http` is accepted only for `localhost`/loopback, since credentials travel on every request.
`apiKey`	`String?`	`null`	Service API key. A secret key (backend services) has the literal prefix `wxs_`; a public key (browser/frontend, safe to expose) has `wxp_` and cannot read secrets. Required unless `wif.enabled` is true. A blank string is rejected - pass `null` to omit it. When WIF is active the session JWT is used instead, and a static key configured alongside WIF acts only as an explicit fallback.
`ttl`	`Duration`	`60.seconds`	How long a synced snapshot is considered fresh. Must be greater than zero. See Caching behaviour.
`wif`	`WifConfig?`	`null`	Workload identity federation settings. When `wif.enabled = true`, the SDK exchanges a workload credential for a short-lived Nexus session token at startup, and fails closed if it cannot. See Workload identity.
`observer`	`NexusObserver`	`NoopNexusObserver`	Callbacks for stream lifecycle and error events. Every callback is invoked through a guarded dispatcher, so one that throws cannot stop the stream. See Stream observer.
`sseReconnectCooldown`	`IntArray?`	`null`	Schedule, in minutes, for reattempting the SSE stream after it falls back to TTL polling. `null` means `[5, 10, 20, 40, 60]`. One element is a fixed delay; several form a schedule that stays at the last value. Every entry must be at least 1 - a smaller value is rejected with its index named, not clamped.
`logger`	`org.slf4j.Logger`	the logger named `dev.westyx.nexus`	Where the SDK writes diagnostics. SLF4J is a no-op unless the application binds a backend, so the default is silent. See Logging.

NexusConfig.toString() redacts apiKey, since a config is often printed while debugging.

TTL explanation

The ttl controls how stale the local in-memory snapshot can get before the SDK triggers a background refresh.

On every getter call (getString, getBoolean, etc.), an internal freshness check compares now - syncedAt against ttl.
If the snapshot is stale, a background coroutine syncs. The current call returns the cached value immediately - there is no blocking.
Concurrent stale reads coalesce: a burst produces one sync plus at most one follow-up, not one per read.
The stream push path (connectStream) bypasses the TTL entirely: when a push event arrives, a sync runs regardless.

Recommended values:

Scenario	TTL
Production service with SSE stream active	`60.seconds` or higher - the stream covers freshness
Batch job or short-lived worker	`10.seconds` - aggressive polling, no stream needed
High-frequency read path, config rarely changes	`300.seconds` - reduce API call rate

WifConfig

data class WifConfig(
    val enabled:    Boolean       = false,
    val credential: WifCredential = WifCredential.Auto(),
)

Field	Type	Default	Meaning
`enabled`	`Boolean`	`false`	Present a workload credential instead of a static API key.
`credential`	`WifCredential`	`WifCredential.Auto()`	Which credential to present. Each case carries only the options that credential has.

WifCredential

Case	Options	Auto-detected
`WifCredential.Kubernetes`	-	yes - the projected service-account token file
`WifCredential.Aws`	-	yes - the IRSA token file named by `$AWS_WEB_IDENTITY_TOKEN_FILE`
`WifCredential.AwsIam`	`region: String?` - pins `sts.<region>.amazonaws.com`; null resolves it from the AWS chain	no - select it explicitly
`WifCredential.Gcp`	`audience: String` - defaults to `westyx-nexus`	yes - a GCE metadata probe
`WifCredential.Azure`	`audience: String?` - your app registration’s Application ID URI (`api://<client-id>`); leave null on AKS Workload Identity, where the projected file carries its own	yes - the federated file, else an IMDS probe
`WifCredential.Developer`	-	yes, last - a session `westyx dev setup` already issued
`WifCredential.Custom`	`source: ExchangePayloadProvider`, `audience: String?`	no

WifCredential.Auto() probes the environment - stat-ing token files and live-probing the metadata servers - and picks the first that has credential material. Its audience applies to the GCP path, the only probed credential that requests one. aws_iam is never auto-detected, and the developer credential is always considered last. WifCredential.Custom takes an ExchangePayloadProvider, which returns the whole POST /v1/auth/token-exchange body rather than a bearer string, so a credential that is not an OIDC token can be expressed. oidcTokenProvider { ... } adapts a plain token supplier. An Azure audience that is blank or the generic westyx-nexus default is rejected at construction: Azure AD does not accept it as a resource, and the SDK never substitutes an ARM token. See Workload identity for full provider details.

Minimal configs

API key only

val config = NexusConfig(
    baseUrl = "https://my-service.westyx.dev",
    apiKey  = System.getenv("NEXUS_API_KEY"),
)

WIF with auto-detection

val config = NexusConfig(
    baseUrl = "https://my-service.westyx.dev",
    wif = WifConfig(enabled = true),
)

Custom TTL, observer, reconnect schedule and logger

val config = NexusConfig(
    baseUrl              = "https://my-service.westyx.dev",
    apiKey               = System.getenv("NEXUS_API_KEY"),
    ttl                  = 30.seconds,
    observer             = MyNexusObserver(),
    sseReconnectCooldown = intArrayOf(2, 5, 15),   // minutes
    logger               = LoggerFactory.getLogger("my-app.nexus"),
)

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Kotlin SDK - Configuration

NexusConfig

Field reference

TTL explanation

WifConfig

WifCredential

Minimal configs

API key only

WIF with auto-detection

Custom TTL, observer, reconnect schedule and logger

​NexusConfig

​Field reference

​TTL explanation

​WifConfig

​WifCredential

​Minimal configs

​API key only

​WIF with auto-detection

​Custom TTL, observer, reconnect schedule and logger

NexusConfig

Field reference

TTL explanation

WifConfig

WifCredential

Minimal configs

API key only

WIF with auto-detection

Custom TTL, observer, reconnect schedule and logger