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; cheap
6//! bucket-scoped handles can share its connection pool.
7//!
8//! # Quick start
9//!
10//! The default credential provider reads `AWS_ACCESS_KEY_ID`,
11//! `AWS_SECRET_ACCESS_KEY`, and optional `AWS_SESSION_TOKEN`.
12//!
13//! ```no_run
14//! use s3_wire::{
15//! ByteStream, Endpoint, GetObjectRequest, ObjectKey, PutObjectRequest, S3Client, S3Config,
16//! };
17//!
18//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
19//! let region = "us-east-1";
20//! let config = S3Config::builder()
21//! .endpoint(Endpoint::for_aws_region(region)?)
22//! .region(region)
23//! .bucket("artifact-bucket")
24//! .build()?;
25//! let client = S3Client::new(config)?;
26//!
27//! let key = ObjectKey::new("reports/latest.json")?;
28//! client
29//! .put_object(PutObjectRequest::new(
30//! key.clone(),
31//! ByteStream::from_bytes(br#"{"status":"complete"}"#.as_slice()),
32//! ))
33//! .await?;
34//!
35//! let download = client.get_object(GetObjectRequest::new(key)).await?;
36//! let mut destination = tokio::io::sink();
37//! download.body.write_to(&mut destination).await?;
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! # Upload and download behavior
43//!
44//! - [`ByteStream::from_bytes`] and [`ByteStream::from_path`] are replayable.
45//! - [`ByteStream::from_stream`] is one-shot and requires an exact length and
46//! SHA-256 digest.
47//! - [`ResponseStream`] applies backpressure and validates declared length,
48//! configured deadlines, and supported checksums while the body is consumed.
49//! - [`S3Client::multipart_upload`] bounds concurrent part buffers and owns
50//! abort cleanup after S3 creates an upload.
51//!
52//! # Errors
53//!
54//! [`S3Error`] exposes a stable [`ErrorCategory`], service status and code,
55//! request identifiers, retry classification, attempt count, retry stop reason,
56//! timeout phase, and any multipart cleanup failure. Formatting remains
57//! redacted by default.
58//!
59//! # More documentation
60//!
61//! - [Architecture](https://github.com/runtrue/s3-rs/blob/main/docs/architecture.md)
62//! - [S3 compatibility](https://github.com/runtrue/s3-rs/blob/main/docs/compatibility.md)
63//! - [Security model](https://github.com/runtrue/s3-rs/blob/main/docs/security-model.md)
64//! - [Examples](https://github.com/runtrue/s3-rs/blob/main/examples/README.md)
65
66#![forbid(unsafe_code)]
67
68mod client;
69mod config;
70mod credentials;
71mod endpoint;
72mod error;
73mod observer;
74mod operation;
75mod retry;
76mod stream;
77
78#[cfg(feature = "fuzzing")]
79#[doc(hidden)]
80pub mod fuzzing;
81
82mod protocol;
83mod signing;
84mod transport;
85
86pub use client::{DownloadToPathOutput, S3Client};
87pub use config::{AddressingStyle, S3Config, S3ConfigBuilder};
88#[cfg(feature = "aws-credentials")]
89pub use credentials::{
90 AwsDefaultCredentialsProvider, resolve_aws_region_for_profile, resolve_default_aws_region,
91};
92pub use credentials::{
93 CachedCredentialsProvider, Credentials, CredentialsProvider, EnvironmentCredentialsProvider,
94 StaticCredentialsProvider,
95};
96pub use endpoint::{AwsEndpointVariant, Endpoint};
97pub use error::{ErrorCategory, RetryClassification, RetryStopReason, S3Error, TimeoutPhase};
98pub use observer::{RequestEvent, RequestEventKind, RequestObserver};
99pub use operation::{
100 AbortMultipartUploadRequest, ByteRange, Checksum, ChecksumAlgorithm, ChecksumCalculationError,
101 ChecksumType, CompleteMultipartUploadOutput, CompleteMultipartUploadRequest, CompletedPart,
102 Conditions, CopyMetadataDirective, CopyObjectOutput, CopyObjectRequest, CopyPartRange,
103 CopySource, CreateMultipartUploadOutput, CreateMultipartUploadRequest, DeleteError,
104 DeleteObjectOutput, DeleteObjectRequest, DeleteObjectsError, DeleteObjectsOutput,
105 DeleteObjectsRequest, DeletedObject, GetObjectOutput, GetObjectRequest, HeadObjectOutput,
106 HeadObjectRequest, ListMultipartUploadsOutput, ListMultipartUploadsRequest,
107 ListObjectsV2Output, ListObjectsV2Request, ListPartsOutput, ListPartsRequest, ListedObject,
108 ListedPart, ManagedMultipartUploadRequest, MultipartError, MultipartOptions, MultipartUpload,
109 MultipartUploadEntry, ObjectKey, ObjectKeyError, ObjectMetadata, ObjectOwner, PageSize,
110 PartNumber, PresignedUrl, PutObjectOutput, PutObjectRequest, RangeError, RequestIds, UploadId,
111 UploadIdError, UploadPartCopyOutput, UploadPartCopyRequest, UploadPartOutput,
112 UploadPartRequest,
113};
114pub use retry::RetryPolicy;
115pub use stream::{ByteStream, ResponseStream};