s3-wire 0.3.1

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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

//! 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; cheap
//! bucket-scoped handles can share its connection pool.
//!
//! # 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, attempt count, retry stop reason,
//! 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)]

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

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

mod protocol;
mod signing;
mod transport;

pub use client::{DownloadToPathOutput, S3Client};
pub use config::{AddressingStyle, S3Config, S3ConfigBuilder};
#[cfg(feature = "aws-credentials")]
pub use credentials::{
    AwsDefaultCredentialsProvider, resolve_aws_region_for_profile, resolve_default_aws_region,
};
pub use credentials::{
    CachedCredentialsProvider, Credentials, CredentialsProvider, EnvironmentCredentialsProvider,
    StaticCredentialsProvider,
};
pub use endpoint::{AwsEndpointVariant, Endpoint};
pub use error::{ErrorCategory, RetryClassification, RetryStopReason, S3Error, TimeoutPhase};
pub use observer::{RequestEvent, RequestEventKind, RequestObserver};
pub use operation::{
    AbortMultipartUploadRequest, ByteRange, Checksum, ChecksumAlgorithm, ChecksumCalculationError,
    ChecksumType, CompleteMultipartUploadOutput, CompleteMultipartUploadRequest, CompletedPart,
    Conditions, CopyMetadataDirective, CopyObjectOutput, CopyObjectRequest, CopyPartRange,
    CopySource, CreateMultipartUploadOutput, CreateMultipartUploadRequest, DeleteError,
    DeleteObjectIdentifier, DeleteObjectOutput, DeleteObjectRequest, DeleteObjectsError,
    DeleteObjectsOutput, DeleteObjectsRequest, DeletedObject, GetObjectOutput, GetObjectRequest,
    HeadObjectOutput, HeadObjectRequest, ListMultipartUploadsOutput, ListMultipartUploadsRequest,
    ListObjectsV2Output, ListObjectsV2Request, ListPartsOutput, ListPartsRequest, ListedObject,
    ListedPart, ManagedMultipartHeaders, ManagedMultipartUploadRequest, MultipartError,
    MultipartOptions, MultipartUpload, MultipartUploadEntry, ObjectKey, ObjectKeyError,
    ObjectMetadata, ObjectOwner, PageSize, PartNumber, PresignedUrl, PutObjectOutput,
    PutObjectRequest, RangeError, RequestIds, UploadId, UploadIdError, UploadPartCopyOutput,
    UploadPartCopyRequest, UploadPartOutput, UploadPartRequest,
};
pub use retry::RetryPolicy;
pub use stream::{ByteStream, ResponseStream};