Azure Core shared client library for Rust

azure_core provides shared primitives, abstractions, and helpers for modern Rust Azure SDK client libraries. These libraries follow the Azure SDK Design Guidelines for Rust and can typically be identified by package and namespaces names starting with azure_, e.g. azure_identity.

azure_core allows client libraries to expose common functionality in a consistent fashion so that once you learn how to use these APIs in one client library, you will know how to use them in other client libraries.

Source code | Package (crates.io) | API Reference Documentation

Getting started

Typically, you will not need to install azure_core; it will be installed for you when you install one of the client libraries using it. In case you want to install it explicitly - to implement your own client library, for example - you can find the package on crates.io.

Key concepts

The main shared concepts of azure_core - and Azure SDK libraries using azure_core - include:

• Configuring service clients, e.g. configuring retries, logging (ClientOptions).
• Accessing HTTP response details (Response<T>).
• Paging and asynchronous streams (Pager<T>).
• Errors from service requests in a consistent fashion. (azure_core::Error).
• Customizing requests (ClientOptions).
• Abstractions for representing Azure SDK credentials. (TokenCredentials).

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guidelines). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Handling errors | Iterating through pages of resources | Waiting on long-running operations | Replacing the HTTP client | Replacing the async runtime

Features

• debug: enables extra information for developers e.g., emitting all fields in std::fmt::Debug implementation.
• decimal: enables support for rust_decimal::Decimal type.
• derive: enable derive macros e.g., SafeDebug.
• hmac_openssl: enables HMAC signing using openssl. If both hmac_openssl and hmac_rust are enabled, hmac_openssl is used.
• hmac_rust: enables HMAC signing using rust-native libraries sha2 and hmac. If both hmac_openssl and hmac_rust are enabled, hmac_openssl is used.
• reqwest (default): enables and sets reqwest as the default HttpClient.
• reqwest_deflate (default): enables deflate compression for reqwest.
• reqwest_gzip (default): enables gzip compression for reqwest.
• reqwest_native_tls (default): enables reqwest's native-tls feature, which uses schannel on Windows and openssl elsewhere.
• tokio: enables and sets tokio as the default async runtime.
• wasm_bindgen: enables the async runtime for WASM.
• xml: enables XML support.

Enabling dependencies' features

We define features to avoid dependencies which may be unnecessary for some applications or even some client libraries e.g., some Azure services do not support the accept-encoding request header nor send content-encoding back so there's no need to add reqwest_gzip by default for all client libraries. We also want to support developers that want to use additional features of some dependencies like reqwest or even replace some dependencies completely like reqwest or tokio to use different HTTP clients or async runtimes.

We do not define features to provide parity with all dependencies' features since the resolver will unify features e.g., you can add reqwest's system-proxy feature without making any changes to Azure SDK dependencies:

[dependencies]
azure_identity = "1"
azure_security_keyvault_secrets = "1"
reqwest = { version = "0.12.23", features = ["system-proxy"] }

Similarly, you can choose to support reqwest::Client but use rustls-tls with a different TLS provider by disabling our default features and adding only what you need, such as our reqwest feature just to enable the HttpClient trait implementation on reqwest::Client and add a dependency on reqwest with the feature you want:

[dependencies]
azure_core = { version = "1", default-features = false, features = ["reqwest"] }
azure_identity = { version = "1", default-features = false }
azure_security_keyvault_secrets = { version = "1", default-features = false }
reqwest = { version = "0.12.23", features = ["rustls-tls-webpki-roots"] }

You could even completely replace reqwest and provide your own HttpClient implementation. See an example below.

NOTE: The debug feature may expose PII and/or secrets to logs or tracing spans which would normally be redacted.

Examples

NOTE: Samples in this file apply only to packages that follow Azure SDK Design Guidelines. Names of such packages typically start with azure_.

Configuring service clients using ClientOptions

Azure SDK client libraries typically expose one or more service client types that are the main starting points for calling corresponding Azure services. You can easily find these client types as their names end with the word Client. For example, SecretClient can be used to call the Key Vault service and interact with secrets, and KeyClient can be used to access Key Vault service cryptographic keys.

These client types can be instantiated by calling a simple new function that takes various configuration options.These options are passed as a parameter that extends ClientOptions class exposed by azure_core. Various service specific options are usually added to its subclasses, but a set of SDK-wide options are available directly on ClientOptions.

use azure_core::http::ClientOptions;
use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::{SecretClient, SecretClientOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let credential = DeveloperToolsCredential::new(None)?;

    let options = SecretClientOptions {
        api_version: "7.5".to_string(),
        ..Default::default()
    };

    let client = SecretClient::new(
        "https://<your-key-vault-name>.vault.azure.net/",
        credential.clone(),
        Some(options),
    )?;

    Ok(())
}

