Struct osauth::Adapter

pub struct Adapter<Srv> { /* private fields */ }

Adapter for a specific service.

An Adapter is very similar to a Session, but is tied to a specific service, and thus does not require passing a service argument to all calls.

Implementations

impl<Srv> Adapter<Srv>

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

Create a new adapter with a given authentication plugin.

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

Create a new adapter from a clouds.yaml configuration file.

See Session::from_config for details.

pub async fn from_env(service: Srv) -> Result<Adapter<Srv>, Error>

Create a new adapter with information from environment variables.

See Session::from_env for details.

pub fn from_session(session: Session, service: Srv) -> Adapter<Srv>

Create a new adapter from a Session.

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 Adapter. It does not, however, affect clones of this Adapter.

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 Adapter and its parent Session, since they share the same authentication object.

pub fn session(&self) -> &Session

Session used for this adapter.

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

Set a new authentication for this Adapter.

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

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 Adapter. It does not, however, affect clones of this Adapter.

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

Convert this adapter into one using the given authentication.

pub fn with_endpoint_filters( self, endpoint_filters: EndpointFilters ) -> Adapter<Srv>

Convert this adapter into one using the given endpoint filters.

pub fn with_endpoint_interface( self, endpoint_interface: InterfaceType ) -> Adapter<Srv>

Convert this adapter into one using the given endpoint filters.

impl<Srv> Adapter<Srv>where Srv: VersionedService + Send,

pub fn default_api_version(&self) -> Option<ApiVersion>

Default API version used when no version is specified.

pub fn set_default_api_version(&mut self, api_version: Option<ApiVersion>)

Set the default API version.

This version will be used when no version is specified. No checks are done against this version inside of this call. If it is not valid, the subsequent request calls will fail.

pub fn with_default_api_version( self, api_version: Option<ApiVersion> ) -> Adapter<Srv>

Convert this adapter into one using the given default API version.

impl<Srv: ServiceType + Send + Clone> Adapter<Srv>

pub async fn get_api_versions( &self ) -> 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 adapter = osauth::Adapter::from_env(osauth::services::COMPUTE)
    .await
    .expect("Failed to create an identity provider from the environment");
let maybe_versions = adapter
    .get_api_versions()
    .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<I>(&self, path: I) -> Result<Url, Error>where I: IntoIterator + Send, I::Item: AsRef<str>,

Construct an endpoint 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(&self) -> Result<Option<ApiVersion>, Error>

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<I>( &self, versions: I ) -> Result<Option<ApiVersion>, Error>where 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 adapter = osauth::Adapter::from_env(osauth::services::COMPUTE)
    .await
    .expect("Failed to create an identity provider from the environment");
let candidates = vec![osauth::ApiVersion(1, 2), osauth::ApiVersion(1, 42)];
let maybe_version = adapter
    .pick_api_version(candidates)
    .await?;

let request = adapter.get(&["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( &self, version: ApiVersion ) -> Result<bool, Error>

Check if the service supports the API version.

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

Make an HTTP request.

The path argument is a URL path without the service endpoint (e.g. /servers/1234).

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 adapter = osauth::Adapter::from_env(osauth::services::COMPUTE)
    .await
    .expect("Failed to create an identity provider from the environment");
let response = adapter
    .request(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<I>(&self, path: I) -> ServiceRequestBuilder<Srv>where I: IntoIterator, I::Item: AsRef<str>,

Start a GET request.

See request for an explanation of the parameters.

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

Fetch a JSON using the GET request.

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 adapter = osauth::Adapter::from_env(osauth::services::COMPUTE)
    .await
    .expect("Failed to create an identity provider from the environment");
let servers: ServersRoot = adapter
    .get_json(&["servers"])
    .await?;
for srv in servers.servers {
    println!("ID = {}, Name = {}", srv.id, srv.name);
}

See request for an explanation of the parameters.

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

Start a POST request.

See request for an explanation of the parameters.

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

Start a PUT request.

See request for an explanation of the parameters.

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

Start a DELETE request.

See request for an explanation of the parameters.

Trait Implementations

impl<Srv: Clone> Clone for Adapter<Srv>

fn clone(&self) -> Adapter<Srv>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Srv: Debug> Debug for Adapter<Srv>

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.