Struct osauth::Adapter

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

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 fn new<Auth: AuthType + 'static>(
    auth_type: Auth,
    service: Srv
) -> Adapter<Srv>

Create a new adapter with a given authentication plugin.

pub 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 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 default_api_version(&self) -> Option<ApiVersion>

Default API version used when no version is specified.

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_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 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>(
    mut self: Self,
    auth_method: Auth
) -> Adapter<Srv>

Convert this adapter into one using the given authentication.

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

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

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

Convert this adapter into one using the given endpoint filters.

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

Convert this adapter into one using the given endpoint filters.

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)
    .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,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

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>,
    I::IntoIter: 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)
    .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?;
if let Some(version) = maybe_version {
    println!("Using version {}", version);
} else {
    println!("Using the base version");
}
let response = adapter.get(&["servers"], maybe_version).await?;

pub async fn supports_api_version(
    &self,
    version: ApiVersion
) -> Result<bool, Error>

Check if the service supports the API version.

pub async fn request<I>(
    &self,
    method: Method,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<RequestBuilder, Error> where
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Make an HTTP request.

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.

let adapter = osauth::Adapter::from_env(osauth::services::COMPUTE)
    .expect("Failed to create an identity provider from the environment");
let response = osauth::request::send_checked(
    adapter
        .request(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<I>(
    &self,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    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<I, T>(
    &self,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<T, Error> where
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    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)
    .expect("Failed to create an identity provider from the environment");
let servers: ServersRoot = adapter
    .get_json(&["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_paginated<I, T>(
    &self,
    path: I,
    api_version: Option<ApiVersion>,
    limit: Option<usize>,
    starting_with: Option<<T as Resource>::Id>
) -> Result<impl Stream<Item = Result<T, Error>>, Error> where
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    T: Resource + Unpin,
    <T as Resource>::Root: Into<Vec<T>> + Send, 

Fetch a paginated list of JSON objects using the GET request.

use futures::pin_mut;
use futures::stream::TryStreamExt;
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>,
}

// This implementatin defines the relationship between the root resource and its items.
impl osauth::stream::Resource for Server {
    type Id = String;
    type Root = ServersRoot;
    fn resource_id(&self) -> Self::Id {
        self.id.clone()
    }
}

// This is another required part of the pagination contract.
impl From<ServersRoot> for Vec<Server> {
    fn from(value: ServersRoot) -> Vec<Server> {
        value.servers
    }
}

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

let servers = adapter
    .get_json_paginated::<_, Server>(&["servers"], None, None, None)
    .await?;

pin_mut!(servers);
while let Some(srv) = servers.try_next().await? {
    println!("ID = {}, Name = {}", srv.id, srv.name);
}

See request for an explanation of the parameters.

pub async fn get_json_query<I, Q, T>(
    &self,
    path: I,
    query: Q,
    api_version: Option<ApiVersion>
) -> Result<T, Error> where
    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_json_query_paginated<I, Q, T>(
    &self,
    path: I,
    query: Q,
    api_version: Option<ApiVersion>,
    limit: Option<usize>,
    starting_with: Option<<T as Resource>::Id>
) -> Result<impl Stream<Item = Result<T, Error>>, Error> where
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send,
    Q: Serialize + Send,
    T: Resource + Unpin,
    <T as Resource>::Root: Into<Vec<T>> + Send, 

Fetch a paginated list of JSON objects 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<I, Q>(
    &self,
    path: I,
    query: Q,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    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<I, T>(
    &self,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    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<I, T, R>(
    &self,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<R, Error> where
    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<I, T>(
    &self,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    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<I>(
    &self,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    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<I, T, R>(
    &self,
    path: I,
    body: T,
    api_version: Option<ApiVersion>
) -> Result<R, Error> where
    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<I>(
    &self,
    path: I,
    api_version: Option<ApiVersion>
) -> Result<Response, Error> where
    I: IntoIterator,
    I::Item: AsRef<str>,
    I::IntoIter: Send, 

Issue a DELETE request.

See request for an explanation of the parameters.

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

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

Performs the conversion.