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(|(offset, body)| body.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// Make async trait docs not-ugly on docs.rs (https://github.com/dtolnay/async-trait/issues/213)
44#![cfg_attr(docsrs, feature(async_fn_in_trait))]
45
46mod build_info;
47pub mod checksums;
48mod endpoint_config;
49#[doc(hidden)]
50pub mod failure_client;
51pub mod imds_crt_client;
52pub mod instance_info;
53#[doc(hidden)]
54pub mod mock_client;
55mod object_client;
56mod s3_crt_client;
57#[doc(hidden)]
58pub mod user_agent;
59
60pub mod error_metadata;
61
62pub use object_client::{ObjectClient, PutObjectRequest};
63
64pub use s3_crt_client::{
65    get_object::S3GetObjectResponse, put_object::S3PutObjectRequest, OnTelemetry, S3CrtClient, S3RequestError,
66};
67
68/// Configuration for the S3 client
69pub mod config {
70    pub use super::endpoint_config::{AddressingStyle, EndpointConfig, SigningAlgorithm, Uri};
71    pub use super::s3_crt_client::{
72        CredentialsProvider, CredentialsProviderStaticOptions, EventLoopGroup, S3ClientAuthConfig, S3ClientConfig,
73    };
74
75    pub use mountpoint_s3_crt::common::allocator::Allocator;
76    pub use mountpoint_s3_crt::common::rust_log_adapter::{RustLogAdapter, AWSCRT_LOG_TARGET};
77
78    #[doc(hidden)]
79    pub use mountpoint_s3_crt::io::io_library_init;
80    #[doc(hidden)]
81    pub use mountpoint_s3_crt::s3::s3_library_init;
82}
83
84/// Types used by all object clients
85pub mod types {
86    pub use super::object_client::{
87        Checksum, ChecksumAlgorithm, ChecksumMode, ClientBackpressureHandle, CopyObjectParams, CopyObjectResult,
88        DeleteObjectResult, ETag, GetBodyPart, GetObjectAttributesParts, GetObjectAttributesResult, GetObjectParams,
89        GetObjectResponse, HeadObjectParams, HeadObjectResult, ListObjectsResult, ObjectAttribute, ObjectClientResult,
90        ObjectInfo, ObjectPart, PutObjectParams, PutObjectResult, PutObjectSingleParams, PutObjectTrailingChecksums,
91        RestoreStatus, UploadChecksum, UploadReview, UploadReviewPart,
92    };
93}
94
95/// Errors returned by all object clients.
96///
97/// Object client methods return an error of type
98/// [`ObjectClientError`](object_client::ObjectClientError), which distinguishes between service and
99/// client errors. See its documentation for more details.
100pub mod error {
101    pub use super::object_client::{
102        CopyObjectError, DeleteObjectError, GetObjectAttributesError, GetObjectError, HeadObjectError,
103        ListObjectsError, ObjectClientError, PutObjectError,
104    };
105    #[doc(hidden)]
106    pub use super::s3_crt_client::CrtError;
107    #[doc(hidden)]
108    pub use super::s3_crt_client::HeadBucketError;
109}
110
111#[cfg(test)]
112mod tests {
113    use crate::s3_crt_client::S3CrtClient;
114
115    #[test]
116    fn smoke() {
117        let _client = S3CrtClient::new(Default::default()).unwrap();
118    }
119}
mountpoint_s3_client/lib.rs

mountpoint_s3_client/
lib.rs
