Rust Client SDK
Relevant source files
The following files were used as context for generating this wiki page:
The Rust Client SDK provides native client bindings for Crucible-modeled services. It consists of a complete Cargo SDK package that integrates with a shared runtime to handle service interactions.
Sources: README.md:14-14, AGENTS.md:58-59
Overview and Architecture
The Rust Client SDK architecture separates generated service-specific code from shared runtime logic. The crucible-codegen-rust crate transforms lowered IR into a native Rust package. The generated package depends on crucible-client-runtime-rust, which manages lower-level concerns like transport, retries, error decoding, and pagination.
Sources: AGENTS.md:58-61, README.md:14-14
Data and Logic Flow
The following diagram illustrates the relationship between the generator, the generated SDK, and the runtime.
The diagram shows how the generator consumes the IR to produce a package that relies on the client runtime for remote communication.
Sources: AGENTS.md:58-61, crates/crucible-codegen-rust/tests/client_package.rs:77-85
SDK Package Structure
A generated Rust Client SDK is emitted as a standard Cargo package. This package includes configuration files, source code, and documentation tailored for the specific service.
Emitted Files
| File Path | Description |
|---|---|
Cargo.toml | Defines package metadata and the dependency on the client runtime. |
src/lib.rs | Contains the generated client struct, operation traits, and models. |
.rustfmt.toml | Provides formatting rules for the generated source code. |
README.md | Provides human-readable installation and usage instructions. |
AGENTS.md | Provides terse instructions for coding agents. |
Sources: crates/crucible-codegen-rust/tests/client_package.rs:77-85
Runtime Dependency
The generator automatically manages the dependency on crucible-client-runtime-rust. It pins the version based on the Crucible Git revision from which the generator was built. This ensures compatibility between the generated bindings and the runtime behavior.
Sources: crates/crucible-codegen-rust/tests/client_package.rs:133-150, AGENTS.md:104-105
Naming and Type Mapping
The SDK converts model identifiers into Rust-compatible names. This process ensures that model names that are reserved keywords in Rust do not cause compilation errors.
Identifier Conversion Rules
- Fields and Functions: Converted to
snake_case. Acronyms are treated as words (e.g.,HTTPStatusbecomeshttp_status). - Variants: Converted to
UpperCamelCase. - Keywords: Prefixed with
r#(raw identifiers) if they match Rust keywords liketype,match, ormove. - Reserved Names: Names like
self,super,crate, andSelfare escaped by appending an underscore (e.g.,self_).
Sources: crates/crucible-codegen-rust/src/names.rs:9-55, crates/crucible-codegen-rust/src/names.rs:135-155
Naming Collisions
The generator validates that model members do not collide after case conversion. For example, fooBar and foo_bar both resolve to foo_bar in Rust, which triggers a diagnostic error during generation.
Sources: crates/crucible-codegen-rust/src/names.rs:62-75
Documentation and Doc Links
Generated SDKs include integrated documentation using Rust's /// comment syntax. The system supports intra-doc links, allowing modeled types and operations to link to each other within the generated documentation.
Doc Link Resolution
The generator translates model-level doc links into Rust intra-doc links.
- Links from inside
mod modelormod errorsuse thesuper::prefix. - Links to operations on the client refer to the client struct methods.
- Internal API links are omitted or rendered as plain text in external audiences.
Sources: crates/crucible-codegen-rust/tests/doc_links.rs:56-75, crates/crucible-codegen-rust/src/names.rs:198-230
The sequence diagram represents the execution flow of a client operation, showing the delegation from the generated client to the shared runtime.
Sources: AGENTS.md:58-61, README.md:14-14
Usage and Implementation
A typical Rust Client SDK usage involves constructing a client with a Config and invoking operation methods.
Client Construction
The client is constructed using a configuration object that defines the endpoint and optional security tokens.
use weather_sdk::{Config, WeatherClient, Token};
let client = WeatherClient::new(
Config::new("https://api.example.com")
.token(Token::fixed("secret-token"))
);
Sources: crates/crucible-codegen-rust/tests/client_package.rs:260-264, crates/crucible-codegen-common/src/guide.rs:434-436
Model redacting
The generated models implement Debug and Display traits that automatically redact fields marked with the @sensitive trait in the model. This prevents accidental leakage of sensitive data in logs.
Sources: crates/crucible-codegen-rust/tests/client_package.rs:252-257, AGENTS.md:108-109
Summary
The Rust Client SDK is a generated, high-conformance library for interacting with Crucible services. It provides a native Rust experience through snake_case method names, UpperCamelCase enum variants, and integrated intra-doc links. By leveraging a shared runtime, the SDK maintains consistent behavior for retries, transport, and error handling across different service implementations.