Accessing HTTP response details using Response<T>

Service clients have methods that can be used to call Azure services. We refer to these client methods as service methods. Service methods return a shared azure_core type Response<T> where T is either a Model type or a ResponseBody representing a raw stream of bytes. This type provides access to both the deserialized result of the service call, and to the details of the HTTP response returned from the server.

use azure_core::http::Response;
use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::{models::Secret, SecretClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // create a client
    let credential = DeveloperToolsCredential::new(None)?;
    let client = SecretClient::new(
        "https://<your-key-vault-name>.vault.azure.net/",
        credential.clone(),
        None,
    )?;

    // call a service method, which returns Response<T>
    let response = client.get_secret("secret-name", None).await?;

    // Response<T> has two main accessors:
    // 1. The `into_body()` function consumes self to deserialize into a model type
    let secret = response.into_body()?;

    // get response again because it was moved in above statement
    let response: Response<Secret> = client.get_secret("secret-name", None).await?;

    // 2. The deconstruct() method for accessing all the details of the HTTP response
    let (status, headers, body) = response.deconstruct();

    // for example, you can access HTTP status
    println!("Status: {}", status);

    // or the headers
    for (header_name, header_value) in headers.iter() {
        println!("{}: {}", header_name.as_str(), header_value.as_str());
    }

    Ok(())
}

Handling errors

When a service call fails, the returned Result will contain an Error. The Error type provides a status property with an HTTP status code and an error_code property with a service-specific error code.

use azure_core::{error::ErrorKind, http::{Response, StatusCode}};
use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::SecretClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // create a client
    let credential = DeveloperToolsCredential::new(None)?;
    let client = SecretClient::new(
        "https://<your-key-vault-name>.vault.azure.net/",
        credential.clone(),
        None,
    )?;

    match client.get_secret("secret-name", None).await {
        Ok(secret) => println!("Secret: {:?}", secret.into_body()?.value),
        Err(e) => match e.kind() {
            ErrorKind::HttpResponse { status, error_code, .. } if *status == StatusCode::NotFound => {
                // handle not found error
                if let Some(code) = error_code {
                    println!("ErrorCode: {}", code);
                } else {
                    println!("Secret not found, but no error code provided.");
                }
            },
            _ => println!("An error occurred: {e:?}"),
        },
    }

    Ok(())
}

Consuming service methods returning Pager<T>

If a service call returns multiple values in pages, it should return Result<Pager<T>> as a result. You can iterate all items from all pages.

use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::{ResourceExt, SecretClient};
use futures::TryStreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // create a client
    let credential = DeveloperToolsCredential::new(None)?;
    let client = SecretClient::new(
        "https://<your-key-vault-name>.vault.azure.net/",
        credential.clone(),
        None,
    )?;

    // get a stream of items
    let mut pager = client.list_secret_properties(None)?;

    // poll the pager until there are no more SecretListResults
    while let Some(secret) = pager.try_next().await? {
        // get the secret name from the ID
        let name = secret.resource_id()?.name;
        println!("Found secret with name: {}", name);
    }

    Ok(())
}

To instead iterate over all pages, call into_pages() on the returned Pager.

use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::{ResourceExt, SecretClient};
use futures::TryStreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // create a client
    let credential = DeveloperToolsCredential::new(None)?;
    let client = SecretClient::new(
        "https://<your-key-vault-name>.vault.azure.net/",
        credential.clone(),
        None,
    )?;

    // get a stream of pages
    let mut pager = client.list_secret_properties(None)?.into_pages();

    // poll the pager until there are no more SecretListResults
    while let Some(secrets) = pager.try_next().await? {
        let secrets = secrets.into_body()?.value;
        // loop through secrets in SecretsListResults
        for secret in secrets {
            // get the secret name from the ID
            let name = secret.resource_id()?.name;
            println!("Found secret with name: {}", name);
        }
    }

    Ok(())
}

Consuming service methods returning Poller<T>

If a service call may take a while to process, it should return Result<Poller<T>> as a result, representing a long-running operation (LRO). The Poller<T> implements futures::Stream so you can asynchronously iterate over each status monitor update:

