> ## 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.

# Spring Boot SDK - Version history

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

Every release of `nexus-spring-boot-starter` and `nexus-openfeature-spring-boot`, newest first. Both 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/spring-boot/-/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.
* **Virtual threads:** switches `sessionLock` from `synchronized` to `ReentrantLock` to avoid pinning carrier threads during token-exchange HTTP calls on JDK 21-23.

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

* **HTTP 423 `service_locked`:** adds `NexusServiceLockedException` and `NexusStreamObserver.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 `statusCode()`, `errorCode()` and `operation()`; the message never carries the response body. A `429` is `NexusRateLimitedException` on every path, or `NexusQuarantinedException` with a quarantine body.
* **The startup summary**: `nexus: client loaded` names the configs, secrets and flags the first sync delivered - never a value. The starter logs it through SLF4J; `WESTYX_NEXUS_LOG_STARTUP=1` writes it to stderr from a plain client with no logger.
* **`getSyncErrors()`** lists the resources the server did not deliver, each logged once as a warning; `nexus.log-sync-errors=false` keeps the list without the log lines. `NexusLogger` gains `warn`.
* **Concurrent `sync()` calls apply one at a time**, so an older response never replaces a newer one.
* **The stream recovers on its own from every failure.** A successful connection starts the failure count and the backoff over, and so does the cooldown; a connection that delivers nothing for `nexus.stream-idle-timeout` (90 s) is closed and reconnected; `disconnectStream()` ends a read on a silent connection at once.
* **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.
* **`nexus.sse-reconnect-cooldown`** binds from properties.
* **JDK 25** is tested, alongside 17 and 21; the Spring Boot matrix is 3.5.16, 4.0.9 and 4.1.2.

### Migrating to v0.17.0

* A custom `ExchangePayloadSource` implements `ExchangeCredential resolveCredential(ExchangeContext)` instead of `String buildPayload(ExchangeContext)`, returning `ExchangeCredential.oidc(token)` or `ExchangeCredential.awsIam(headers, body)` rather than a JSON body. `ExchangePayloadSource.ofOidcToken(...)` is unchanged.
* An expired `developer` credential throws `NexusSessionExpiredException` (it was `NexusWIFNotConfiguredException`); a missing one still throws `NexusWIFNotConfiguredException`.
* A blank token from `ExchangePayloadSource.ofOidcToken` throws `NexusWIFNotConfiguredException` (it was `NexusWIFTokenExchangeFailedException`).
* Code that matched the message of an unexpected status (`unexpected sync status 500`) reads `NexusApiException.statusCode()` instead.

## v0.16.0 - 2026-09-30

* **The endpoint can come from the environment.** With `nexus.base-url` (or `NexusConfig.baseUrl`) unset, the client reads `WESTYX_SERVICE_ENDPOINT`, which `westyx dev run` sets; the auto-configuration activates on either, and an error about the variable's value names the variable.
* **No key means WIF.** With no `nexus.api-key` and `nexus.wif.enabled` unset, the starter enables WIF with the configured provider, so `westyx dev run` starts a Spring application with no Nexus properties at all.

## v0.15.0 - 2026-08-25

* **The secret guard honours the backend's key classification.** A key is public - and secret access refused - when either the key's prefix or the server's `key_type` says so; `getKeyType()` reports that effective type.
* **A logger that throws cannot take the client down.** Every internal log call is contained.
* **The cached snapshot never renders a secret** - its `toString()` prints counts only.
* **An interrupted sync re-raises the interrupt.**

## v0.14.0 - 2026-08-10

* **The WIF provider is a type.** `WIFProvider` is an enum; `nexus.wif.provider` binds leniently and an unknown value fails the start naming every valid one.
* **`WIFConfig` has a factory per provider**, so a provider's options are reachable only through the factory that owns them.
* **`WIFConfig.custom(...)`** expresses a credential the SDK has no provider for.
* **A `developer` provider.** After `westyx dev setup`, a developer machine authenticates with the session the CLI already obtained; always the last provider `auto` considers.
* **The API key stays masked on the actuator's configuration endpoints** even with `show-values` on.
* **`X-Nexus-Server-ID` is the authority the request actually carries** - host, plus a port only when it is not the scheme's default.

### Migrating to v0.14.0

* `WIFConfig.builder().provider("...")` becomes the provider's factory: `WIFConfig.kubernetes()`, `aws()`, `awsIam(region)`, `gcp(audience)`, `azure(audience)`, `azureFederated()`, `developer()`, `auto()` or `custom(source)`.
* `WIFConfig.provider()` returns `WIFProvider`; the `PROVIDER_*` string constants are gone.
* `ExchangePayloadSource.buildPayload()` takes an `ExchangeContext`.

## v0.13.0 - 2026-08-06

* **A 402 throttles the background refresh** to one attempt every five minutes, and any successful sync - a `304` included - clears `isBillingOverdue()`. A quarantine `expires_at` is clamped to 24 hours.
* **Configuration is validated at `create()`**, with `NexusConfigException` naming the option.
* **The OpenFeature provider carries an integer larger than the `Value` integer slot as its exact decimal text** inside an object or array resolution.

### Migrating to v0.13.0

* A zero or negative `ttl`, an empty `sseReconnectCooldown`, or an entry below one minute is rejected; leave the option unset for the default.
* An oversized integer inside an object resolution is read with `asString()`.

## v0.12.0 - 2026-08-03

* **Per-user targeting in the OpenFeature provider** through the AB Testing add-on, one request per identity, memoised, with concurrent evaluations coalesced.
* **`findFlag(String)`** distinguishes a missing flag from one that is off.
* **An object config resolves into the OpenFeature value model**; integer resolutions are exact.

### Migrating to v0.12.0

* `evaluateAB` takes `Map<String, String>` attributes; format non-string values at the call site.
* An unknown boolean flag reports `FLAG_NOT_FOUND`; a non-`int` number in `getIntegerEvaluation` reports `TYPE_MISMATCH`; `getObjectEvaluation` returns a structured `Value`.

## v0.11.0 - 2026-07-28

* **One artifact for Spring Boot 3.5, 4.0 and 4.1**, built against 4.0.
* **The SDK no longer picks a JSON library for you** - Jackson 2 and 3 are both optional, and the SDK uses whichever your application has.
* **File-type secrets are written `0600`** at creation, opened `CREATE_NEW` + `NOFOLLOW_LINKS`, on paths scoped to each client.
* **SpotBugs + find-sec-bugs** run in the build; the OpenFeature provider has a CI test job.

### Migrating to v0.11.0

| Before | After |
| - | - |
| `Optional<JsonNode> v = nexus.getConfig(k)` | `Optional<JsonValue> v = nexus.getConfig(k)` |
| `Map<String, JsonNode> all = nexus.getAllConfigs()` | `Map<String, JsonValue> all = nexus.getAllConfigs()` |
| `node.asText()` | `value.asString()` |
| `node.isTextual()` | `value.isString()` |
| `node.path("x")` | `value.get("x")` |
| `node.asInt()` | `value.asInt(default)` |
| `NexusConfig.builder().objectMapper(m)` | `.jsonCodec(Jackson3Codec.using(m))` or `Jackson2Codec.using(m)` |

If you materialise file-type secrets on a shared host, rotate them after upgrading.

## 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** for ECS, Fargate, Lambda and plain EC2: a SigV4-signed STS `GetCallerIdentity` request bound to the service's own host. `nexus.wif.aws-region` sets the STS region.
* **Azure Workload Identity on AKS** - the projected federated token file is preferred over IMDS; the IMDS path requires an `api://<client-id>` audience.
* **Auto-detection probes the credential material**, never an environment variable alone.
* **`create()` rejects a plain-http base URL** outside loopback; metadata and exchange reads are bounded; a non-positive `expires_in` is an exchange failure.

## v0.8.0 - 2026-06-16

* **The OpenFeature provider** - the `nexus-openfeature-spring-boot` artifact.

## v0.6.0 - 2026-06-10

* **The stream reconnects after a fallback to polling**, on the `sseReconnectCooldown` schedule.

## v0.5.1 - 2026-06-03

* Exception messages carry status codes only; file-secret paths hash the key name; WIF tokens are trimmed; the WIF session is refreshed before each stream reconnect.

## v0.5.0 - 2026-06-01

* **The write API**: `setSecret`, `deleteSecret`, `deleteSecretVersion`, and `NexusRateLimitedException`.

## v0.4.0 - 2026-05-28

* All endpoints under `/v1/`; `NexusQuarantinedException` and `onQuarantined`.

## v0.3.1 - 2026-05-13

* The stream honours `Retry-After` on a `429`.

## v0.3.0

* AB testing batch evaluation, file-type secrets.

## v0.2.0

* Workload Identity Federation, stream observer hooks, 402 handling, service kind, separate sync and stream HTTP clients.

## v0.1.0

* Initial release.


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