Enabling Support for Conditional Single-Part Upload [AWS S3]

[x-INFiN1TY-x]

Enable Conditional Single-Part Uploads via executeSingleUploadConditionally

Introduce a condition-aware single-part upload method to S3BlobStore, leveraging ConditionalWriteOptions for “If-Match” and “If-None-Match” semantics and returning structured ConditionalWriteResponse results.

Method	Location	Purpose
executeSingleUploadConditionally	S3BlobStore	Conditional single-part S3 upload

---

Summary of Changes

• Add executeSingleUploadConditionally(...) to S3BlobStore

• Introduce ConditionalWriteOptions to model “If-Match” and “If-None-Match” conditions

• Return a ConditionalWriteResponse.success(etag) on success

• Translate HTTP 412 (precondition failed) into OpenSearchException("stale_primary_shard")

• Wrap other S3/SDK errors in IOException and propagate via listener.onFailure(...)

• Enforce blob size limits (≤ 5 GB and ≤ buffer size) before making any S3 requests

• Apply custom metadata and server-side encryption (AES256 or KMS) settings consistently

---

Core Workflow

1. Validate Blob Size

   • If blobSize > 5 GB or blobSize > bufferSize, throw IllegalArgumentException.

2. Build and Send PutObjectRequest

   • Set bucket, key, contentLength, storageClass, acl, and metrics.

   • Apply conditional headers from ConditionalWriteOptions (If-Match or If-None-Match).

   • Attach metadata and configure encryption (AES256 or KMS).

   • Upload via putObject(...).

3. Handle Response

   • If response.eTag() is non-null, return ConditionalWriteResponse.success(etag).

   • If response.eTag() is null, throw IOException and invoke listener.onFailure(...).

4. Error Handling

   • HTTP 412 → listener receives OpenSearchException("stale_primary_shard"), then throw IOException to abort.

   • Other S3Exception/SdkException → wrap in IOException, invoke listener.onFailure(...), and rethrow.

---

Test Coverage Highlights

• testExecuteSingleUploadConditionallyPreconditionFailed: ETag mismatch (HTTP 412) → OpenSearchException("stale_primary_shard").

• testExecuteSingleUploadConditionallyS3Exception: S3 error (e.g., HTTP 403) → IOException.

• testExecuteSingleUploadConditionallySuccess: Successful upload with metadata, AES256/KMS, and correct ETag response.

• testExecuteSingleUploadConditionallySdkException: AWS SDK failure → IOException.

• testExecuteSingleUploadConditionallyWithNullETag: Null ETag → IOException.

• testExecuteSingleUploadConditionallyNullOrEmptyInput: Zero-length blob or empty ETag handling.

---

Related Issues

• Implements RFC #17763

• Parent Meta: #17859

---

Developer Checklist

• Add executeSingleUploadConditionally(...) to S3BlobStore

• Introduce ConditionalWriteOptions / ConditionalWriteResponse

• Validate size limits before request

• Apply conditional headers correctly

• Configure metadata and encryption settings

• Map HTTP 412 to OpenSearchException("stale_primary_shard") + abort

• Wrap other exceptions in IOException

• Expand tests for conditional and boundary scenarios

• Sign off commits per DCO

By submitting this PR, I confirm that my contribution is made under the terms of the Apache 2.0 license.

# Enable Conditional Single-Part Uploads via `executeSingleUploadConditionally` (#XXXX)

At a Glance:
Introduce a condition-aware single-part upload method to S3BlobStore, leveraging ConditionalWriteOptions for “If-Match” and “If-None-Match” semantics and returning structured ConditionalWriteResponse results.

Method	Location	Purpose
executeSingleUploadConditionally	S3BlobStore	Conditional single-part S3 upload

---

Summary of Changes

• Add executeSingleUploadConditionally(...) to S3BlobStore
• Introduce ConditionalWriteOptions to model “If-Match” and “If-None-Match” conditions
• Return a ConditionalWriteResponse.success(etag) on success
• Translate HTTP 412 (precondition failed) into OpenSearchException("stale_primary_shard")
• Wrap other S3/SDK errors in IOException and propagate via listener.onFailure(...)
• Enforce blob size limits (≤ 5 GB and ≤ buffer size) before making any S3 requests
• Apply custom metadata and server-side encryption (AES256 or KMS) settings consistently

---

Core Workflow

1. Validate Blob Size

   • If blobSize > 5 GB or blobSize > bufferSize, throw IllegalArgumentException.

2. Build and Send PutObjectRequest

   • Set bucket, key, contentLength, storageClass, acl, and metrics.
   • Apply conditional headers from ConditionalWriteOptions (If-Match or If-None-Match).
   • Attach metadata and configure encryption (AES256 or KMS).
   • Upload via putObject(...).

3. Handle Response

   • If response.eTag() is non-null, return ConditionalWriteResponse.success(etag).
   • If response.eTag() is null, throw IOException and invoke listener.onFailure(...).

4. Error Handling

   • HTTP 412 → listener receives OpenSearchException("stale_primary_shard"), then throw IOException to abort.
   • Other S3Exception/SdkException → wrap in IOException, invoke listener.onFailure(...), and rethrow.

---

Test Coverage

• testExecuteSingleUploadConditionallyPreconditionFailed: ETag mismatch (HTTP 412) → OpenSearchException("stale_primary_shard").
• testExecuteSingleUploadConditionallyS3Exception: S3 error (e.g., HTTP 403) → IOException.
• testExecuteSingleUploadConditionallySuccess: Successful upload with metadata, AES256/KMS, and correct ETag response.
• testExecuteSingleUploadConditionallySdkException: AWS SDK failure → IOException.
• testExecuteSingleUploadConditionallyWithNullETag: Null ETag → IOException.
• testExecuteSingleUploadConditionallyNullOrEmptyInput: Zero-length blob or empty ETag handling.

---

Related Issue

Concerned RFC : RFC #17763
Parent Meta Issue : Meta #17859

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

❌ Gradle check result for f1c411e: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[x-INFiN1TY-x]

Flaky Test : : #14509

• "testRecoverWhileUnderLoadAllocateReplicasRelocatePrimariesTest {p0={"cluster.indices.replication.strategy":"DOCUMENT"}} – org.opensearch.recovery.RecoveryWhileUnderLoadIT"

[github-actions]

✅ Gradle check result for 3951775: SUCCESS

[codecov]

Codecov Report

Attention: Patch coverage is 82.14286% with 15 lines in your changes missing coverage. Please review.

Project coverage is 72.64%. Comparing base (d52cefa) to head (9a429f2).

Files with missing lines	Patch %	Lines
.../opensearch/common/blobstore/ConditionalWrite.java	71.79%	11 Missing ⚠️
...rg/opensearch/repositories/s3/S3BlobContainer.java	91.11%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #18092      +/-   ##
============================================
- Coverage     72.74%   72.64%   -0.10%     
+ Complexity    67767    67688      -79     
============================================
  Files          5497     5498       +1     
  Lines        311815   311899      +84     
  Branches      45261    45268       +7     
============================================
- Hits         226822   226588     -234     
- Misses        66504    66829     +325     
+ Partials      18489    18482       -7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[opensearch-trigger-bot]

This PR is stalled because it has been open for 30 days with no activity.

[github-actions]

❌ Gradle check result for 109a7cf: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[github-actions]

✅ Gradle check result for 9a429f2: SUCCESS