Struct osauth::Session

pub struct Session { /* private fields */ }

An OpenStack API session.

The session object serves as a wrapper around an authentication type, providing convenient methods to make HTTP requests and work with microversions.

Note

All clones of one session share the same authentication and endpoint cache. Use with_auth_type to detach a session.

Implementations

impl Session

pub async fn new<Auth: AuthType + 'static>( auth_type: Auth ) -> Result<Session, Error>

Create a new session with a given authentication plugin.

The resulting session will use the default endpoint interface (usually, public).

pub fn new_with_authenticated_client(client: AuthenticatedClient) -> Session

Create a new session with a given authenticated client.

pub async fn new_with_client<Auth: AuthType + 'static>( client: Client, auth_type: Auth ) -> Result<Session, Error>

Create a new session with a given authentication plugin and an HTTP client.

The resulting session will use the default endpoint interface (usually, public).

pub async fn from_config<S: AsRef<str>>(cloud_name: S) -> Result<Session, Error>

Create a Session from a clouds.yaml configuration file.

See openstacksdk documentation for detailed information on the format of the configuration file.

The cloud_name argument is a name of the cloud entry to use.

Supported features are:

1. Password and HTTP basic authentication, as well as no authentication.
2. Users, projects and domains by name.
3. Region names (for password authentication).
4. Custom TLS CA certificates.
5. Profiles from clouds-public.yaml.
6. Credentials from secure.yaml.

A non-exhaustive list of features that are not currently supported:

1. Users, projects and domains by ID.
2. Adapter options, such as interfaces, default API versions and endpoint overrides.
3. Other authentication methods.
4. Identity v2.

pub async fn from_env() -> Result<Session, Error>

Create a Session from environment variables.

Supports the following authentication types: password, v3token, http_basic and noop.

Understands the following variables:

• OS_CLOUD (equivalent to calling from_config with the given cloud).
• OS_AUTH_TYPE (defaults to v3token if OS_TOKEN is provided otherwise to password).
• OS_AUTH_URL for password and v3token, OS_ENDPOINT for http_basic and noop.
• OS_USERNAME and OS_PASSWORD.
• OS_PROJECT_NAME or OS_PROJECT_ID.
• OS_USER_DOMAIN_NAME or OS_USER_DOMAIN_ID (defaults to Default).
• OS_PROJECT_DOMAIN_NAME or OS_PROJECT_DOMAIN_ID.
• OS_TOKEN (for v3token).
• OS_REGION_NAME and OS_INTERFACE.

pub fn adapter<Srv>(&self, service: Srv) -> Adapter<Srv>

Create an adapter for the specific service type.

The new Adapter will share the same authentication and will initially use the same endpoint interface (although it can be changed later without affecting the Session).

If you don’t need the Session any more, using into_adapter is a bit more efficient.

let session = osauth::Session::from_env().await?;
let adapter = session.adapter(osauth::services::COMPUTE);

pub fn into_adapter<Srv>(self, service: Srv) -> Adapter<Srv>

Create an adapter for the specific service type.

The new Adapter will share the same authentication and will initially use the same endpoint interface (although it can be changed later without affecting the Session).

This method is a bit more efficient than adapter since it does not involve cloning internal structures.

let adapter = osauth::Session::from_env()
    .await?
    .into_adapter(osauth::services::COMPUTE);

pub fn auth_type(&self) -> &dyn AuthType

Get a reference to the authentication type in use.

pub fn client(&self) -> &AuthenticatedClient

Get a reference to the authenticated client in use.

pub fn endpoint_filters(&self) -> &EndpointFilters

Endpoint filters in use.

pub fn endpoint_filters_mut(&mut self) -> &mut EndpointFilters

Modify endpoint filters.

This call clears the cached service information for this Session. It does not, however, affect clones of this Session.

pub fn endpoint_overrides(&self) -> &HashMap<String, Url>

Endpoint overrides in use.

pub fn endpoint_overrides_mut(&mut self) -> &mut HashMap<String, Url>

Modify endpoint overrides.

This call clears the cached service information for this Session. It does not, however, affect clones of this Session.

pub async fn refresh(&mut self) -> Result<(), Error>

Update the authentication and purges cached endpoint information.

Warning

Authentication will also be updated for clones of this Session, since they share the same authentication object.

pub fn set_auth_type<Auth: AuthType + 'static>(&mut self, auth_type: Auth)

Set a new authentication for this Session.

This call clears the cached service information for this Session. It does not, however, affect clones of this Session.

pub fn set_endpoint_interface(&mut self, endpoint_interface: InterfaceType)

A convenience call to set an endpoint interface.

This call clears the cached service information for this Session. It does not, however, affect clones of this Session.

pub fn set_endpoint_override<Svc: ServiceType>( &mut self, service: Svc, url: Url )

A convenience call to set an endpoint override for one service.

This call clears the cached service information for this Session. It does not, however, affect clones of this Session.

pub fn set_region<T: Into<String>>(&mut self, region: T)

A convenience call to set a region.

This call clears the cached service information for this Session. It does not, however, affect clones of this Session.

pub fn with_auth_type<Auth: AuthType + 'static>( self, auth_method: Auth ) -> Session

Convert this session into one using the given authentication.

pub fn with_endpoint_filters(self, endpoint_filters: EndpointFilters) -> Session

Convert this session into one using the given endpoint filters.

pub fn with_endpoint_interface( self, endpoint_interface: InterfaceType ) -> Session

Convert this session into one using the given endpoint filters.

pub fn with_endpoint_override<Srv: ServiceType>( self, service: Srv, url: Url ) -> Session

Convert this session into one using the given endpoint override for the given service.

