Crate s3 

Lean, modern, unofficial S3-compatible client for Rust.

Start here

If you are new to the crate, read these items in this order:

• Client for the async entry point
• BlockingClient for the blocking entry point
• Auth for signing strategy and credential loading
• api for request builders exposed from objects() and buckets()
• types for public request and response models
• providers for endpoint presets such as AWS, MinIO, and Cloudflare R2

Mental model

Most applications follow the same flow:

• Auth chooses how requests are signed.
• Client::builder(...) and BlockingClient::builder(...) capture endpoint, region, retry, TLS, and addressing policy.
• client.objects() and client.buckets() produce typed request builders for object and bucket operations.
• types contains the public request and response models you work with. Protocol XML mapping stays internal.
• Optional providers presets bootstrap common S3-compatible endpoints.

Quick start (async)

use s3::{Auth, Client};

let client = Client::builder("https://s3.example.com")?
    .region("us-east-1")
    .auth(Auth::from_env()?)
    .build()?;

let obj = client
    .objects()
    .get("my-bucket", "path/to/object.txt")
    .send()
    .await?;
let bytes = obj.bytes().await?;
println!("{} bytes", bytes.len());

Quick start (blocking)

use s3::{Auth, BlockingClient};

let client = BlockingClient::builder("https://s3.example.com")?
    .region("us-east-1")
    .auth(Auth::from_env()?)
    .build()?;

let obj = client.objects().get("my-bucket", "path/to/object.txt").send()?;
let bytes = obj.bytes()?;
println!("{} bytes", bytes.len());

Common tasks

• Download an object: api::GetObjectRequest
• Upload an object: api::PutObjectRequest
• List objects: api::ListObjectsV2Request
• Presign a request: api::PresignGetObjectRequest or types::PresignedRequest
• List buckets: api::ListBucketsRequest
• Manage bucket settings: api::PutBucketLifecycleRequest, api::PutBucketCorsRequest, api::PutBucketTaggingRequest, api::PutBucketEncryptionRequest

Feature visibility

Docs.rs builds this crate with all features enabled. Feature-gated items are labeled on their docs pages so you can tell whether an API requires async, blocking, providers, multipart, or one of the optional credential features.

Examples and docs

See the README and examples/README.md for a usage guide organized around auth, client builders, object and bucket services, TLS policy, and blocking variants.

Modules

apiasync or blocking

Service entry points and request builders. Service entry points and request builders.

providersproviders

Endpoint presets for common S3-compatible services. Endpoint presets for common S3-compatible services.

types

Shared request/response types. Public request and response types shared across operations.

Structs

BlockingClientblocking

Blocking S3 client.

BlockingClientBuilderblocking

Builder for BlockingClient.

CachedProviderasync or blocking

Cached credentials wrapper with refresh and throttling.

Clientasync

Async S3 client.

ClientBuilderasync

Builder for Client.

Credentials

Static access credentials with optional session token.

CredentialsSnapshot

Snapshot of credentials and optional expiration metadata.

Region

Region identifier used for signing.

Enums

AddressingStyle

How the bucket name is encoded into the request URL.

AsyncTlsRootStoreasync

Trust root selection for async HTTPS requests.

Auth

Authentication configuration for requests.

BlockingTlsRootStoreblocking

Trust root selection for blocking HTTPS requests.

CredentialsTlsRootStore

Trust root selection for credential-provider HTTPS requests (IMDS/STS).

Error

Error type for request building, transport, and API responses.

Traits

CredentialsProvider

Source of credential snapshots for request signing.

Type Aliases

DynCredentialsProvider

Shared credentials provider trait object.

Result

Library result type.