> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Kotlin SDK - Version history

> What changed in each release of the Kotlin SDK, and how to migrate across a breaking change.

Every release of `nexus-kotlin-sdk`, `nexus-kotlin-openfeature` and `nexus-ktor-plugin`, newest first. The three release from one tag and share one version number. Where a release broke something, its **Migrating** section shows the change to make. The repository's [`CHANGELOG.md`](https://gitlab.com/westyx/nexus/sdk/kotlin/-/blob/main/CHANGELOG.md) carries the same releases in full detail.

## v0.18.1 - 2026-11-19

* **OpenFeature `423 service_locked` hold:** uses a timed suppression window (default 5 minutes) matching `environment_disabled`, so `evaluateAB` recovers automatically once the lockdown is lifted.

## v0.18.0 (2026-11-19)

* **HTTP 423 `service_locked`:** adds `NexusServiceLockedException` and `FALLBACK_REASON_SERVICE_LOCKED`; stops SSE reconnects immediately and halts background sync retries until an explicit `sync()` succeeds.
* **OpenFeature provider:** suppresses repeated `evaluateAB` requests while the service is locked down, serving the cached snapshot as `STALE`.

## v0.17.0 - 2026-11-12

* **A switched-off environment is reported by name.** `403 {"error":"environment_disabled"}` throws `NexusEnvironmentDisabledException` on every request. The cache keeps serving; the background refresh and the stream wait five minutes between attempts (`onFallback("environment-disabled")`), one warning is logged, and the first successful sync clears it. The OpenFeature provider serves the snapshot as `STALE` meanwhile.
* **Every API error carries its status and code.** A response no more specific exception describes throws `NexusApiException` with `status`, `code` and `operation`; `NexusForbiddenException` is one too. The message never carries the response body.
* **The startup summary**: `nexus: client loaded` names the configs, secrets and flags the first sync delivered - never a value.
* **`syncErrors`** lists the resources the server did not deliver, each logged once as a warning; `logSyncErrors = false` keeps the list without the log lines.
* **A WIF refresh that fails while the session is still valid no longer fails the request**; an expired session falls back to the `apiKey`, or throws `NexusSessionExpiredException` with the refresh error as its cause, and a credential that is gone throws `NexusWifNotConfiguredException` at once.

### Migrating to v0.17.0

* A custom `ExchangePayloadProvider` implements `suspend fun resolveCredential(context: ExchangeContext): ExchangeCredential` instead of `buildPayload(context): String`, returning `ExchangeCredential.Oidc(token)` or `ExchangeCredential.AwsIam(headers, body)` rather than a JSON body. `oidcTokenProvider { }` is unchanged.
* Code that matched the message of an unexpected status (`nexus: /v1/sync returned 500`) reads `NexusApiException.status` instead.
* Code compiled against an earlier version that calls the `NexusConfig` constructor or `copy` positionally is recompiled; named arguments are unaffected.

## v0.16.0 - 2026-09-30

