Struct osauth::Session

pub struct Session { /* fields omitted */ }

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 fn new<Auth: AuthType + 'static>(auth_type: Auth) -> Session

Create a new session with a given authentication plugin.

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

pub 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.
2. Users, projects and domains by name.
3. Region names.
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 fn from_env() -> Result<Session, Error>

Create a Session from environment variables.

Understands the following variables:

• OS_CLOUD (equivalent to calling from_config with the given cloud).
• OS_AUTH_TYPE (supports password and http_basic, defaults to password).
• OS_AUTH_URL for password, OS_ENDPOINT for http_basic.
• 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_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()
    .expect("Failed to create an identity provider from the environment");
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 session = osauth::Session::from_env()
    .expect("Failed to create an identity provider from the environment");
let adapter = session.into_adapter(osauth::services::COMPUTE);

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

Get a reference to the authentication type 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 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 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()
    .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,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

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>,
    I::IntoIter: 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()
    .expect("Failed to create an identity provider from the environment");
let candidates = vec![osauth::ApiVersion(1, 2), osauth::ApiVersion(1, 42)];
let maybe_version = session
    .pick_api_version(osauth::services::COMPUTE, candidates)
    .await?;
if let Some(version) = maybe_version {
    println!("Using version {}", version);
} else {
    println!("Using the base version");
}
let response = session
    .get(osauth::services::COMPUTE, &["servers"], maybe_version)
    .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 async fn request<Srv, I, '_>(
    &'_ self,
    service: Srv,
    method: Method,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<RequestBuilder, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

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 RequestBuilder 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()
    .expect("Failed to create an identity provider from the environment");
let response = osauth::request::send_checked(
    session
        .request(osauth::services::COMPUTE, reqwest::Method::HEAD, &["servers", "1234"], None)
        .await?
    )
    .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 async fn get<Srv, I, '_>(
    &'_ self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Issue a GET request.

See request for an explanation of the parameters.

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

Fetch a JSON using the GET request.

use osproto::common::IdAndName;
use serde::Deserialize;

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

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

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

See request for an explanation of the parameters.

pub async fn get_json_query<Srv, I, Q, T, '_>(
    &'_ self,
    service: Srv,
    path: I,
    query: Q,
    api_version: Option<ApiVersion>
) -> Result<T, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    Q: Serialize + Send,
    T: DeserializeOwned + Send, 

Fetch a JSON using the GET request with a query.

See reqwest crate documentation for how to define a query. See request for an explanation of the parameters.

pub async fn get_query<Srv, I, Q, '_>(
    &'_ self,
    service: Srv,
    path: I,
    query: Q,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    Q: Serialize + Send, 

Issue a GET request with a query

See reqwest crate documentation for how to define a query. See request for an explanation of the parameters.

pub async fn post<Srv, I, T, '_>(
    &'_ self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    T: Serialize + Send, 

POST a JSON object.

The body argument is anything that can be serialized into JSON.

See request for an explanation of the other parameters.

pub async fn post_json<Srv, I, T, R, '_>(
    &'_ self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<R, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    T: Serialize + Send,
    R: DeserializeOwned + Send, 

POST a JSON object and receive a JSON back.

The body argument is anything that can be serialized into JSON.

See request for an explanation of the other parameters.

pub async fn put<Srv, I, T, '_>(
    &'_ self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    T: Serialize + Send, 

PUT a JSON object.

The body argument is anything that can be serialized into JSON.

See request for an explanation of the other parameters.

pub async fn put_empty<Srv, I, '_>(
    &'_ self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Issue an empty PUT request.

See request for an explanation of the parameters.

pub async fn put_json<Srv, I, T, R, '_>(
    &'_ self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<R, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    T: Serialize + Send,
    R: DeserializeOwned + Send, 

PUT a JSON object and receive a JSON back.

The body argument is anything that can be serialized into JSON.

See request for an explanation of the other parameters.

pub async fn delete<Srv, I, '_>(
    &'_ self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Issue 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

Performs the conversion.

impl From<Session> for SyncSession

fn from(value: Session) -> SyncSession

Performs the conversion.

impl From<SyncSession> for Session

fn from(value: SyncSession) -> Session

Performs the conversion.