Expand description
The official Rust SDK for Octelium.
A Client authenticates to an Octelium Cluster, keeps the resulting
Session fresh, and hands out ready-to-use gRPC and HTTP clients:
use octelium::Client;
use octelium_apis::corev1;
let client = Client::builder()
.domain("example.com")
.authenticator(octelium::AuthenticationToken::new("<authentication token>"))
.build()
.await?;
let users = client
.core_v1()
.list_user(corev1::ListUserOptions::default())
.await?
.into_inner();
for user in users.items {
println!("{}", user.metadata.unwrap_or_default().name);
}§Credentials
With no explicit credentials the Client reads them from the environment, in this order:
| Variable | Meaning |
|---|---|
OCTELIUM_ACCESS_TOKEN | An externally managed access token, used as-is. |
OCTELIUM_ASSERTION_FILE | A file holding a signed assertion, re-read on every authentication. |
OCTELIUM_ASSERTION | A signed assertion. |
OCTELIUM_AUTH_TOKEN | A Credential authentication token. |
OCTELIUM_DOMAIN, OCTELIUM_API_ENDPOINT and OCTELIUM_TLS_SERVER_NAME
configure the Cluster and its endpoint. An application can supply its own
Authenticator or AccessTokenProvider instead, which is how
authentication methods added after this release are used.
§Sessions
The Client obtains an access token on the first call that needs one, and
replaces it on demand shortly before it expires. Concurrent callers share one
in-flight authentication. A Session created from a reusable credential,
such as an assertion, is re-created after it expires; one created from a
one-time authentication token is not, and the Client then returns
Error::SessionExpired.
§Cloning and shutdown
Client is cheap to clone and safe to share across tasks: every clone
shares one Session, one token cache and an API channel. Managed Sessions
additionally use a separate auth channel. Create one per Cluster for the
lifetime of the process.
Client::close cancels operations, releases owned credentials and
transports, and makes later calls fail with Error::Closed.
Client::shutdown also waits for authentication workers to stop.
§Features
| Feature | Default | Description |
|---|---|---|
http | yes | Client::http, an HTTP client for Octelium Services. |
tls-native-roots | yes | Verify Cluster certificates against the host’s certificate store. |
tls-webpki-roots | no | Verify Cluster certificates against the bundled webpki roots. |
Re-exports§
pub use crate::http::HttpAuthorizationPolicy;httppub use crate::http::HttpClient;httppub use crate::http::RequestBuilder;httppub use octelium_apis as apis;pub use tonic;pub use reqwest;http
Modules§
- http
http - An authenticated HTTP client for Octelium Services.
Structs§
- Access
Token - A bearer token for the Octelium Cluster and its known expiration time.
- Access
Token Provider Fn - An
AccessTokenProviderbacked by a closure. - Assertion
- Authenticates with a signed assertion, such as an OIDC ID token.
- Authenticated
Channel - A
Channelthat attaches the Octelium access token to every call, authenticating or refreshing the Cluster Session as needed. - Authentication
Token - Exchanges a Credential authentication token for a Cluster Session.
- Client
- An authenticated Octelium Cluster client.
- Client
Builder - Builds a
Client. - Session
Channel - A
Channelthat attaches the Cluster Session’s refresh token, used for the authentication API itself. - Static
Access Token - One externally managed access token with no known expiration time.
Enums§
- Error
- The errors returned by this crate.
Constants§
- METADATA_
KEY_ AUTH - The gRPC metadata key carrying the Octelium access token.
- METADATA_
KEY_ REFRESH_ TOKEN - The gRPC metadata key carrying a Cluster Session’s refresh token.
Traits§
- Access
Token Provider - Supplies externally managed Octelium access tokens.
- Authenticator
- Creates a Cluster Session.
Type Aliases§
- Auth
Service Client - The authentication client handed to an
Authenticator. - BoxError
- A type-erased error, used wherever an application supplies its own failure,
such as an
Authenticatoror anAccessTokenProvider. - Result
- A
Resultalias for this crate.