Basaltic Rust SDK
Official typed, asynchronous Rust client for Basaltic. Covers 547 operations across 19 services: audit, billing, catalog, certificate, compute, DNS, email, IAM, KMS, load balancer, network, notifications, queue, quota, registry, secrets, storage, telemetry, and workspace.
Requires Rust 1.89 or newer and a Tokio runtime. HTTP connections use reqwest with Rustls. Clone a client to share its connection pool and cached credentials.
Install
[]
= { = "basaltic-sdk-rust", = "0.9" }
= { = "1", = ["macros", "rt-multi-thread"] }
= "0.3"
Quick start
Set BASALTIC_ACCESS_KEY_ID, BASALTIC_SECRET_ACCESS_KEY, and BASALTIC_REGION in
your environment, then:
use ;
use TryStreamExt;
async
Configuration and authentication
Config::from_env() reads BASALTIC_ACCESS_TOKEN (if present, it takes precedence
over the access-key pair), BASALTIC_REGION, BASALTIC_ACCOUNT_ID, BASALTIC_DOMAIN,
and BASALTIC_ENDPOINT_URL_<SERVICE>. Explicit Config values do not read the environment.
use ;
let client = new?;
# Ok::
Use Credentials::bearer(token)? for an existing bearer token, or
Credentials::Provider(Arc::new(provider)) with your own TokenProvider implementation.
Access-key credentials exchange via OAuth client credentials, cache the token, and
refresh it before expiry. Concurrent requests share one refresh; cancellation cannot
leave the cache locked. A rejected refreshable token is invalidated once per request.
Credentials::Anonymous permits only API operations declared unauthenticated.
The default timeout is 30 seconds and the maximum is four attempts. Endpoints must be HTTP(S) URLs without credentials, query strings, or fragments. HTTPS is used by default. Redirects, ambient proxies and cookie storage are disabled.
Typed requests and responses
Methods return owned request builders and perform no HTTP request until .send().await.
Path parameters are strings, JSON/form bodies use service-specific models, and query
parameters use the operation's *Query model. Models with required request fields
provide ::new(...); optional fields start omitted. Queries with no required fields
implement Default. Field names use Rust snake_case and retain their API names on the wire.
JSON calls return ApiResponse<T> containing the typed API envelope, status and
headers; .request_id() returns the request ID. String enums retain future values
as Unknown(String). Optional nullable fields use Option<Nullable<T>>: None
omits a field, Some(Nullable::Null) sends JSON null, and Some(Nullable::Value(x))
sends a value. Credential and token fields are redacted in model Debug output.
Use request options for account overrides, custom headers, timeouts and idempotency:
# use ;
# async
Reuse the same idempotency key for retries of one logical mutation. Transient failures
retry GET, HEAD, OPTIONS, PUT and DELETE, and other methods only with an idempotency
key. Backoff uses jitter and respects bounded Retry-After; a delay above the configured
maximum is returned as an error instead of retried early. Streaming uploads run once.
Managed headers, including Authorization and Idempotency-Key, cannot be overridden
through the custom header map. Supply API-required headers such as If-Match there.
Pagination and references
Paged requests support .send().await for one Page<T, Item>, .pages() for a lazy
stream of pages, and .items() for a lazy stream of resources. Pages retain their
typed response envelope alongside items and pagination metadata. Invalid or repeated
markers produce Error::Protocol rather than silently truncating a collection.
Supported resource getters offer *_by_reference(reference, scope) for UUIDs, CRNs
or unambiguous names. Scope models retain service-specific filters. Missing resources
return an API error with status 404; multiple matches return Error::AmbiguousReference.
Binary data and WebSockets
Storage uploads accept basaltic::Body (buffered bytes or a stream). Binary downloads
and HEAD calls return BinaryResponse, exposing headers, .chunk().await, .bytes().await
and .bytes_stream(). Consume or drop the response to release it. Dropping a request
future cancels that request.
WebSocket operations expose .prepare().await, returning a URL and authenticated
headers for your chosen WebSocket library. The SDK does not open a WebSocket itself.
Keep those headers private and disable redirects when connecting.
Errors
Match Error::Api(error) for status, API code, message, operation, request ID and
response headers. Authentication, transport, timeout, configuration, protocol and
ambiguous-reference failures have separate variants. Raw HTTP errors and authentication
response bodies are not retained in errors.
See the API reference for every operation and the Basaltic documentation for API concepts.
Development and security
This repository is a release snapshot for reference. Development happens internally; external pull requests and contributions are not accepted. Public GitHub Actions run formatting, lint, tests, documentation and package verification on the released source. Report vulnerabilities privately to security@basaltic.sh; see SECURITY.md.
Licensed under Apache-2.0.
KMS key rotation
The KMS client supports automatic rotation policies, on-demand rotation, paginated
rotation history, public keys by material version, and ciphertext rewrapping.
Reuse an idempotency key when retrying the same on-demand rotation. A 202
response represents accepted work; poll its rotation ID until it completes.
Persist the material version returned by signing and supply it when verifying
or retrieving a public key. Verification without a version remains compatible
with older signatures. Rotation retains existing key identities and historical
material; it does not rewrite stored ciphertext.
See KMS rotation for the lifecycle, permissions, and migration workflow.