use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_certificates::{
    CertificateClient,
    models::{CreateCertificateParameters, CertificatePolicy, X509CertificateProperties, IssuerParameters},
};
use futures::stream::TryStreamExt as _;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let credential = DeveloperToolsCredential::new(None)?;
    let client = CertificateClient::new(
        "https://your-key-vault-name.vault.azure.net/",
        credential.clone(),
        None,
    )?;

    // Create a self-signed certificate.
    let policy = CertificatePolicy {
        x509_certificate_properties: Some(X509CertificateProperties {
            subject: Some("CN=DefaultPolicy".into()),
            ..Default::default()
        }),
        issuer_parameters: Some(IssuerParameters {
            name: Some("Self".into()),
            ..Default::default()
        }),
        ..Default::default()
    };
    let body = CreateCertificateParameters {
        certificate_policy: Some(policy),
        ..Default::default()
    };

    // Wait for the certificate operation to complete.
    // The Poller implements futures::Stream and automatically waits between polls.
    let mut poller = client.begin_create_certificate("certificate-name", body.try_into()?, None)?;
    while let Some(operation) = poller.try_next().await? {
        let operation = operation.into_body()?;
        match operation.status.as_deref().unwrap_or("unknown") {
            "inProgress" => continue,
            "completed" => {
                let target = operation.target.ok_or("expected target")?;
                println!("Created certificate {}", target);
                break;
            },
            status => Err(format!("operation terminated with status {status}"))?,
        }
    }

    Ok(())
}

If you just want to wait until the Poller<T> is complete and get the last status monitor, you can await wait():

use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_certificates::{
    CertificateClient,
    models::{CreateCertificateParameters, CertificatePolicy, X509CertificateProperties, IssuerParameters},
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let credential = DeveloperToolsCredential::new(None)?;
    let client = CertificateClient::new(
        "https://your-key-vault-name.vault.azure.net/",
        credential.clone(),
        None,
    )?;

    // Create a self-signed certificate.
    let policy = CertificatePolicy {
        x509_certificate_properties: Some(X509CertificateProperties {
            subject: Some("CN=DefaultPolicy".into()),
            ..Default::default()
        }),
        issuer_parameters: Some(IssuerParameters {
            name: Some("Self".into()),
            ..Default::default()
        }),
        ..Default::default()
    };
    let body = CreateCertificateParameters {
        certificate_policy: Some(policy),
        ..Default::default()
    };

    // Wait for the certificate operation to complete and get the last status monitor.
    let operation = client
        .begin_create_certificate("certificate-name", body.try_into()?, None)?
        .wait()
        .await?
        // Deserialize the CertificateOperation:
        .into_body()?;

    if matches!(operation.status, Some(status) if status == "completed") {
        let target = operation.target.ok_or("expected target")?;
        println!("Created certificate {}", target);
    }

    Ok(())
}

Awaiting wait() will only fail if the HTTP status code does not indicate successfully fetching the status monitor.

Replacing the HTTP client

Though azure_core uses reqwest for its default HTTP client, you can replace it with either a customized reqwest::Client or an entirely different HTTP client.

Reqwest

We define a reqwest feature that provides a blanket implementation of our HttpClient trait for reqwest::Client and depends on the reqwest crate. If you just want to configure a reqwest::Client to use different options including a different TLS provider, optionally add a dependency on reqwest and enable whichever feature you want:

cargo add reqwest -F rustls-tls-native-roots

You can then disable default features of any of the Azure SDK crates and add a dependency on azure_core with the reqwest feature for the blanket HttpClient implementation:

cargo add azure_core --no-default-features -F reqwest

You should end up with a Cargo.toml that looks something like:

[dependencies]
azure_core = { version = "1", default-features = false, features = ["reqwest"] }
azure_identity = { version = "1", default-features = false }
azure_security_keyvault_secrets = { version = "1", default-features = false }
reqwest = { version = "0.12.23", default-features = false, features = [
    "deflate",
    "gzip",
    "rustls-tls-native-roots",
] }

In many cases with reqwest, importing features may be enough. See their documentation for more information. If you do need to write code to customize the reqwest::Client, you can pass it in ClientOptions to our client libraries:

use azure_core::http::{ClientOptions, Transport};
use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::{SecretClient, SecretClientOptions};
use std::sync::Arc;

let http_client = Arc::new(reqwest::ClientBuilder::new().gzip(true).build().unwrap());

let options = SecretClientOptions {
    client_options: ClientOptions {
        transport: Some(Transport::new(http_client)),
        ..Default::default()
    },
    ..Default::default()
};

let credential = DeveloperToolsCredential::new(None).unwrap();
let client = SecretClient::new(
    "https://your-key-vault-name.vault.azure.net/",
    credential.clone(),
    Some(options),
)
.unwrap();

Other HTTP client

If you do not want to take a dependency on reqwest at all - perhaps because you want to use a different async runtime other than tokio - you can implement the HttpClient (recommended) or the Policy trait yourself.

Similar to customizing reqwest above, you can disable default features for Azure SDK crates. In this example where we do not want a dependency on reqwest at all, we need to import azure_core with no default features only to implement HttpClient so that your Cargo.toml looks something like:

