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

# Rust SDK - Installation

> Install the Westyx Nexus Rust SDK via cargo add.

The Rust SDK is published to [crates.io](https://crates.io/crates/westyx-nexus) as `westyx-nexus`. There is **no custom registry** - `cargo` resolves the crate directly from crates.io.

## Install

```sh theme={null}
cargo add westyx-nexus
```

This adds the latest version to your `Cargo.toml` automatically. Alternatively, add it manually:

```toml theme={null}
[dependencies]
westyx-nexus = "0.10.1-beta.1"
```

Then import the crate in your code:

```rust theme={null}
use westyx_nexus::{NexusClient, NexusConfig, NexusError};
```

## Requirements

* **Rust 1.75** or newer
* Network access to `crates.io` (or a mirror) for installation, and to `<your-slug>.westyx.dev` at runtime

## Dependencies

The SDK brings in a small, focused set of dependencies:

| Crate              | Version | Purpose                                     |
| ------------------ | ------- | ------------------------------------------- |
| `ureq`             | `2.x`   | Synchronous HTTP client - no tokio required |
| `serde`            | `1.x`   | JSON serialisation / deserialisation        |
| `serde_json`       | `1.x`   | JSON value type (`serde_json::Value`)       |
| `thiserror`        | `1.x`   | Derive macro for `NexusError`               |
| `percent-encoding` | `2.x`   | URL encoding for secret key segments        |

No async runtime (`tokio`, `async-std`) is pulled in. The SDK is synchronous and works in any Rust program regardless of whether you use async or not.

## Using alongside async runtimes

The SDK does not require an async runtime, but it works fine in async applications. `NexusClient` is `Clone + Send + Sync`, so you can pass clones into async tasks:

```rust theme={null}
// In an axum or actix-web handler, clone the client and move it in:
let client = client.clone();
tokio::spawn(async move {
    let val = client.get_config("some.key");
    // ...
});
```

All SDK calls are blocking. If you need to call them from an async context without blocking the executor, wrap in `tokio::task::spawn_blocking`:

```rust theme={null}
let client = client.clone();
let secret = tokio::task::spawn_blocking(move || {
    client.get_secret("stripe.key")
}).await??;
```

In practice, cache reads (`get_config`, `get_flag`, `get_secret`) complete in microseconds, so blocking the executor for those is usually acceptable.

## Verifying installation

```sh theme={null}
cargo tree -p westyx-nexus
```

Should print the crate and its transitive dependency tree. If `westyx-nexus` does not appear, check your `Cargo.toml` for the correct spelling.

## Verifying connectivity

Before writing any code, confirm your endpoint and API key work with a plain `curl`:

```sh theme={null}
curl -s \
  -H "X-Nexus-API-Key: wxs_..." \
  https://your-service.westyx.dev/v1/sync
```

A valid response returns a JSON snapshot with your `configs`, `secrets`, and `flags`. An `HTTP 401` means the key is wrong; `HTTP 404` means the slug is wrong.

To watch the live SSE stream:

```sh theme={null}
curl -N \
  -H "X-Nexus-API-Key: wxs_..." \
  -H "Accept: text/event-stream" \
  https://your-service.westyx.dev/v1/stream
```

You should see `event:resync` arrive within a second. Press `Ctrl+C` to stop.

## Troubleshooting

<Warning>
  The crate name is `westyx-nexus` (hyphen-separated). The Rust import uses underscores: `use westyx_nexus::...`. This is standard Cargo behaviour - the crate name on crates.io uses hyphens, the Rust identifier uses underscores.
</Warning>

* **`error[E0432]: unresolved import`** - ensure the dependency is in `Cargo.toml` and you have run `cargo build` or `cargo check` at least once.
* **`could not find 'westyx-nexus' in the registry`** - check network access to `crates.io`, or run `cargo update` to refresh the index.
* **Compilation error on Rust \< 1.75** - upgrade your toolchain: `rustup update stable`.