From a9deccfc546b42e47cf2247c56b187c58fc9cf4a Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 10 Jul 2026 10:00:39 -0400 Subject: [PATCH 1/2] Add doc example for multipart upload to AmazonS3::create_multipart Add a runnable (`no_run`) example on the `MultipartStore` impl for `AmazonS3` showing the full low-level flow: `create_multipart`, `put_part` for each part, and `complete_multipart` to finalize. Also link to the example from `MultipartStore::create_multipart` so it is discoverable from the trait definition. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/aws/mod.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++++++ src/multipart.rs | 11 ++++++++++ 2 files changed, 65 insertions(+) diff --git a/src/aws/mod.rs b/src/aws/mod.rs index b02bd0e0..957fc410 100644 --- a/src/aws/mod.rs +++ b/src/aws/mod.rs @@ -484,6 +484,60 @@ impl MultipartUpload for S3MultiPartUpload { #[async_trait] impl MultipartStore for AmazonS3 { + /// Create a new multipart upload, returning its [`MultipartId`]. + /// + /// This is the low-level [`MultipartStore`] API, which gives direct control + /// over individual parts. See [`ObjectStoreExt::put_multipart`] for a + /// higher-level API that handles parts automatically. + /// + /// # Example + /// + /// Create a multipart upload, upload two parts, and finalize it by calling + /// [`complete_multipart`]: + /// + /// ```no_run + /// # async fn example() -> Result<(), Box> { + /// # use object_store::{aws::AmazonS3Builder, multipart::MultipartStore, path::Path, PutPayload}; + /// # + /// let s3 = AmazonS3Builder::new() + /// .with_region("us-east-1") + /// .with_bucket_name("my-bucket") + /// .with_access_key_id("my-access-key-id") + /// .with_secret_access_key("my-secret-access-key") + /// .build()?; + /// + /// let path = Path::from("data/large_file"); + /// + /// // Start the upload, obtaining an id used to reference it in later calls + /// let id = s3.create_multipart(&path).await?; + /// + /// // Upload the individual parts. Every part except the last must be at least + /// // 5 MiB. + /// let part0 = s3 + /// .put_part(&path, &id, 0, PutPayload::from(vec![0; 5 * 1024 * 1024])) + /// .await?; + /// let part1 = s3 + /// .put_part(&path, &id, 1, PutPayload::from("the final part")) + /// .await?; + /// + /// // Finalize the upload. The parts must be provided in `part_idx` order. + /// s3.complete_multipart(&path, &id, vec![part0, part1]).await?; + /// # Ok(()) + /// # } + /// ``` + /// + /// Every part except the last must be at least 5 MiB. Parts may be uploaded + /// concurrently and in any order, provided each is given the correct + /// `part_idx`. See [Amazon S3 multipart upload limits] for the full set of + /// size and count constraints. + /// + /// To discard an upload instead of completing it, call + /// [`abort_multipart`] with the same `id`. + /// + /// [`ObjectStoreExt::put_multipart`]: crate::ObjectStoreExt::put_multipart + /// [`complete_multipart`]: MultipartStore::complete_multipart + /// [`abort_multipart`]: MultipartStore::abort_multipart + /// [Amazon S3 multipart upload limits]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html async fn create_multipart(&self, path: &Path) -> Result { self.client .create_multipart(path, PutMultipartOptions::default()) diff --git a/src/multipart.rs b/src/multipart.rs index 90db576d..6588b070 100644 --- a/src/multipart.rs +++ b/src/multipart.rs @@ -39,17 +39,28 @@ pub struct PartId { /// backends, including [`LocalFileSystem`], and automatically handles uploading fixed /// size parts of sufficient size in parallel /// +/// See [`AmazonS3::create_multipart`] for a full example of this API. +/// /// [`ObjectStore::put_multipart_opts`]: crate::ObjectStore::put_multipart_opts /// [`LocalFileSystem`]: crate::local::LocalFileSystem +/// [`AmazonS3::create_multipart`]: crate::aws::AmazonS3::create_multipart #[async_trait] pub trait MultipartStore: Send + Sync + 'static { /// Creates a new multipart upload, returning the [`MultipartId`] + /// + /// See [`AmazonS3::create_multipart`] for a full example of this API. + /// + /// [`AmazonS3::create_multipart`]: crate::aws::AmazonS3::create_multipart async fn create_multipart(&self, path: &Path) -> Result; /// Creates a new multipart upload with the given options, returning the [`MultipartId`] /// /// This allows callers using the low-level multipart API to provide object attributes, /// tags, or implementation-specific extensions when initiating the upload. + /// + /// See [`AmazonS3::create_multipart`] for a full example of this API. + /// + /// [`AmazonS3::create_multipart`]: crate::aws::AmazonS3::create_multipart async fn create_multipart_opts( &self, path: &Path, From 9e3f81c9d399f2f244c5e165538aa78bd588004f Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 10 Jul 2026 11:22:34 -0400 Subject: [PATCH 2/2] Fix double space in create_multipart doc link references Co-Authored-By: Claude Opus 4.8 (1M context) --- src/aws/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/aws/mod.rs b/src/aws/mod.rs index 957fc410..5d30fbf5 100644 --- a/src/aws/mod.rs +++ b/src/aws/mod.rs @@ -487,7 +487,7 @@ impl MultipartStore for AmazonS3 { /// Create a new multipart upload, returning its [`MultipartId`]. /// /// This is the low-level [`MultipartStore`] API, which gives direct control - /// over individual parts. See [`ObjectStoreExt::put_multipart`] for a + /// over individual parts. See [`ObjectStoreExt::put_multipart`] for a /// higher-level API that handles parts automatically. /// /// # Example @@ -528,7 +528,7 @@ impl MultipartStore for AmazonS3 { /// /// Every part except the last must be at least 5 MiB. Parts may be uploaded /// concurrently and in any order, provided each is given the correct - /// `part_idx`. See [Amazon S3 multipart upload limits] for the full set of + /// `part_idx`. See [Amazon S3 multipart upload limits] for the full set of /// size and count constraints. /// /// To discard an upload instead of completing it, call