* **The endpoint can come from the environment.** Leave `baseUrl` empty and the client reads
  `WESTYX_SERVICE_ENDPOINT` when it is created - `westyx dev run` sets it for the script's service,
  so a locally started application needs neither an endpoint nor a key in its code. A `baseUrl` you
  set always wins, and an error about the variable's value names the variable. The Ktor plugin's
  `endpoint` falls back the same way. See [Configuration](https://docs.westyx.dev/sdks/kotlin/configuration.md#service-endpoint).

## v0.15.1 - 2026-08-19

* A code-quality maintenance release: internal improvements only, with no behaviour or API change.

## v0.15.0 - 2026-08-19

* **Credential-bearing requests never follow a redirect.** The API and stream clients refuse
  redirects, so the API key and the WIF session token reach only the endpoint you configured.
* **The public-key guard honours the backend's classification.** A key the backend reports as public
  is refused secret access whether or not it carries the `wxp_` prefix - the guard reads either signal.
* **`aws_iam` signs the full authority.** The signed `X-Nexus-Server-ID` includes a non-default port,
  so `aws_iam` authenticates on a deployment reachable at a port other than 443.
* **The wire models are `internal`.** `SecretEntry`, `SyncResponse` and `TokenExchangeResponse` carry
  the server's wire format and are no longer exported; their `toString()`, and the client's own,
  render secrets and tokens as `***`. **Breaking** only if you referenced those types directly.

## v0.14.1 - 2026-08-07

* **Auto-detection reaches Azure IMDS when `WifCredential.Auto` carries an audience.** On a non-AKS
  Azure VM, `WifCredential.Auto(audience = "api://<client-id>")` is what that step needs; the
  generic `westyx-nexus` default is still refused rather than sent, because Azure AD rejects it as a
  resource. AKS Workload Identity is unaffected - its projected token file carries its own audience.

## v0.14.0 - 2026-08-07

The WIF configuration surface is reshaped, and local development gets a credential of its own.
**It contains breaking changes** - see the CHANGELOG for the migration table.

* **`WifConfig` is `enabled` plus `credential`**, a sealed `WifCredential` whose cases carry only
  the options that credential has: no audience on Kubernetes, no AWS region outside `AwsIam`, and
  no way to combine a built-in provider with a custom one.
* **A `developer` credential** - `westyx dev setup` issues a session for your service and the SDK
  picks it up with no code change, last in auto-detection so a cloud credential always wins.
* **`ExchangePayloadProvider`**, a public extension point that returns the whole exchange payload,
  so a credential that is not an OIDC bearer token can be expressed.
* **`WifProvider`**, an enum for the provider vocabulary, with `fromWire` for parsing a string.

### Migrating to v0.14.0

| Before | After |
| - | - |
| `WifConfig(enabled = true, provider = "auto")` | `WifConfig(enabled = true)` |
| `WifConfig(enabled = true, provider = "kubernetes")` | `WifConfig(enabled = true, credential = WifCredential.Kubernetes)` |
| `WifConfig(enabled = true, provider = "aws")` | `WifConfig(enabled = true, credential = WifCredential.Aws)` |
| `WifConfig(enabled = true, provider = "aws_iam", awsRegion = "eu-central-1")` | `WifConfig(enabled = true, credential = WifCredential.AwsIam(region = "eu-central-1"))` |
| `WifConfig(enabled = true, provider = "gcp", audience = "westyx-nexus")` | `WifConfig(enabled = true, credential = WifCredential.Gcp())` |
| `WifConfig(enabled = true, provider = "azure", audience = "api://<id>")` | `WifConfig(enabled = true, credential = WifCredential.Azure("api://<id>"))` |
| `WifConfig(enabled = true, tokenSource = { fetch() })` | `WifConfig(enabled = true, credential = WifCredential.Custom(oidcTokenProvider { fetch() }))` |

The `WIF_PROVIDER_*` constants are replaced by the `WifProvider` enum; parse a string with `WifProvider.fromWire(value)`.

## v0.13.0 - 2026-08-06

* **A composite (object or array) OpenFeature resolution carries an integer larger than
  the `Value` type's 32-bit integer slot as its exact decimal text.** An integer that
  fits stays an `Int`, a genuinely fractional number stays a `Double`, and the scalar
  `Integer` evaluation still answers `TYPE_MISMATCH` for the same value - the two paths
  differ on purpose.

## v0.12.1 - 2026-08-03

* **An `Integer` evaluation through the OpenFeature provider requires an exact `Int`.** A fractional config value resolved as the truncated integer with a success reason - `3.14` gave `3` - which handed the caller a wrong number with nothing to indicate it. It now resolves as `TYPE_MISMATCH` with the default you passed, the same answer every other Westyx Nexus SDK gives. See [OpenFeature](https://docs.westyx.dev/sdks/kotlin/openfeature.md).
* **`getInt` and `getLong` read a whole number written with a decimal point** - `8.0` reads as `8`, where it previously returned the default. A fractional value still returns the default, and the log line names which of the two mistakes it was.

## v0.12.0 - 2026-07-31

* **The OpenFeature provider resolves per user.** An `EvaluationContext` carrying a targeting key
  now selects a per-user boolean evaluation through the Nexus AB Testing add-on, so rollout
  percentages and cohort rules apply. One request covers every flag in the snapshot, results are
  memoised per user for 30 seconds, and concurrent evaluations for the same user coalesce into one
  call. The targeted path blocks the calling thread - see the OpenFeature page.
* **`NexusProviderOptions`** - `targetingTtl`, `maxTargetingKeys`, `addonSuppression` and
  `logger`, each validated in the constructor.
* **`NexusClient.getAllFlags()`** returns every flag in the snapshot with its active state, as
  every other Westyx Nexus SDK does.

Upgrading needs no source change.

## v0.11.0 - 2026-07-29

* **No bundled HTTP engine.** The SDK depends on `ktor-client-core` only, so engine choice - connection pooling, TLS, proxying - stays with the application. Add one engine artifact, or pass one to `NexusClient.create(engine = …)`. With none available, `create` raises `NexusNoHttpEngineException` naming the dependency line to add. See [Installation](https://docs.westyx.dev/sdks/kotlin/installation.md).
* **Logging, via SLF4J.** `NexusConfig.logger` defaults to the logger named `dev.westyx.nexus` and is a no-op until the application binds a backend. No record carries a secret value, a secret key name, an API key, a session JWT or a workload OIDC token.
* **A Ktor server plugin**, published separately as `nexus-ktor-plugin`. See [Ktor plugin](https://docs.westyx.dev/sdks/kotlin/ktor-plugin.md).
* **`getLong`** reads an integer config exactly, including values above 2^53; **`findFlag`** returns `null` for a flag that does not exist; **`syncedAt()`** reports when the snapshot was last confirmed current.
* **The stream reconnects after a clean server close** - which is what a deploy and a WIF session rollover both produce. `connectStream()` is idempotent, and the stream has a connect deadline and a 90-second idle deadline. See [SSE live updates](https://docs.westyx.dev/sdks/kotlin/sse-live-updates.md).
* **A 402 throttles the background refresh for five minutes** instead of suspending it, and any success clears it. A quarantine deadline is honoured up to a 24-hour bound. Refreshes are serialised and coalesced, and a 304 resets the TTL. See [Caching behaviour](https://docs.westyx.dev/sdks/kotlin/caching-behaviour.md).
* **Response bodies are bounded while reading**, and one status-to-exception mapping is shared by every endpoint. See [Error handling](https://docs.westyx.dev/sdks/kotlin/error-handling.md).
* **Observer callbacks are guarded** - a throwing callback is absorbed, reported through the logger, and cannot stop the stream. See [Stream observer](https://docs.westyx.dev/sdks/kotlin/stream-observer.md).
* **File-type secrets are `0600` from creation**, in a per-client `0700` directory created on first use and removed by `close()` or a JVM shutdown hook.
* **WIF selection fails closed**: a client that asked for workload identity is never quietly created with API-key authentication. See [Workload identity](https://docs.westyx.dev/sdks/kotlin/workload-identity.md).
* **`sseReconnectCooldown` rejects a value below one minute** instead of clamping it, and `ttl` must be positive - both named in the error.
* Ktor 3.5.1, coroutines 1.11.0, serialization 1.11.0, SLF4J 2.0.18, AWS SDK 2.49.5, OpenFeature 1.22.0; built with Kotlin 2.4.10. JVM baseline unchanged at 17, now tested on 17, 21 and 25.

### Migrating to v0.11.0

* Add one Ktor client engine (`io.ktor:ktor-client-cio`, `-okhttp`, `-java` or `-apache5`), or pass one to `NexusClient.create(engine = ...)`.
* A client with `wif.enabled = true` whose credential cannot be resolved raises `NexusWifNotConfiguredException`; configure `apiKey` and leave WIF disabled if you relied on the API-key fallback.
* `sseReconnectCooldown` entries below 1 and a non-positive `ttl` raise `NexusConfigException`; `apiKey` is required unless WIF is enabled.
* `getString` returns a composite value's default - use `getJson`; `getInt` returns the default outside `Int` range - use `getLong`.
* The OpenFeature provider reports `FLAG_NOT_FOUND` for a missing flag and returns a structured `Value` for an object.

## v0.10.0 - 2026-07-05

* Version alignment across the Westyx Nexus SDK suite.

## v0.9.0 - 2026-07-03

* The `aws_iam` WIF provider; Azure requests the app-registration audience rather than an ARM token; https enforced on the base URL; fail-closed session refresh; `expires_in` guard; hardened metadata client.

## v0.8.0 - 2026-06-16

* The OpenFeature provider (`nexus-kotlin-openfeature`).

## v0.6.0 - 2026-06-10

* The stream reconnects after the TTL-polling fallback, on the `sseReconnectCooldown` schedule (in minutes).

## v0.5.1 - 2026-06-03

* Response bodies removed from exception messages; file-secret paths hash key and value; thread-safe WIF session state; SSE event whitelist.

## v0.5.0 - 2026-06-01

* Write API: `setSecret`, `deleteSecret`, `deleteSecretVersion`; `NexusRateLimitedException`.

## v0.4.0 - 2026-05-28

* Initial release: `evaluateAB`, quarantine handling, `auth_expiring` refresh, `getSecretFilePath`, `streamStatus`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.