s3-wire 0.1.0

An async, streaming S3-compatible client for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

//! Async, streaming S3-compatible client with explicit resource bounds.
//!
//! `s3-wire` provides typed object operations, SigV4 signing, replay-aware
//! retries, streaming downloads, and primitive or managed multipart uploads.
//! A client is configured for one endpoint, region, and bucket.
//!
//! # Quick start
//!
//! The default credential provider reads `AWS_ACCESS_KEY_ID`,
//! `AWS_SECRET_ACCESS_KEY`, and optional `AWS_SESSION_TOKEN`.
//!
//! ```no_run
//! use s3_wire::{
//!     ByteStream, Endpoint, GetObjectRequest, ObjectKey, PutObjectRequest, S3Client, S3Config,
//! };
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let region = "us-east-1";
//! let config = S3Config::builder()
//!     .endpoint(Endpoint::for_aws_region(region)?)
//!     .region(region)
//!     .bucket("artifact-bucket")
//!     .build()?;
//! let client = S3Client::new(config)?;
//!
//! let key = ObjectKey::new("reports/latest.json")?;
//! client
//!     .put_object(PutObjectRequest::new(
//!         key.clone(),
//!         ByteStream::from_bytes(br#"{"status":"complete"}"#.as_slice()),
//!     ))
//!     .await?;
//!
//! let download = client.get_object(GetObjectRequest::new(key)).await?;
//! let mut destination = tokio::io::sink();
//! download.body.write_to(&mut destination).await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Upload and download behavior
//!
//! - [`ByteStream::from_bytes`] and [`ByteStream::from_path`] are replayable.
//! - [`ByteStream::from_stream`] is one-shot and requires an exact length and
//!   SHA-256 digest.
//! - [`ResponseStream`] applies backpressure and validates declared length,
//!   configured deadlines, and supported checksums while the body is consumed.
//! - [`S3Client::multipart_upload`] bounds concurrent part buffers and owns
//!   abort cleanup after S3 creates an upload.
//!
//! # Errors
//!
//! [`S3Error`] exposes a stable [`ErrorCategory`], service status and code,
//! request identifiers, retry classification, timeout phase, and any multipart
//! cleanup failure. Formatting remains redacted by default.
//!
//! # More documentation
//!
//! - [Architecture](https://github.com/runtrue/s3-rs/blob/main/docs/architecture.md)
//! - [S3 compatibility](https://github.com/runtrue/s3-rs/blob/main/docs/compatibility.md)
//! - [Security model](https://github.com/runtrue/s3-rs/blob/main/docs/security-model.md)
//! - [Examples](https://github.com/runtrue/s3-rs/blob/main/examples/README.md)

#![forbid(unsafe_code)]

pub mod client;
pub mod config;
pub mod credentials;
pub mod endpoint;
pub mod error;
pub mod operation;
pub mod retry;
pub mod stream;

#[cfg(feature = "fuzzing")]
#[doc(hidden)]
pub mod fuzzing;

mod protocol;
mod signing;
mod transport;

pub use client::S3Client;
pub use config::{AddressingStyle, S3Config, S3ConfigBuilder};
pub use credentials::{
    CachedCredentialsProvider, Credentials, CredentialsProvider, EnvironmentCredentialsProvider,
    StaticCredentialsProvider,
};
pub use endpoint::{Endpoint, EndpointUrl};
pub use error::{ErrorCategory, RetryClassification, S3Error, TimeoutPhase};
pub use operation::*;
pub use retry::RetryPolicy;
pub use stream::{ByteStream, ResponseStream};