# nv-redfish
`nv-redfish` is a modular Rust client stack for Redfish BMC management.
The project combines generated Redfish schema types with a small transport
abstraction and optional ergonomic wrappers for common Redfish services. The
main crate is intentionally feature-gated: enable the service and OEM support
your client needs, or use `std-redfish` for a broad standard Redfish build.
## Crates
- `nv-redfish-core`
- Transport-agnostic primitives and traits used by generated code.
- Includes `Bmc`, `EntityTypeRef`, `NavProperty<T>`, `Action<T, R>`,
`ODataId`, `ODataETag`, `ModificationResponse`, and Redfish session-create
response metadata.
- Provides common Redfish/OData value types such as date/time, duration,
UUID, decimal, task, action, and navigation-property helpers.
- Does not include an HTTP implementation.
- `nv-redfish-bmc-http`
- HTTP implementation of `nv_redfish_core::Bmc`.
- Provides `HttpBmc<C>`, `BmcCredentials`, ETag/cache handling, and the
`HttpClient` trait.
- The built-in reqwest client is behind the `reqwest` feature, enabled by
default for this crate.
- Supports custom default headers and session-token credential updates, so
callers can use either basic credentials or a Redfish `X-Auth-Token`.
- `nv-redfish`
- High-level Redfish API over generated schema types.
- Exposes `ServiceRoot` and feature-gated wrappers for services such as
accounts, chassis, systems, sessions, events, telemetry, and updates.
- Re-exports `nv-redfish-bmc-http` as `nv_redfish::bmc_http` when the
`bmc-http` feature is enabled.
- Generates only the schemas required by enabled features during build.
- Uses feature-gated patch helpers for vendor quirks and schema deviations
observed in real BMCs.
- `nv-redfish-bmc-mock`
- Test BMC implementation used by integration tests and examples.
- Provides expectation helpers for GET, PATCH, POST/create, DELETE, actions,
SSE, and Redfish session creation.
- `nv-redfish-csdl-compiler`
- CSDL/OData XML compiler and Rust code generator.
- Used by `nv-redfish` at build time to compile selected standard and OEM
Redfish schemas.
- Reads Redfish, Swordfish, and OEM CSDL/EDMX documents into a schema index,
resolves inheritance and references, compiles a reduced intermediate model,
optimizes it, and emits Rust.
- Compilation is rooted at service singletons such as `Service`, plus
feature-defined include patterns from `redfish/features.toml`.
- Navigation targets can be limited with wildcard entity-type patterns so
generated code contains only the reachable schema surface needed by the
selected features.
- Generates read, update, create, excerpt, action, enum, and typedef shapes
consumed by `nv-redfish`.
- CLI entry points:
- `Compile`: compile standard CSDL from a root singleton into a Rust file.
- `CompileOem`: compile OEM CSDL as root schemas while resolving references
from standard CSDL files.
## Feature Flags
`nv-redfish` has no default features.
Common feature groups:
- `bmc-http`: re-export `nv-redfish-bmc-http` from `nv_redfish::bmc_http`.
- `std-redfish`: enable a broad standard Redfish surface.
- Service features: `accounts`, `assembly`, `bios`, `boot-options`,
`chassis`, `computer-systems`, `ethernet-interfaces`, `event-service`,
`host-interfaces`, `log-services`, `managers`, `memory`,
`network-adapters`, `network-device-functions`, `pcie-devices`, `power`,
`power-supplies`, `processors`, `secure-boot`, `sensors`,
`session-service`, `storages`, `telemetry-service`, `thermal`,
`update-service`.
- OEM features: `oem-ami`, `oem-dell`, `oem-hpe`, `oem-lenovo`,
`oem-supermicro`, `oem-nvidia`, `oem-liteon`.
- OEM product features: `oem-nvidia-bluefield`, `oem-nvidia-baseboard`,
`oem-dell-attributes`.
For smaller binaries and faster builds, enable only the service and OEM
features your client needs.
## Minimal Example
`Cargo.toml`:
```toml
[dependencies]
nv-redfish = { version = "0.1", features = ["bmc-http"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
url = "2.5"
```
Rust:
```rust
use nv_redfish::bmc_http::reqwest::Client;
use nv_redfish::bmc_http::{BmcCredentials, CacheSettings, HttpBmc};
use nv_redfish::ServiceRoot;
use std::sync::Arc;
use url::Url;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let bmc = Arc::new(HttpBmc::new(
Client::new()?,
Url::parse("https://example.com")?,
BmcCredentials::new("admin".into(), "password".into()),
CacheSettings::default(),
));
let root = ServiceRoot::new(Arc::clone(&bmc)).await?;
println!("Vendor: {:?}", root.vendor());
println!("Product: {:?}", root.product());
println!("Redfish version: {:?}", root.redfish_version());
Ok(())
}
```
See `examples/readme-minimal` for this example as a workspace target.
See `examples/session-token` for Redfish SessionService authentication using
`X-Auth-Token`.
## How It Fits Together
1. Enable features on `nv-redfish`.
2. `redfish/build.rs` invokes `nv-redfish-csdl-compiler`.
3. The compiler reads `redfish/features.toml` plus selected CSDL XML schemas
and generates the schema module compiled into `nv-redfish`.
4. High-level wrappers use the generated types and the transport-agnostic
`Bmc` trait.
5. Applications provide a BMC implementation, commonly `HttpBmc<Client>` from
`nv-redfish-bmc-http`.
## Goals
- Keep the transport layer independent from the Redfish schema layer.
- Compile only the schema surface needed by enabled features.
- Support standard Redfish and selected OEM extensions.
- Keep vendor compatibility fixes isolated behind feature-gated patch helpers.
## License
See workspace `Cargo.toml`.
This project includes Redfish schema files from DMTF's
[Redfish-Publications repository](https://github.com/DMTF/Redfish-Publications/tree/main),
licensed under the
[BSD-3-Clause license](https://github.com/DMTF/Redfish-Publications/blob/main/LICENSE.md).
This project includes Swordfish schema files from SNIA's
[Swordfish-Publications repository](https://github.com/SNIA/Swordfish-Publications),
licensed under the
[BSD-3-Clause license](https://github.com/SNIA/Swordfish-Publications/blob/main/LICENSE).
## Contributing
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.