[dependencies]
azure_core = { version = "1", default-features = false }
azure_identity = { version = "1", default-features = false }
azure_security_keyvault_secrets = { version = "1", default-features = false }
http = "1"
ureq = { version = "3", default-features = false, features = [
    "gzip",
    "native-tls",
] }

Then we need to implement HttpClient for another HTTP client like ureq:

use azure_core::{error::{ErrorKind, ResultExt as _}, http::{HttpClient, BufResponse, Request}};
use ureq::tls::{TlsConfig, TlsProvider};

#[derive(Debug)]
struct Agent(ureq::Agent);

impl Default for Agent {
    fn default() -> Self {
        Self(
            ureq::Agent::config_builder()
                .https_only(true)
                .tls_config(
                    TlsConfig::builder()
                        .provider(TlsProvider::NativeTls)
                        .build(),
                )
                .build()
                .into(),
        )
    }
}

#[async_trait::async_trait]
impl HttpClient for Agent {
    async fn execute_request(&self, request: &Request) -> azure_core::Result<BufResponse> {
        let request: ::http::request::Request<Vec<u8>> = todo!("convert our request into their request");
        let response = self
            .0
            .run(request)
            .with_context_fn(ErrorKind::Io, || "failed to send request")?;

        Ok(todo!("convert their response into our response"))
    }
}

See the example for a full sample implementation.

After you've implemented HttpClient, you pass it in ClientOptions to our client libraries as shown for reqwest above.

Replacing the async runtime

Internally, the Azure SDK uses either the tokio async runtime (with the tokio feature), or it implements asynchronous functionality using functions in the std namespace.

If your application uses a different asynchronous runtime, you can replace the asynchronous runtime used for internal functions by providing your own implementation of the azure_core::async_runtime::AsyncRuntime trait.

You provide the implementation by calling the set_async_runtime() API:

use azure_core::{async_runtime::{
     set_async_runtime, AsyncRuntime, TaskFuture, SpawnedTask},
     time::Duration};
use std::sync::Arc;
use futures::FutureExt;

struct CustomRuntime;

impl AsyncRuntime for CustomRuntime {
    fn spawn(&self, f: TaskFuture) -> SpawnedTask {
      unimplemented!("Custom spawn not implemented");
    }
    fn sleep(&self, duration: Duration) -> TaskFuture {
      unimplemented!("Custom sleep not implemented");
    }
  }

  set_async_runtime(Arc::new(CustomRuntime)).expect("Failed to set async runtime");

There can only be one async runtime set in a given process, so attempts to set the async runtime multiple times will fail.

Troubleshooting

Logging

To help protected end users from accidental Personally-Identifiable Information (PII) from leaking into logs or traces, models' default implementation of core::fmt::Debug formats as non-exhaustive structure tuple e.g.,

use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::{ResourceExt, SecretClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // create a client
    let credential = DeveloperToolsCredential::new(None)?;
    let client = SecretClient::new(
        "https://<your-key-vault-name>.vault.azure.net/",
        credential.clone(),
        None,
    )?;

    // get a secret
    let secret = client.get_secret("secret-name", None)
        .await?
        .into_body()?;

    println!("{secret:#?}");

    Ok(())
}

By default this will print:

Secret { .. }

Though not recommended for production, you can enable normal core::fmt::Debug formatting complete with field names and values by enabling the debug feature of azure_core e.g.,

cargo add azure_core -F debug

Known issues

Hang when invoking multiple HTTP operations using the default HTTP transport

Some customers have reported hangs when using the default reqwest HTTP transport. The issue is tracked in this GitHub issue. The recommended workaround is to disable connection pooling in a custom reqwest transport.

If you are encountering this issue, you can construct an HttpClient which disables HTTP connection pooling and set that as the transport in any ClientOptions used to configure your Azure SDK clients:

use std::sync::Arc;
use azure_core::http::{HttpClient, ClientOptions, Transport};
use azure_security_keyvault_secrets::SecretClientOptions;

let client = Arc::new(
    ::reqwest::ClientBuilder::new()
        // Note that reqwest does not support `pool_max_idle_per_host` on WASM.
        .pool_max_idle_per_host(0)
        .build()
        .expect("failed to build `reqwest` client"),
);

let options = SecretClientOptions {
    client_options: ClientOptions {
        transport: Some(Transport::new(client.clone())),
        ..Default::default()
    },
    ..Default::default()
};

Note that implementing this workaround can result in a significant performance slowdown depending on your scenario.

Contributing

See the CONTRIBUTING.md for details on building, testing, and contributing to these libraries.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://opensource.microsoft.com/cla/.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the [Microsoft Open Source Code of Conduct]. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.