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.

Methods

impl Session

pub fn new<Auth: AuthType + 'static>(auth_method: Auth) -> Session

Create a new session with a given authentication plugin.

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

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

Get a reference to the authentication type in use.

pub fn endpoint_interface(&self) -> &Option<String>

Endpoint interface in use (if any).

pub fn refresh(&mut self) -> impl Future<Item = (), Error = Error> + Send

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_method: 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<S>(&mut self, endpoint_interface: S) where
    S: Into<String>, 

Set endpoint interface to use.

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_interface<S>(self, endpoint_interface: S) -> Session where
    S: Into<String>, 

Convert this session into one using the given endpoint interface.

pub fn get_api_versions<Srv: ServiceType + Send>(
    &self,
    service: Srv
) -> impl Future<Item = Option<(ApiVersion, ApiVersion)>, Error = Error> + Send

Get minimum/maximum API (micro)version information.

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

use futures::Future;

let session =
    osauth::from_env().expect("Failed to create an identity provider from the environment");
let future = session
    .get_api_versions(osauth::services::COMPUTE)
    .map(|maybe_versions| {
        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 fn get_endpoint<Srv, I>(
    &self,
    service: Srv,
    path: I
) -> impl Future<Item = Url, Error = Error> + Send 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 fn get_major_version<Srv: ServiceType + Send>(
    &self,
    service: Srv
) -> impl Future<Item = Option<ApiVersion>, Error = Error> + 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 fn pick_api_version<Srv, I>(
    &self,
    service: Srv,
    versions: I
) -> impl Future<Item = Option<ApiVersion>, Error = Error> + Send 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.

use futures::Future;

let session =
    osauth::from_env().expect("Failed to create an identity provider from the environment");
let candidates = vec![osauth::ApiVersion(1, 2), osauth::ApiVersion(1, 42)];
let future = session
    .pick_api_version(osauth::services::COMPUTE, candidates)
    .and_then(|maybe_version| {
        if let Some(version) = maybe_version {
            println!("Using version {}", version);
        } else {
            println!("Using the base version");
        }
        session.get(osauth::services::COMPUTE, &["servers"], maybe_version)
    });

pub fn supports_api_version<Srv: ServiceType + Send>(
    &self,
    service: Srv,
    version: ApiVersion
) -> impl Future<Item = bool, Error = Error> + Send

Check if the service supports the API version.

pub fn request<Srv, I>(
    &self,
    service: Srv,
    method: Method,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = RequestBuilder, Error = Error> + Send 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).

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.

use futures::Future;
use reqwest::Method;

let session =
    osauth::from_env().expect("Failed to create an identity provider from the environment");
let future = session
    .request(osauth::services::COMPUTE, Method::HEAD, &["servers", "1234"], None)
    .then(osauth::request::send_checked)
    .map(|response| {
        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 start_get<Srv, I>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = RequestBuilder, Error = Error> + Send where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Start a GET request.

Use this call if you need some advanced features of the resulting RequestBuilder. Otherwise use:

• get to issue a generic GET without a query.
• get_query to issue a generic GET with a query.
• get_json to issue GET and parse a JSON result.
• get_json_query to issue GET with a query and parse a JSON result.

See request for an explanation of the parameters.

pub fn get<Srv, I>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = Response, Error = Error> + Send 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 fn get_json<Srv, I, T>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = T, Error = Error> + Send 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 futures::Future;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct Server {
    pub id: String,
    pub name: String,
}

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

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

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

See request for an explanation of the parameters.

pub fn get_json_query<Srv, I, Q, T>(
    &self,
    service: Srv,
    path: I,
    query: Q,
    api_version: Option<ApiVersion>
) -> impl Future<Item = T, Error = Error> + Send 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 fn get_query<Srv, I, Q>(
    &self,
    service: Srv,
    path: I,
    query: Q,
    api_version: Option<ApiVersion>
) -> impl Future<Item = Response, Error = Error> + Send 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 fn start_post<Srv, I>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = RequestBuilder, Error = Error> + Send where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Start a POST request.

See request for an explanation of the parameters.

pub fn post<Srv, I, T>(
    &self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> impl Future<Item = Response, Error = Error> + Send 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 fn post_json<Srv, I, T, R>(
    &self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> impl Future<Item = R, Error = Error> + Send 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 fn start_put<Srv, I>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = RequestBuilder, Error = Error> + Send where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Start a PUT request.

See request for an explanation of the parameters.

pub fn put<Srv, I, T>(
    &self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> impl Future<Item = Response, Error = Error> + Send 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 fn put_empty<Srv, I>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = Response, Error = Error> + Send 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 fn put_json<Srv, I, T, R>(
    &self,
    service: Srv,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> impl Future<Item = R, Error = Error> + Send 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 fn start_delete<Srv, I>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = RequestBuilder, Error = Error> + Send where
    Srv: ServiceType + Send + Clone,
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Start a DELETE request.

See request for an explanation of the parameters.

pub fn delete<Srv, I>(
    &self,
    service: Srv,
    path: I,
    api_version: Option<ApiVersion>
) -> impl Future<Item = Response, Error = Error> + Send 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.