re-organize crate structure part one #36
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
|
|
||
| /// Abstractions for downloading objects from S3 | ||
| pub mod downloader; | ||
| pub use downloader::Downloader; | ||
|
|
||
| use crate::Config; | ||
| use crate::{ | ||
| types::{ConcurrencySetting, PartSize}, | ||
| DEFAULT_CONCURRENCY, MEBIBYTE, | ||
| }; | ||
| use std::sync::Arc; | ||
|
|
||
| /// Transfer manager client for Amazon Simple Storage Service. | ||
| #[derive(Debug, Clone)] | ||
| pub struct Client { | ||
| handle: Arc<Handle>, | ||
| } | ||
|
|
||
| /// Whatever is needed to carry out operations, e.g. scheduler, budgets, config, env details, etc | ||
| #[derive(Debug)] | ||
| pub(crate) struct Handle { | ||
| pub(crate) config: crate::Config, | ||
| } | ||
|
|
||
| impl Handle { | ||
| /// Get the concrete number of workers to use based on the concurrency setting. | ||
| pub(crate) fn num_workers(&self) -> usize { | ||
| match self.config.concurrency() { | ||
| // TODO(aws-sdk-rust#1159): add logic for determining this | ||
| ConcurrencySetting::Auto => DEFAULT_CONCURRENCY, | ||
| ConcurrencySetting::Explicit(explicit) => *explicit, | ||
| } | ||
| } | ||
|
|
||
| /// Get the concrete minimum upload size in bytes to use to determine whether multipart uploads | ||
| /// are enabled for a given request. | ||
| pub(crate) fn mpu_threshold_bytes(&self) -> u64 { | ||
| match self.config.multipart_threshold() { | ||
| PartSize::Auto => 16 * MEBIBYTE, | ||
| PartSize::Target(explicit) => *explicit, | ||
| } | ||
| } | ||
|
|
||
| /// Get the concrete target part size to use for uploads | ||
| pub(crate) fn upload_part_size_bytes(&self) -> u64 { | ||
| match self.config.part_size() { | ||
| PartSize::Auto => 8 * MEBIBYTE, | ||
| PartSize::Target(explicit) => *explicit, | ||
| } | ||
| } | ||
| } | ||
|
|
||
| impl Client { | ||
| /// Creates a new client from a transfer manager config. | ||
| pub fn new(config: Config) -> Client { | ||
| let handle = Arc::new(Handle { config }); | ||
|
|
||
| Client { handle } | ||
| } | ||
|
|
||
| /// Returns the client's configuration | ||
| pub fn config(&self) -> &Config { | ||
| &self.handle.config | ||
| } | ||
|
|
||
| /// Constructs a fluent builder for the | ||
| /// [`Upload`](crate::operation::upload::builders::UploadFluentBuilder) operation. | ||
| /// | ||
| /// # Examples | ||
| /// | ||
| /// ```no_run | ||
| /// use std::error::Error; | ||
| /// use std::path::Path; | ||
| /// use aws_s3_transfer_manager::io::InputStream; | ||
| /// | ||
| /// async fn upload_file( | ||
| /// client: &aws_s3_transfer_manager::Client, | ||
| /// path: impl AsRef<Path> | ||
| /// ) -> Result<(), Box<dyn Error>> { | ||
| /// let stream = InputStream::from_path(path)?; | ||
| /// let handle = client.upload() | ||
| /// .bucket("my-bucket") | ||
| /// .key("my_key") | ||
| /// .body(stream) | ||
| /// .send() | ||
| /// .await?; | ||
| /// | ||
| /// // send() may return before the transfer is complete. | ||
| /// // Call the `join()` method on the returned handle to drive the transfer to completion. | ||
| /// // The handle can also be used to get progress, pause, or cancel the transfer, etc. | ||
| /// let response = handle.join().await?; | ||
| /// // ... do something with response | ||
| /// Ok(()) | ||
| /// } | ||
| /// | ||
| /// ``` | ||
| pub fn upload(&self) -> crate::operation::upload::builders::UploadFluentBuilder { | ||
|
There was a problem hiding this comment. I was going to say it seems it weird that the returned type has such a long module path, and wondered if we want to shorten it at least for public consumption? But I see that this mirrors the path to aws_sdk_s3's fluent builders, so it's probably good I'm seeing now how the module organization here really mirrors the SDK's module organization, which seems good to do. no need to respond. just sharing my mental journey There was a problem hiding this comment. It makes no difference to the generated docs or how users consume it FWIW. The end result to a user is the same as: use crate::operation::upload::builders::UploadFluentBuilder;
...
pub fn upload(&self) -> UploadFluentBuilder |
||
| crate::operation::upload::builders::UploadFluentBuilder::new(self.handle.clone()) | ||
| } | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will it be confusing to call it
aws_s3_transfer_manager::Clientbut also theaws_sdk_s3::Clientis in the mix? User code is going to end up with 2 "S3 clients". Should it beaws_s3_transfer_manager::TransferManagerinstead?Or is that just normal? Everything is a "::Client", it's namespaced by the module name, and users are used to that, and give good disambiguating variable names when they both appear side-by-side
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm going to leave it for now but feel free to add it to the bikeshed issue. I can go either way, I do think it's redundant a bit when the crate/module name has transfer manager in it, though the SEP says it should be named
TransferManagerso maybe we call it that. Users can give an alias to an import to disambiguate e.g.use aws_s3_transfer_manager::Client as TransferManager. Also my hope is that the need for users to instantiate their ownaws_sdk_s3::Clientis rare when we add some convenience "loader" functions.