s3_wire/
lib.rs

1//! Async, streaming S3-compatible client with explicit resource bounds.
2//!
3//! `s3-wire` provides typed object operations, SigV4 signing, replay-aware
4//! retries, streaming downloads, and primitive or managed multipart uploads.
5//! A client is configured for one endpoint, region, and bucket.
6//!
7//! # Quick start
8//!
9//! The default credential provider reads `AWS_ACCESS_KEY_ID`,
10//! `AWS_SECRET_ACCESS_KEY`, and optional `AWS_SESSION_TOKEN`.
11//!
12//! ```no_run
13//! use s3_wire::{
14//!     ByteStream, Endpoint, GetObjectRequest, ObjectKey, PutObjectRequest, S3Client, S3Config,
15//! };
16//!
17//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
18//! let region = "us-east-1";
19//! let config = S3Config::builder()
20//!     .endpoint(Endpoint::for_aws_region(region)?)
21//!     .region(region)
22//!     .bucket("artifact-bucket")
23//!     .build()?;
24//! let client = S3Client::new(config)?;
25//!
26//! let key = ObjectKey::new("reports/latest.json")?;
27//! client
28//!     .put_object(PutObjectRequest::new(
29//!         key.clone(),
30//!         ByteStream::from_bytes(br#"{"status":"complete"}"#.as_slice()),
31//!     ))
32//!     .await?;
33//!
34//! let download = client.get_object(GetObjectRequest::new(key)).await?;
35//! let mut destination = tokio::io::sink();
36//! download.body.write_to(&mut destination).await?;
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! # Upload and download behavior
42//!
43//! - [`ByteStream::from_bytes`] and [`ByteStream::from_path`] are replayable.
44//! - [`ByteStream::from_stream`] is one-shot and requires an exact length and
45//!   SHA-256 digest.
46//! - [`ResponseStream`] applies backpressure and validates declared length,
47//!   configured deadlines, and supported checksums while the body is consumed.
48//! - [`S3Client::multipart_upload`] bounds concurrent part buffers and owns
49//!   abort cleanup after S3 creates an upload.
50//!
51//! # Errors
52//!
53//! [`S3Error`] exposes a stable [`ErrorCategory`], service status and code,
54//! request identifiers, retry classification, timeout phase, and any multipart
55//! cleanup failure. Formatting remains redacted by default.
56//!
57//! # More documentation
58//!
59//! - [Architecture](https://github.com/runtrue/s3-rs/blob/main/docs/architecture.md)
60//! - [S3 compatibility](https://github.com/runtrue/s3-rs/blob/main/docs/compatibility.md)
61//! - [Security model](https://github.com/runtrue/s3-rs/blob/main/docs/security-model.md)
62//! - [Examples](https://github.com/runtrue/s3-rs/blob/main/examples/README.md)
63
64#![forbid(unsafe_code)]
65
66pub mod client;
67pub mod config;
68pub mod credentials;
69pub mod endpoint;
70pub mod error;
71pub mod operation;
72pub mod retry;
73pub mod stream;
74
75#[cfg(feature = "fuzzing")]
76#[doc(hidden)]
77pub mod fuzzing;
78
79mod protocol;
80mod signing;
81mod transport;
82
83pub use client::S3Client;
84pub use config::{AddressingStyle, S3Config, S3ConfigBuilder};
85pub use credentials::{
86    CachedCredentialsProvider, Credentials, CredentialsProvider, EnvironmentCredentialsProvider,
87    StaticCredentialsProvider,
88};
89pub use endpoint::{Endpoint, EndpointUrl};
90pub use error::{ErrorCategory, RetryClassification, S3Error, TimeoutPhase};
91pub use operation::*;
92pub use retry::RetryPolicy;
93pub use stream::{ByteStream, ResponseStream};
s3_wire/lib.rs

s3_wire/
lib.rs