pub fn with_endpoint_overrides( self, endpoint_overrides: HashMap<String, Url> ) -> Session

Convert this session into one using the given endpoint overrides.

pub fn with_region<T: Into<String>>(self, region: T) -> Session

Convert this session into one using the given region.

pub async fn get_api_versions<Srv: ServiceType + Send>( &self, service: Srv ) -> Result<Option<(ApiVersion, ApiVersion)>, Error>

Get minimum/maximum API (micro)version information.

Returns None if the range cannot be determined, which usually means that microversioning is not supported.

let session = osauth::Session::from_env()
    .await
    .expect("Failed to create an identity provider from the environment");
let maybe_versions = session
    .get_api_versions(osauth::services::COMPUTE)
    .await?;
if let Some((min, max)) = maybe_versions {
    println!("The compute service supports versions {} to {}", min, max);
} else {
    println!("The compute service does not support microversioning");
}

pub async fn get_endpoint<Srv, I>( &self, service: Srv, path: I ) -> Result<Url, Error>where Srv: ServiceType + Send, I: IntoIterator + Send, I::Item: AsRef<str>,

Construct and endpoint for the given service from the path.

You won’t need to use this call most of the time, since all request calls can fetch the endpoint automatically.

pub async fn get_major_version<Srv>( &self, service: Srv ) -> Result<Option<ApiVersion>, Error>where Srv: ServiceType + Send,

Get the currently used major version from the given service.

Can return None if the service does not support API version discovery at all.

pub async fn pick_api_version<Srv, I>( &self, service: Srv, versions: I ) -> Result<Option<ApiVersion>, Error>where Srv: ServiceType + Send, I: IntoIterator<Item = ApiVersion> + Send,

Pick the highest API version supported by the service.

Returns None if none of the requested versions are available.

let session = osauth::Session::from_env()
    .await
    .expect("Failed to create an identity provider from the environment");
let candidates = [osauth::ApiVersion(1, 2), osauth::ApiVersion(1, 42)];
let maybe_version = session
    .pick_api_version(osauth::services::COMPUTE, candidates)
    .await?;

let request = session.get(osauth::services::COMPUTE, &["servers"]);
let response = if let Some(version) = maybe_version {
    println!("Using version {}", version);
    request.api_version(version)
} else {
    println!("Using the base version");
    request
}.send().await?;

pub async fn supports_api_version<Srv>( &self, service: Srv, version: ApiVersion ) -> Result<bool, Error>where Srv: ServiceType + Send,

Check if the service supports the API version.

pub fn request<Srv, I>( &self, service: Srv, method: Method, path: I ) -> ServiceRequestBuilder<Srv>where Srv: ServiceType + Send, I: IntoIterator, I::Item: AsRef<str>,

Make an HTTP request to the given service.

The service argument is an object implementing the ServiceType trait. Some known service types are available in the services module.

The path argument is a URL path without the service endpoint (e.g. /servers/1234). For an empty path, NO_PATH can be used.

If api_version is set, it is send with the request to enable a higher API version. Otherwise the base API version is used. You can use pick_api_version to choose an API version to use.

The result is a ServiceRequestBuilder that can be customized further. Error checking and response parsing can be done using functions from the request module.

let session = osauth::Session::from_env()
    .await
    .expect("Failed to create an identity provider from the environment");
let response = session
    .request(osauth::services::COMPUTE, reqwest::Method::HEAD, &["servers", "1234"])
    .send()
    .await?;
println!("Response: {:?}", response);

This is the most generic call to make a request. You may prefer to use more specific get, post, put or delete calls instead.

pub fn get<Srv, I>(&self, service: Srv, path: I) -> ServiceRequestBuilder<Srv>where Srv: ServiceType + Send + Clone, I: IntoIterator, I::Item: AsRef<str>,

Start a GET request.

See request for an explanation of the parameters.

pub async fn get_json<Srv, I, T>( &self, service: Srv, path: I ) -> Result<T, Error>where Srv: ServiceType + Send + Clone, I: IntoIterator, I::Item: AsRef<str>, T: DeserializeOwned + Send,

Fetch a JSON using the GET request.

use osauth::common::IdAndName;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct ServersRoot {
    pub servers: Vec<IdAndName>,
}

let session = osauth::Session::from_env()
    .await
    .expect("Failed to create an identity provider from the environment");

let servers: ServersRoot = session
    .get_json(osauth::services::COMPUTE, &["servers"])
    .await?;
for srv in servers.servers {
    println!("ID = {}, Name = {}", srv.id, srv.name);
}

See Session::request for an explanation of the parameters.

Note that this call does not handle pagination. Use Session::get in combination with ServiceRequestBuilder::fetch_paginated instead.

pub fn post<Srv, I>(&self, service: Srv, path: I) -> ServiceRequestBuilder<Srv>where Srv: ServiceType + Send + Clone, I: IntoIterator, I::Item: AsRef<str>,

Start a POST request.

See request for an explanation of the parameters.

pub fn put<Srv, I>(&self, service: Srv, path: I) -> ServiceRequestBuilder<Srv>where Srv: ServiceType + Send + Clone, I: IntoIterator, I::Item: AsRef<str>,

Start a PUT request.

See request for an explanation of the parameters.

pub fn delete<Srv, I>( &self, service: Srv, path: I ) -> ServiceRequestBuilder<Srv>where Srv: ServiceType + Send + Clone, I: IntoIterator, I::Item: AsRef<str>,

Start a DELETE request.

See request for an explanation of the parameters.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Srv> From<Adapter<Srv>> for Session

fn from(value: Adapter<Srv>) -> Session

Converts to this type from the input type.