mountpoint_s3_client/
lib.rs

1//! An Amazon S3 client built on top of the AWS Common Runtime (AWS CRT).
2//!
3//! This crate provides a high-performance implementation of an Amazon S3 client that uses the [AWS
4//! Common Runtime (CRT)][awscrt]. The CRT is a software library for interacting with AWS services,
5//! offering components like IO, HTTP, and encryption. The CRT is purpose-built for high performance
6//! and low resource usage to make the most efficient use of your compute resources. For Amazon S3,
7//! the CRT includes a client that implements best practice performance design patterns, including
8//! timeouts, retries, and automatic request parallelization for high throughput.
9//!
10//! **This crate is not intended for general-purpose use and we consider its interface to be
11//! unstable.** Customers looking for a general-purpose Amazon S3 client in Rust should use the
12//! official [AWS SDK for Rust](https://aws.amazon.com/sdk-for-rust/).
13//!
14//! # Example
15//!
16//! To construct a new S3 client and download an object from a bucket in the `us-east-1` region:
17//! ```no_run
18//! # async fn test() {
19//! use futures::{TryFutureExt, TryStreamExt};
20//! use mountpoint_s3_client::types::GetObjectParams;
21//! use mountpoint_s3_client::{S3CrtClient, ObjectClient};
22//!
23//! let client = S3CrtClient::new(Default::default()).expect("client construction failed");
24//!
25//! let response = client.get_object("my-bucket", "my-key", &GetObjectParams::new()).await.expect("get_object failed");
26//! let body = response.map_ok(|part| part.data.to_vec()).try_concat().await.expect("body streaming failed");
27//! # }
28//! ```
29//!
30//! To further configure the client, use the [`S3ClientConfig`](config::S3ClientConfig) builder:
31//! ```
32//! use mountpoint_s3_client::S3CrtClient;
33//! use mountpoint_s3_client::config::{S3ClientAuthConfig, S3ClientConfig, EndpointConfig};
34//!
35//! let config = S3ClientConfig::new()
36//!                 .endpoint_config(EndpointConfig::new("us-west-2"))
37//!                 .auth_config(S3ClientAuthConfig::NoSigning);
38//! let client = S3CrtClient::new(config).expect("client construction failed");
39//! ```
40//!
41//! [awscrt]: https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html
42
43#![deny(clippy::undocumented_unsafe_blocks)]
44// Make async trait docs not-ugly on docs.rs (https://github.com/dtolnay/async-trait/issues/213)
45#![cfg_attr(docsrs, feature(async_fn_in_trait))]
46
47mod build_info;
48pub mod checksums;
49mod endpoint_config;
50#[doc(hidden)]
51pub mod failure_client;
52pub mod imds_crt_client;
53pub mod instance_info;
54pub mod metrics;
55#[doc(hidden)]
56pub mod mock_client;
57mod object_client;
58mod s3_crt_client;
59#[doc(hidden)]
60pub mod user_agent;
61
62pub mod error_metadata;
63
64pub use object_client::{ObjectClient, PutObjectRequest};
65
66pub use s3_crt_client::{
67    NewClientError, OnTelemetry, S3CrtClient, S3RequestError, get_object::S3GetObjectResponse,
68    put_object::S3PutObjectRequest,
69};
70
71/// Configuration for the S3 client
72pub mod config {
73    pub use super::endpoint_config::{AddressingStyle, EndpointConfig, SigningAlgorithm, Uri};
74    pub use super::s3_crt_client::{
75        CredentialsProvider, CredentialsProviderStaticOptions, EventLoopGroup, S3ClientAuthConfig, S3ClientConfig,
76    };
77
78    pub use mountpoint_s3_crt::common::allocator::Allocator;
79    pub use mountpoint_s3_crt::common::rust_log_adapter::{AWSCRT_LOG_TARGET, RustLogAdapter};
80
81    #[doc(hidden)]
82    pub use mountpoint_s3_crt::io::io_library_init;
83    #[doc(hidden)]
84    pub use mountpoint_s3_crt::s3::s3_library_init;
85
86    pub use mountpoint_s3_crt::s3::client::MetaRequestType;
87    pub use mountpoint_s3_crt::s3::pool::{MemoryPool, MemoryPoolFactory, MemoryPoolFactoryOptions};
88}
89
90/// Types used by all object clients
91pub mod types {
92    pub use super::object_client::{
93        Checksum, ChecksumAlgorithm, ChecksumMode, ClientBackpressureHandle, CopyObjectParams, CopyObjectResult,
94        DeleteObjectResult, ETag, GetBodyPart, GetObjectAttributesParts, GetObjectAttributesResult, GetObjectParams,
95        GetObjectResponse, HeadObjectParams, HeadObjectResult, ListObjectsResult, ObjectAttribute, ObjectClientResult,
96        ObjectInfo, ObjectPart, PutObjectParams, PutObjectResult, PutObjectSingleParams, PutObjectTrailingChecksums,
97        RenameObjectParams, RenameObjectResult, RenamePreconditionTypes, RestoreStatus, UploadChecksum, UploadReview,
98        UploadReviewPart,
99    };
100}
101
102/// Errors returned by all object clients.
103///
104/// Object client methods return an error of type
105/// [`ObjectClientError`](object_client::ObjectClientError), which distinguishes between service and
106/// client errors. See its documentation for more details.
107pub mod error {
108    pub use super::object_client::{
109        CopyObjectError, DeleteObjectError, GetObjectAttributesError, GetObjectError, HeadObjectError,
110        ListObjectsError, ObjectClientError, PutObjectError, RenameObjectError,
111    };
112    #[doc(hidden)]
113    pub use super::s3_crt_client::CrtError;
114    #[doc(hidden)]
115    pub use super::s3_crt_client::HeadBucketError;
116}
117
118#[cfg(test)]
119mod tests {
120    use crate::s3_crt_client::S3CrtClient;
121
122    #[test]
123    fn smoke() {
124        let _client = S3CrtClient::new(Default::default()).unwrap();
125    }
126}
mountpoint_s3_client/lib.rs

mountpoint_s3_client/
lib.rs
