pub struct Session { /* private fields */ }
Expand description
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§
source§impl Session
impl Session
sourcepub async fn new<Auth: AuthType + 'static>(
auth_type: Auth
) -> Result<Session, Error>
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).
sourcepub fn new_with_authenticated_client(client: AuthenticatedClient) -> Session
pub fn new_with_authenticated_client(client: AuthenticatedClient) -> Session
Create a new session with a given authenticated client.
sourcepub async fn new_with_client<Auth: AuthType + 'static>(
client: Client,
auth_type: Auth
) -> Result<Session, Error>
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).
sourcepub async fn from_config<S: AsRef<str>>(cloud_name: S) -> Result<Session, Error>
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:
- Password and HTTP basic authentication, as well as no authentication.
- Users, projects and domains by name.
- Region names (for password authentication).
- Custom TLS CA certificates.
- Profiles from
clouds-public.yaml
. - Credentials from
secure.yaml
.
A non-exhaustive list of features that are not currently supported:
- Users, projects and domains by ID.
- Adapter options, such as interfaces, default API versions and endpoint overrides.
- Other authentication methods.
- Identity v2.
sourcepub async fn from_env() -> Result<Session, Error>
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 tov3token
ifOS_TOKEN
is provided otherwise topassword
).OS_AUTH_URL
forpassword
andv3token
,OS_ENDPOINT
forhttp_basic
andnoop
.OS_USERNAME
andOS_PASSWORD
.OS_PROJECT_NAME
orOS_PROJECT_ID
.OS_USER_DOMAIN_NAME
orOS_USER_DOMAIN_ID
(defaults toDefault
).OS_PROJECT_DOMAIN_NAME
orOS_PROJECT_DOMAIN_ID
.OS_TOKEN
(forv3token
).OS_REGION_NAME
andOS_INTERFACE
.
sourcepub fn adapter<Srv>(&self, service: Srv) -> Adapter<Srv>
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);
sourcepub fn into_adapter<Srv>(self, service: Srv) -> Adapter<Srv>
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);
sourcepub fn client(&self) -> &AuthenticatedClient
pub fn client(&self) -> &AuthenticatedClient
Get a reference to the authenticated client in use.
sourcepub fn endpoint_filters(&self) -> &EndpointFilters
pub fn endpoint_filters(&self) -> &EndpointFilters
Endpoint filters in use.
sourcepub fn endpoint_filters_mut(&mut self) -> &mut EndpointFilters
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
.
sourcepub fn endpoint_overrides(&self) -> &HashMap<String, Url>
pub fn endpoint_overrides(&self) -> &HashMap<String, Url>
Endpoint overrides in use.
sourcepub fn endpoint_overrides_mut(&mut self) -> &mut HashMap<String, Url>
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
.
sourcepub async fn refresh(&mut self) -> Result<(), Error>
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.
sourcepub fn set_auth_type<Auth: AuthType + 'static>(&mut self, auth_type: Auth)
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
.
sourcepub fn set_endpoint_interface(&mut self, endpoint_interface: InterfaceType)
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
.
sourcepub fn set_endpoint_override<Svc: ServiceType>(
&mut self,
service: Svc,
url: Url
)
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
.
sourcepub fn set_region<T: Into<String>>(&mut self, region: T)
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
.
sourcepub fn with_auth_type<Auth: AuthType + 'static>(
self,
auth_method: Auth
) -> Session
pub fn with_auth_type<Auth: AuthType + 'static>( self, auth_method: Auth ) -> Session
Convert this session into one using the given authentication.
sourcepub fn with_endpoint_filters(self, endpoint_filters: EndpointFilters) -> Session
pub fn with_endpoint_filters(self, endpoint_filters: EndpointFilters) -> Session
Convert this session into one using the given endpoint filters.
sourcepub fn with_endpoint_interface(
self,
endpoint_interface: InterfaceType
) -> Session
pub fn with_endpoint_interface( self, endpoint_interface: InterfaceType ) -> Session
Convert this session into one using the given endpoint filters.
sourcepub fn with_endpoint_override<Srv: ServiceType>(
self,
service: Srv,
url: Url
) -> Session
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.
sourcepub fn with_endpoint_overrides(
self,
endpoint_overrides: HashMap<String, Url>
) -> Session
pub fn with_endpoint_overrides( self, endpoint_overrides: HashMap<String, Url> ) -> Session
Convert this session into one using the given endpoint overrides.
sourcepub fn with_region<T: Into<String>>(self, region: T) -> Session
pub fn with_region<T: Into<String>>(self, region: T) -> Session
Convert this session into one using the given region.
sourcepub async fn get_api_versions<Srv: ServiceType + Send>(
&self,
service: Srv
) -> Result<Option<(ApiVersion, ApiVersion)>, Error>
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");
}
sourcepub 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>,
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.
sourcepub async fn get_major_version<Srv>(
&self,
service: Srv
) -> Result<Option<ApiVersion>, Error>where
Srv: ServiceType + Send,
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.
sourcepub 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,
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?;
sourcepub async fn supports_api_version<Srv>(
&self,
service: Srv,
version: ApiVersion
) -> Result<bool, Error>where
Srv: ServiceType + Send,
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.
sourcepub fn request<Srv, I>(
&self,
service: Srv,
method: Method,
path: I
) -> ServiceRequestBuilder<Srv>where
Srv: ServiceType + Send,
I: IntoIterator,
I::Item: AsRef<str>,
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.
sourcepub fn get<Srv, I>(&self, service: Srv, path: I) -> ServiceRequestBuilder<Srv>where
Srv: ServiceType + Send + Clone,
I: IntoIterator,
I::Item: AsRef<str>,
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.
sourcepub 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,
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.
sourcepub fn post<Srv, I>(&self, service: Srv, path: I) -> ServiceRequestBuilder<Srv>where
Srv: ServiceType + Send + Clone,
I: IntoIterator,
I::Item: AsRef<str>,
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.
sourcepub fn put<Srv, I>(&self, service: Srv, path: I) -> ServiceRequestBuilder<Srv>where
Srv: ServiceType + Send + Clone,
I: IntoIterator,
I::Item: AsRef<str>,
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.
sourcepub fn delete<Srv, I>(
&self,
service: Srv,
path: I
) -> ServiceRequestBuilder<Srv>where
Srv: ServiceType + Send + Clone,
I: IntoIterator,
I::Item: AsRef<str>,
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.