add custom_headers parameter to initiate_multipart_upload

[ZzIsGod1019]

This PR adds support for custom HTTP headers in the initiate_multipart_upload method, allowing users to pass custom headers (such as cache-control, metadata, storage class, etc.) when initiating multipart uploads to S3.

This feature aligns the initiate_multipart_upload API with the existing put_object_with_headers functionality, providing a consistent interface for setting custom headers across different upload methods.

---

This change is 

Summary by CodeRabbit

• New Features

  • Custom HTTP headers can now be specified when initiating multipart uploads.

• Breaking Changes

  • Multipart upload initiation method signatures updated to include a custom headers parameter.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds support for custom HTTP headers in multipart upload initiation flows. The initiate_multipart_upload method signature is updated to accept an optional custom_headers parameter, which propagates through the Command::InitiateMultipartUpload variant and into the request header assembly logic.

Changes

Cohort / File(s)	Summary
Multipart Upload API s3/src/bucket.rs	Both async and sync initiate_multipart_upload method signatures updated to include custom_headers: Option<HeaderMap> parameter. All call sites within the multipart upload flow updated to pass custom headers (Some or None) to the method and through to Command construction. Higher-level streaming code paths now route custom headers to initiate_multipart_upload.
Command Enum s3/src/command.rs	Command::InitiateMultipartUpload variant extended with new field custom_headers: Option<HeaderMap>. Pattern matching for content_type() updated to use .. to accommodate the new field.
Request Header Merging s3/src/request/request_trait.rs	Header merging logic added for InitiateMultipartUpload command, iterating over custom_headers and inserting them into the request headers map before host header computation, mirroring existing PutObject header handling.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Headers hop through multipart flows,

Custom threads the rabbit knows,

Upload streams with flair so bright,

Every part gets headers right! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title directly and accurately summarizes the main change: adding a custom_headers parameter to the initiate_multipart_upload method.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

s3/src/bucket.rs (2)

1857-1877: Breaking API change: Consider backward compatibility.

Adding custom_headers: Option<HeaderMap> as a required parameter to the public initiate_multipart_upload method is a breaking change for existing callers. Consider whether this warrants a semver major version bump.

Additionally, as per coding guidelines, public APIs should include documentation examples. This method currently lacks doc comments demonstrating the new custom_headers parameter usage.

Example documentation to add

/// Initiate multipart upload to s3.
///
/// # Example:
///
/// ```no_run
/// use s3::bucket::Bucket;
/// use s3::creds::Credentials;
/// use http::HeaderMap;
/// use http::header::HeaderName;
/// use anyhow::Result;
///
/// # #[tokio::main]
/// # async fn main() -> Result<()> {
/// let bucket = Bucket::new("my-bucket", "us-east-1".parse()?, Credentials::default()?)?;
///
/// // Without custom headers
/// let response = bucket.initiate_multipart_upload("/path/to/file", "application/octet-stream", None).await?;
///
/// // With custom headers (e.g., Cache-Control, x-amz-meta-*)
/// let mut headers = HeaderMap::new();
/// headers.insert(
///     HeaderName::from_static("cache-control"),
///     "public, max-age=3600".parse().unwrap(),
/// );
/// let response = bucket.initiate_multipart_upload("/path/to/file", "application/octet-stream", Some(headers)).await?;
/// # Ok(())
/// # }
/// ```
#[maybe_async::async_impl]
pub async fn initiate_multipart_upload(

---

1802-1809: Inconsistency: Sync streaming path doesn't support custom headers.

The sync _put_object_stream_with_content_type method always passes None for custom_headers, while the async path (_put_object_stream_with_content_type_and_headers) properly propagates custom headers. Consider adding a sync equivalent that supports custom headers for consistency.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3a9314f and 2db43eb.

📒 Files selected for processing (3)

• s3/src/bucket.rs
• s3/src/command.rs
• s3/src/request/request_trait.rs

🧰 Additional context used

📓 Path-based instructions (2)

s3/src/**/*.rs

📄 CodeRabbit inference engine (CLAUDE.md)

Use existing error types from s3/src/error.rs rather than defining new error types

Files:

• s3/src/command.rs
• s3/src/request/request_trait.rs
• s3/src/bucket.rs

{s3,aws-region,aws-creds}/src/**/*.rs

📄 CodeRabbit inference engine (CLAUDE.md)

{s3,aws-region,aws-creds}/src/**/*.rs: Follow the async/sync abstraction pattern using maybe_async macros for runtime-agnostic implementations
Mark integration tests with #[ignore] if they require AWS credentials
Provide documentation examples for all public APIs

Files:

• s3/src/command.rs
• s3/src/request/request_trait.rs
• s3/src/bucket.rs

🧬 Code graph analysis (1)

s3/src/request/request_trait.rs (2)

s3/src/signing.rs (1)

• headers (141-144)

s3/src/request/tokio_backend.rs (1)

• headers (124-135)

🔇 Additional comments (6)

s3/src/command.rs (2)

135-138: LGTM! Consistent with existing patterns.

The addition of custom_headers: Option<HeaderMap> to InitiateMultipartUpload mirrors the existing pattern in PutObject and PresignPut variants, providing a consistent API surface.

---

262-262: LGTM! Correct pattern matching update.

Using .. to ignore the new custom_headers field while extracting content_type is the idiomatic approach.

s3/src/request/request_trait.rs (1)

699-706: LGTM! Header merging correctly follows the established pattern.

The custom headers for InitiateMultipartUpload are merged using the same approach as PutObject (lines 691-697). Headers are inserted before the host header and authorization calculation, ensuring they are properly included in the AWS signature.

s3/src/bucket.rs (3)

1864-1867: LGTM! Command construction correctly includes custom_headers.

The Command::InitiateMultipartUpload is properly constructed with both content_type and custom_headers fields.

---

1879-1899: Sync implementation mirrors async correctly.

The sync variant properly accepts and passes custom_headers to the command, maintaining consistency with the async implementation.

---

1667-1668: LGTM! Custom headers correctly propagated in async multipart flow.

The custom_headers parameter is properly forwarded to initiate_multipart_upload, enabling per-request header customization for multipart uploads.