Azure Core (Rust)

azure_core is the foundation crate underneath every modern azure_* client library in the Azure SDK for Rust. Instead of each service crate (Key Vault, Storage, Identity, and dozens more) reinventing how it sends HTTP requests, retries failures, deserializes responses, or represents credentials, they all depend on azure_core for that shared behavior. Learning its ClientOptions, Response<T>, Pager<T>, and Poller<T> types once means you already know how to work with any Azure Rust client library.

The crate wraps a thinner internal typespec_client_core layer with Azure-specific conventions: consistent error types with HTTP status and service error codes attached, long-running operation polling, paginated result iteration as async streams, and a pluggable HTTP transport (reqwest by default, with a ureq example showing how to swap it). It also carries the tracing/telemetry attribute macros (#[client], #[function]) that Azure SDK crates use to emit consistent distributed-tracing spans.

What You Get

• A ClientOptions-based pattern for configuring retries, logging, and transport that every Azure service client shares
• Response<T> for accessing both a deserialized model and the raw HTTP status/headers/body from any service call
• Pager<T> and Poller<T> for consuming paginated list endpoints and long-running operations as async streams
• A consistent Error type carrying HTTP status and service-specific error codes instead of ad-hoc error handling per crate
• A pluggable HttpClient trait (reqwest by default) so you can swap the transport without touching client code
• Tracing/telemetry macros (#[client], #[function], #[new], #[subclient]) for consistent distributed-tracing spans across Azure SDK crates

Common Use Cases

• Implicit dependency: installed automatically when you add any azure_* client crate (Identity, Storage, Key Vault) rather than added directly
• Implementing a custom Azure client library that needs to follow the same design guidelines as Microsoft’s own SDK crates
• Replacing the default reqwest HTTP transport with a custom HttpClient implementation (e.g. ureq) across all Azure clients at once
• Iterating paginated Azure API responses (list_secret_properties, etc.) as a single async stream instead of manual page-by-page requests
• Polling long-running Azure operations (deployments, resource provisioning) via a uniform Poller<T> API instead of custom retry loops

Under The Hood

Architecture azure_core sits as a thin, Azure-flavored layer over an internal typespec_client_core crate: src/http/mod.rs re-exports pipeline, pager, poller, and request types from that lower layer while adding Azure-specific pieces in src/credentials.rs (the constant-time-compare Secret type) and src/error/error_response.rs (mapping Azure’s standard error-response JSON onto ErrorKind::HttpResponse). The crate is organized as flat public modules (cloud, credentials, error, hmac, http, tracing) rather than deep nesting, and a private::Sealed trait pattern is used to prevent external implementations of certain traits — a common Rust idiom for controlled extensibility. Because dozens of downstream azure_* crates depend on this one, any breaking change to Response<T>, Pager<T>, or ClientOptions ripples across the entire SDK, which is why the crate is still versioned as a 1.x beta series and gated behind #![deny(missing_debug_implementations, nonstandard_style)] plus #![warn(missing_docs)] lint rules.

Tech Stack Built on async Rust: tokio as the default async runtime, reqwest (with rustls, gzip, and deflate feature flags) as the default HTTP client, serde/serde_json for model (de)serialization, and futures for the Pager/Poller stream abstractions. Optional features let consumers swap HMAC signing between openssl- and pure-Rust (sha2/hmac)-backed implementations, and an xml feature pulls in XML (de)serialization for the Azure services that still use it. The crate depends on sibling workspace crates azure_core_macros (attribute macros) and typespec/typespec_client_core (the lower-level HTTP/serialization primitives), all pinned via Cargo workspace inheritance so the whole SDK moves in lockstep.

Code Quality Tests live both inline (#[test]/#[tokio::test] across roughly a dozen sites in src/) and in a small tests/ integration directory (core_error_http_response.rs, plus a readme.rs doctest-style check that keeps the README’s code samples compiling). Benchmarks are a first-class citizen — five separate Criterion benchmark targets under benches/ cover serialization, HTTP transport, and response collection, unusual rigor for a shared SDK crate. Error handling is fully typed through azure_core::Error/ErrorKind rather than string errors, unsafe_code is denied crate-wide, and CI-visible perf.yml/perf-tests.yml configs show performance regressions are tracked continuously, not just checked ad hoc.

What Makes It Unique Rather than each Azure Rust client crate independently deciding how to page results, poll long-running operations, or represent credentials, azure_core centralizes those decisions once and lets dozens of azure_* crates inherit them — the README explicitly frames this as “learn once, use everywhere” across the whole SDK surface. The Secret type’s constant-time equality comparison for credential values, and the design guideline-driven consistency between this crate and the equivalent Go, .NET, Python, and Java Azure Core libraries, reflect an SDK built to a cross-language specification rather than organically grown.