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

# Go SDK - Version history

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

Every release of the three modules (`gitlab.com/westyx/nexus/sdk/go`, `.../openfeature`,
`.../wifaws`), newest first. The three are tagged together 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/go/-/blob/main/CHANGELOG.md)
carries the same releases in full detail.

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

* **HTTP 423 `service_locked`:** adds `ErrServiceLocked` and `FallbackReasonServiceLocked`; `RunStream` exits immediately on `423` and background sync retries halt until an explicit `Sync` succeeds.
* **OpenFeature provider:** suppresses repeated `EvaluateAB` requests while the service is locked down, serving the cached snapshot as `STALE`.

## v0.18.2 - 2026-11-12

* **The OpenFeature provider stops asking a switched-off environment.** While the environment is switched off in the console, a targeted evaluation serves the snapshot as `STALE` and the provider sends no `EvaluateAB` request - for any user - for the add-on suppression window, with one warning; any success clears it.

## v0.18.1 - 2026-11-11

* **`ErrSessionExpired` is returned when it says it is:** the session has expired, its refresh
  failed, and there is no static `APIKey`. It wraps the refresh error, so `errors.Is` matches both.
* **A refresh that fails while the session is still valid no longer fails the request** - the
  session carries it until it expires, and the SDK logs a `Warn` record.
* **With an `APIKey`, an expired session falls back to the key** instead of being sent.
* **A credential that is gone fails closed at once** (`ErrWIFNotConfigured`) when there is no
  `APIKey`.
* `openfeature` and `wifaws` require the core at `v0.18.1`.

## v0.18.0 - 2026-11-11

