Skip to main content

Crate octelium

Crate octelium 

Source
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:

VariableMeaning
OCTELIUM_ACCESS_TOKENAn externally managed access token, used as-is.
OCTELIUM_ASSERTION_FILEA file holding a signed assertion, re-read on every authentication.
OCTELIUM_ASSERTIONA signed assertion.
OCTELIUM_AUTH_TOKENA 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

FeatureDefaultDescription
httpyesClient::http, an HTTP client for Octelium Services.
tls-native-rootsyesVerify Cluster certificates against the host’s certificate store.
tls-webpki-rootsnoVerify Cluster certificates against the bundled webpki roots.

Re-exports§

pub use crate::http::HttpAuthorizationPolicy;http
pub use crate::http::HttpClient;http
pub use crate::http::RequestBuilder;http
pub use octelium_apis as apis;
pub use tonic;
pub use reqwest;http

Modules§

httphttp
An authenticated HTTP client for Octelium Services.

Structs§

AccessToken
A bearer token for the Octelium Cluster and its known expiration time.
AccessTokenProviderFn
An AccessTokenProvider backed by a closure.
Assertion
Authenticates with a signed assertion, such as an OIDC ID token.
AuthenticatedChannel
A Channel that attaches the Octelium access token to every call, authenticating or refreshing the Cluster Session as needed.
AuthenticationToken
Exchanges a Credential authentication token for a Cluster Session.
Client
An authenticated Octelium Cluster client.
ClientBuilder
Builds a Client.
SessionChannel
A Channel that attaches the Cluster Session’s refresh token, used for the authentication API itself.
StaticAccessToken
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§

AccessTokenProvider
Supplies externally managed Octelium access tokens.
Authenticator
Creates a Cluster Session.

Type Aliases§

AuthServiceClient
The authentication client handed to an Authenticator.
BoxError
A type-erased error, used wherever an application supplies its own failure, such as an Authenticator or an AccessTokenProvider.
Result
A Result alias for this crate.