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

# Spring Boot SDK

> Official Spring Boot SDK for Westyx Nexus - auto-configuration, two properties to start.

Official Spring Boot SDK for [Westyx Nexus](https://westyx.dev) - the centralised secrets, feature flags, and config service.

```yaml theme={null}
# application.yml
nexus:
  base-url: https://blue-ocean-a5rx7.westyx.dev
  api-key:  wxs_...
```

```java theme={null}
@Service
public class CheckoutService {

    private final NexusClient nexus;

    public CheckoutService(NexusClient nexus) {
        this.nexus = nexus;
    }

    public boolean newCheckoutEnabled() {
        return nexus.getFlag("checkout.v2", false);
    }
}
```

That's the entire integration. The auto-configuration creates the `NexusClient` bean at startup, performs a blocking initial sync, and starts the SSE stream in a daemon thread.

## What's new in v0.10.0

* Version alignment across the Westyx Nexus SDK suite.

## What's new in v0.9.0

* **`aws_iam` WIF provider (AWS IAM Caller Identity)** - authenticates non-EKS AWS compute (**ECS/Fargate, Lambda, plain EC2**) that has IAM credentials but no OIDC token. The SDK SigV4-signs an STS `GetCallerIdentity` request (never sent to AWS) and posts it to `/v1/auth/token-exchange`; Nexus replays it against a pinned STS endpoint to prove your IAM role. The signed `X-Nexus-Server-ID` is your service's own base-URL host - a captured request is valid for that one service only, and there is nothing to configure. Requires the optional `software.amazon.awssdk:auth` + `:regions` dependencies. See [Workload identity](workload-identity#aws-iam-non-eks-aws-compute).
* **Azure Workload Identity (AKS)** - the `azure` provider now prefers the projected federated token file (`$AZURE_FEDERATED_TOKEN_FILE`) before falling back to IMDS; auto-detection probes the file too, and the GCP identity request now includes `&format=full`.
* **Probe-based auto-detection** - auto-detect now stats the Kubernetes / AWS-IRSA / Azure token files and live-probes the GCP and Azure metadata servers (\~1 s timeout); the metadata client disables redirects and the system proxy.
* **Security hardening** - `NexusClient.create` rejects plain-http base URLs (loopback excepted); the Azure IMDS path refuses the generic default audience (must be `api://<client-id>`); metadata/exchange reads are bounded; a non-positive `expires_in` is treated as an exchange failure.

## What's new in v0.8.0

* **OpenFeature provider** - new `nexus-openfeature-spring-boot` sub-module. Wrap your `NexusClient`
  in a `NexusProvider` and register it with the OpenFeature Java SDK. See [OpenFeature](openfeature).

## What's new in v0.6.0

* **SSE reconnect after polling fallback** - the SDK now re-attempts the SSE stream after falling
  back to TTL polling. `sseReconnectCooldown` controls the delay (clamped 1s-300s).

## What's new in v0.5.1

* **Security improvements** - exception messages contain only HTTP status codes; file-type secret paths are fully hashed; WIF tokens stripped of whitespace.
* **WIF reliability** - session refreshes before each SSE reconnect; expired sessions no longer cause permanent TTL-polling fallback.
* **CI improvements** - tests run on every MR and `main` push; publish restricted to `main`-branch tags.

## What's new in v0.5.0

* **Write API** - `setSecret`, `deleteSecret`, `deleteSecretVersion` for programmatic secret management. secret keys only; public keys throw `NexusPublicKeyException` immediately without a network call.
* **`NexusRateLimitedException`** - new exception for HTTP 429 on write endpoints.

## What's new in v0.4.0

* **Path prefix corrected** - all API calls now use `/v1/` (e.g. `/v1/sync`, `/v1/stream`). Update `nexus.base-url` to `https://<slug>.westyx.dev` - no `/api` suffix needed.
* **Quarantine support** - HTTP 429 with `{"error":"quarantined","reason":"...","expires_at":"..."}` body now throws `NexusQuarantinedException` (sync) or triggers sleep-then-reconnect (stream). `NexusStreamObserver.onQuarantined(reason, expiresAt)` is called in both cases.
* **`isPublic` removed from `ConfigEntry`** - the field is no longer present in sync responses.

## What's new in v0.3.1

* **`Retry-After`-aware SSE 429 handling** - the stream now sleeps the indicated delay (clamped `[5 s, 5 min]`) and reconnects automatically when the server returns 429 with a parseable `Retry-After` header. Without `Retry-After`, legacy terminate-on-429 + TTL polling fallback preserved.

## What's new in v0.2.0

* **Workload Identity Federation** - Kubernetes / AWS IRSA / GCP / Azure auto-detected; bearer-JWT auth with automatic refresh. Configure via `nexus.wif.*` properties or a `WIFConfig` bean.
* **Stream observer hooks** - `NexusStreamObserver` interface; the auto-configuration wires any bean automatically.
* **Service kind awareness** - `getSecret()` blocked with `NexusServiceKindMismatchException` on `kind=frontend` services.
* **402 Payment Required handling** - `NexusBillingException`, `isBillingOverdue()`; background sync halted, cache served.
* **Split sync vs stream `HttpClient`** - a short consumer timeout cannot truncate the SSE stream.

## Highlights

* **Java 17+ / Spring Boot 3.x** - auto-configured starter, `NexusClient` bean from two properties
* **Zero hard external dependencies** beyond Jackson (already on the Spring Boot classpath) and SLF4J
* **Thread-safe TTL cache** with atomic snapshot replacement and ETag/304 support
* **Background refresh** - request threads are never blocked on cache expiry
* **SSE live updates** - propagates remote changes within milliseconds; falls back to TTL polling after 3 transport errors
* **Typed exception hierarchy** - `NexusException` base + 10 subclasses for `catch` clauses
* **Workload Identity Federation** *(v0.2.0)* - Kubernetes / AWS IRSA / GCP / Azure auto-detection; bearer JWT auth; **AWS IAM (`aws_iam`)** for ECS/Fargate/Lambda/plain-EC2 *(v0.9.0)*
* **Stream observer hooks** *(v0.2.0)* - structured callbacks for SSE lifecycle events

## Package

Hosted on the [GitLab Maven Package Registry](https://gitlab.com/westyx/nexus/sdk/spring-boot/-/packages). Install:

```xml theme={null}
<dependency>
  <groupId>dev.westyx.nexus</groupId>
  <artifactId>nexus-spring-boot-starter</artifactId>
  <version>0.10.0</version>
</dependency>
```

Latest release: **v0.10.0** *(2026-07-05 - version alignment across the Westyx Nexus SDK suite)*.

## Pages

| Page                                   | Description                                               |
| -------------------------------------- | --------------------------------------------------------- |
| [Installation](installation)           | Register the GitLab Maven registry and add the dependency |
| [Configuration](configuration)         | `nexus.*` property reference                              |
| [API reference](api-reference)         | Every public method, getter, and bean                     |
| [Error handling](error-handling)       | Exception hierarchy + when each is thrown                 |
| [SSE live updates](sse-live-updates)   | How live propagation works                                |
| [Stream observer](stream-observer)     | `NexusStreamObserver` reference                           |
| [Workload identity](workload-identity) | WIF setup, providers, custom token sources                |
| [Caching behaviour](caching-behaviour) | When does the SDK hit the network                         |