* **A switched-off environment has its own sentinel.** `ErrEnvironmentDisabled` matches,
  with `errors.Is`, the 403 `environment_disabled` the server answers on every call and on
  the token exchange. The cache keeps serving; the background refresh waits five minutes
  between attempts and the stream reconnects on the cooldown schedule
  (`FallbackReasonEnvironmentDisabled`) until the environment is switched on. See
  [Error handling](https://docs.westyx.dev/sdks/go/error-handling.md).
* **`*APIError` carries `StatusCode` and `Code`** for any status with no sentinel, so a
  `410 tenant_deleted` can be told apart without parsing a message.
* **`SyncErrors()`** lists the resources the server left out of the last sync, and each is
  logged once as a `Warn` record (`Config.DisableSyncErrorLog` turns that off).
* **A startup summary** - `client loaded` names the configs, secrets and flags the first
  sync delivered, never a value. Without a `Logger`, `WESTYX_NEXUS_LOG_STARTUP=1` writes it
  to standard error. See [Logging](https://docs.westyx.dev/sdks/go/logging.md).
* **Syncs run one at a time**, so a slow response can no longer replace a newer one.
* **The stream's failure count and backoff start over after a successful connection.**
* **Breaking: `ExchangePayloadFunc` returns an `ExchangeCredential`** - a `nexus.OIDCToken`
  or a `nexus.AWSSignedRequest` - and the SDK writes the token-exchange body.
* **The toolchain pin is go1.26.11** (GO-2026-6859); CI tests Go 1.25, 1.26 and 1.27.

### Migrating to v0.18.0

`wifaws.ExchangePayload` needs no change: upgrade `wifaws` to v0.18.0 together with the
core. A producer of your own returns the credential instead of the JSON body:

```go theme={null}
// before
ExchangePayload: func(ctx context.Context, t nexus.ExchangeTarget) ([]byte, error) {
    return json.Marshal(map[string]string{"oidc_token": token})
},

// after
ExchangePayload: func(ctx context.Context, t nexus.ExchangeTarget) (nexus.ExchangeCredential, error) {
    return nexus.OIDCToken{Token: token}, nil
},
```

## v0.17.0 - 2026-09-30

* **The endpoint can come from the environment.** With `Config.BaseURL` empty,
  `NewClient` reads `WESTYX_SERVICE_ENDPOINT` (`nexus.ServiceEndpointEnv`), which
  `westyx dev run` sets for the script's service - so neither the endpoint nor a key
  has to be in your code. `BaseURL` wins when both are set, and an error about a
  value from the variable names the variable.

## v0.16.1 - 2026-08-30

* **A 402 Payment Required no longer suspends background refresh indefinitely.**
  The client retries on its own every five minutes instead of requiring an
  explicit `Sync` call to notice the tenant's invoices were settled.
* **The Go toolchain is pinned to 1.25.13**, closing four disclosed standard-library
  CVEs. A build environment that pins an older Go image needs `GOTOOLCHAIN=auto` for
  this pin to actually take effect.

## v0.15.0 - 2026-08-13

* **Printing a client or its config is safe.** `%v`, `%+v`, `%#v`, `%s`, `fmt.Print` and
  every `slog` handler render a redacted form - the base URL, the key type, the WIF
  provider and how many configs, secrets and flags are cached - never the API key and
  never a secret value. `Config` and `*Client` implement `fmt.Stringer`,
  `fmt.GoStringer` and `slog.LogValuer`, which together cover every channel: `fmt`
  sends `%#v` to `GoStringer` rather than `Stringer`, and a handler resolves
  `LogValuer` before formatting. See [Logging](https://docs.westyx.dev/sdks/go/logging.md).
* **A redirect is refused rather than followed.** `net/http` copies a custom header
  such as `X-Nexus-API-Key` across a redirect even when the domain changes, and the
  response that followed would become the cache. A Nexus endpoint does not redirect,
  and the error names the location it was sent to.
* **A secret operation is refused whenever the backend classifies the key as public**,
  not only when it carries the `wxp_` prefix. `KeyType()` reports the effective type.
* **`SnapshotRevision()` and `Subscribe(fn)`** report configuration changes.
  `SnapshotRevision` counts contents replacements, so a 304 or a stream reconnect
  leaves it unchanged; `Subscribe` runs the callback after the new snapshot is visible,
  which `StreamObserver.OnEvent` cannot do - it fires before the sync it announces.
* **The OpenFeature provider emits `PROVIDER_CONFIGURATION_CHANGED`** and drops its
  per-user evaluation cache when the configuration moves.
  `openfeature.NewProvider` reports an invalid option as an error where `New` panics.
* Fixes: a very large `Retry-After` no longer overflows into "retry immediately"; a
  failed `NewClient` releases the connection it opened; a developer credential expiring
  inside the refresh window is refused with the renew command; and an entry written
  `https://svc.westyx.dev:443` matches a client configured `https://svc.westyx.dev`.

## v0.14.0 - 2026-08-09

* **The `developer` WIF provider - the same code authenticates on a laptop and in a cluster.** Run `westyx dev setup --service=<name>` once, and `WIFConfig{Enabled: true}` is the entire configuration on your machine. The SDK finds the session the Westyx CLI already obtained - `$WESTYX_DEV_TOKEN` first, then the CLI's `dev-credentials.json` matched to your endpoint - and uses it directly as the bearer credential. **No token exchange happens on this path**; the CLI performed it. The credential is probed last, after every cloud provider, so a real workload credential always wins, and the file is re-read on every refresh so `westyx dev setup` takes effect without a restart.
* **A payload producer is told which service it is producing a credential for.** `ExchangePayloadFunc` receives a `nexus.ExchangeTarget` carrying the client's `BaseURL` host, so `wifaws.ExchangePayload(ctx, wifaws.Config{})` needs no `ServerID` - the host signed into `X-Nexus-Server-ID` comes from the client that will send the request.
* **`WIFConfig.Provider` is a `nexus.WIFProvider`** with `Valid()` and `String()`, the same closed domain the Nexus backend models. An unknown provider is reported by `NewClient` with the accepted set named.
* **An override that names its provider is logged as that provider** rather than as `custom`.
* Breaking, three one-line call shapes: a typed constant assigned to a `string` variable needs `string(...)`; a custom `ExchangePayload` gains a `nexus.ExchangeTarget` parameter; `wifaws.Config.ServerID` is optional and a value disagreeing with the client's host is refused. `Provider: WIFProviderAWSIAM` together with `TokenSource` is now rejected at construction - the two describe different kinds of credential.

## v0.13.0 - 2026-08-06

* **File-type secrets are materialised into a directory private to the client.** Each client creates its own `0700` directory (`nexus-secrets-*` under the system temp directory) lazily on the first file-type secret and writes the `0600` files inside it, so a file left behind by an abrupt exit sits where no other local user can enter. `Close` removes the directory with everything in it. The file name no longer carries an instance id - the directory's random suffix keeps clients apart. If you logged or asserted on the previous flat `os.TempDir()` paths, read the path from `GetSecretFilePath`.
* **`Close` is documented as the only cleanup point for materialised secrets.** Go runs no code on `os.Exit`, finalizers are not guaranteed to run before termination, and a library must not install a signal handler - so there is deliberately no exit backstop.
* **A `Sync` called on a closed client leaves nothing on disk.**

## v0.12.0 - 2026-07-31

* **Boolean flag evaluation is per-user.** With a targeting key in the `EvaluationContext`, the OpenFeature provider resolves the flag through the AB Testing add-on, applying its rollout percentage and cohort rules to that identity. Without a targeting key it reads the synced snapshot, exactly as before.
* **`FindFlag(key)`** returns the flag's `is_active` state together with whether the flag is in the cache at all - a distinction `GetFlag` cannot express.
* Breaking: `EvaluateAB`'s `attributes` is `map[string]string`, and an OpenFeature boolean evaluation of a flag the snapshot does not hold returns `FLAG_NOT_FOUND` rather than your default with a `STATIC` reason. A non-string attribute value was already rejected by the service with `400`, so nothing that worked before stops working.

## v0.11.0 - 2026-07-28

A correctness, security and packaging release. **Several items are breaking**; each is
a one-line change at the call site, and the README carries a migration table.

* **The core module has no dependencies at all.** The `aws_iam` WIF provider moved to
  `gitlab.com/westyx/nexus/sdk/go/wifaws` *(breaking)*. Go has no optional
  dependencies, so while the SigV4 signer lived in the core module every consumer's
  build carried the AWS SDK - including services that run nowhere near AWS. Every
  other provider is unchanged and still needs nothing.
* **The minimum is Go 1.25.** The `go` directive is a hard floor for everyone who
  imports the module, transitively, and Go supports the two newest majors - so naming
  a patch release of the newest one excluded every Go 1.25 install. CI runs the suite
  on both.
* **Config numbers are `json.Number`, not `float64`** *(breaking)*. `float64` cannot
  represent an integer above 2^53 exactly, so an id or an amount in minor units came
  back altered with nothing to indicate it. See [Config values](https://docs.westyx.dev/sdks/go/config-values.md).
* **New `GetConfigAs[T]`** decodes a config value straight into your own type from the
  exact bytes the backend sent.
* **`Config.Logger` is a `*slog.Logger`** *(breaking)*. Records carry attributes plus a
  `component` field rather than pre-formatted text, so the output is aggregatable. Any
  backend works - zap, zerolog and logrus all provide an `slog.Handler`. See
  [Logging](https://docs.westyx.dev/sdks/go/logging.md).
* **The SSE stream has an idle deadline** (`StreamIdleTimeout`, default 90 s = three
  missed keepalives), so a connection that is black-holed rather than closed is
  detected and reconnected instead of leaving a read blocked with no deadline.
* **New `StreamConnected()`** reports whether live updates are arriving right now.
* **The stream outlives the context passed to `NewClient`** *(breaking)*. That context
  bounds construction; `Close` is what ends a client.
* **The background refresh backs off after a failure**, so the retry rate is the SDK's
  choice rather than a function of how often the application reads.
* **A panicking observer callback is contained and reported.** In Go this is not
  cosmetic: a panic can only be recovered on the goroutine that raised it, and these
  callbacks run on a goroutine the SDK starts.
* **`TTL` and `SSEReconnectCooldown` are validated at construction**, with the
  offending value named, rather than silently clamped at the point of use.
* **File-type secrets are created `0600`**, with the mode applied at creation rather
  than by a chmod afterwards, opened `O_EXCL` and `O_NOFOLLOW`; each client scopes its
  paths with an instance id so two clients never share a file.
* **Every response the SDK decodes is size-bounded**, and `govulncheck` plus `gosec`,
  `errorlint`, `bodyclose`, `noctx` and `contextcheck` run in CI.

## v0.10.1 - 2026-07-10

* **Config reads are deep-copied** - `GetConfig` and `GetAllConfigs` return a deep copy of object/array config values, so mutating a returned nested `map`/slice can no longer corrupt the shared cache or race a background refresh. Scalars are unaffected.
* **Clean shutdown** - `Close` cancels all background work (TTL refresh, WIF session refresh) and waits for it to finish before removing `file`-secret temp files; a closed client never starts a new background sync, and no orphaned secret files are left on disk.
* **Lint enforced in CI** - committed `.golangci.yml` plus a pinned `golangci-lint` stage covering the root and `openfeature/` modules.

## v0.10.0 - 2026-07-05

* Version alignment across the Westyx Nexus SDK suite.

## v0.9.0 - 2026-07-03

* **`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 `BaseURL` host - a captured request is valid for that one service only, and there is nothing to configure. See [Workload identity](https://docs.westyx.dev/sdks/go/workload-identity.md#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.
* **Security hardening** - `NewClient` rejects plain-http `BaseURL`s (loopback excepted); the Azure IMDS path refuses the generic default audience (must be `api://<client-id>`); the token-exchange response read is bounded; AWS auto-detection stats the IRSA token file instead of trusting the env var.
* **WIF test suite** - per-provider token-source tests, auto-detect dispatch, the Azure audience guard, and the signed `aws_iam` payload shape.

## v0.8.0 - 2026-06-16

* **OpenFeature provider** - new `openfeature/` sub-module (`gitlab.com/westyx/nexus/sdk/go/openfeature`). Wraps an initialized `*nexus.Client` and implements the OpenFeature `FeatureProvider` interface. `EvaluationContext` is ignored - Nexus has no per-user targeting. See [OpenFeature integration](https://docs.westyx.dev/sdks/go/openfeature.md).

## v0.5.1 - 2026-06-03

* **Security improvements** - exception messages contain only status codes; `file`-type secret paths are fully hashed so key names are never visible on the filesystem.
* **`Close()` cancels the stream** - `Close()` now stops the `RunStream` goroutine started by `NewClient`; no need to cancel the parent context separately.
* **CI improvements** - tests run on merge requests; publish is restricted to `main`-branch tags.

## v0.5.0 - 2026-06-01

* **Write API** - `SetSecret`, `DeleteSecret`, `DeleteSecretVersion` for programmatic secret management. secret keys only; public keys get `ErrPublicKeyRestricted` immediately without a network call.
* **`ErrRateLimited`** - new sentinel for HTTP 429 on write endpoints.

## v0.4.0 - 2026-05-28

* **Path prefix update** - API endpoints moved from `/api/v1/` to `/v1/`; update your `BaseURL` from `nexus.westyx.dev` to `<slug>.westyx.dev`.
* **Quarantine handling** *(v0.4.0)* - new `429` quarantine response pauses sync until expiry. `OnQuarantined(reason, expiresAt)` observer callback added.
* **`Retry-After`-aware SSE 429 handling** - `RunStream` now sleeps the indicated delay (clamped `[5 s, 5 min]`) and reconnects automatically when the server returns `429 Too Many Requests` with a parseable `Retry-After` header. The reconnect does NOT count toward the transport-failure threshold.


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