Introduce Interfaces to Support atomic conditional-writes

[x-INFiN1TY-x]

Description

This PR introduces interfaces for conditional-write support and defines new option and response types, updating the BlobContainer interface, and extending AsyncMultiStreamBlobContainer to support asynchronous conditional uploads.

• New Types

  • ConditionalWriteOptions — an object that explicitly models each supported precondition.

  • ConditionalWriteResponse — a typed result that carries provider-generated version identifiers and success status.

• Conditional APIs Interfaces for BlobContainer

  • writeBlobConditionally

  • writeBlobWithMetadataConditionally
    

• Async Conditional API

  • Introduces asyncBlobUploadConditionally to AsyncMultiStreamBlobContainer.

  • Provides the corresponding override in AsyncMultiStreamEncryptedBlobContainer to ensure encrypted uploads honor the same contract.

Supported Preconditions

Precondition	Azure	AWS S3	GCS
If-None-Match	ETag ≠ existing	If-None-Match header	—
If-Match	ETag == existing	If-Match header	generation match
If-Unmodified-Since	—	—	ifMetagenerationNotModifiedSince

Atomic Write Workflow

1. Caller constructs a ConditionalWriteOptions specifying the desired precondition.

2. On success, the blob (and optional metadata) are written, returning a ConditionalWriteResponse that includes the new version identifier for if-match writes.

3. On failure, the provider’s standard precondition-failed exception is propagated.

Note: The async implementation logic—including multipart handling via AsyncTransferManager—is being delivered in the companion PR: #18093. This PR is scoped purely to defining and aligning the interfaces and types needed to support that capability.

Related Issues

• Implements part of RFC #17763

• Parent Meta Issue: [META] Implement Conditional APIs for Multi-Writer Detection

• Supersedes Introduce Interface changes to Support atomic conditional-writes #18065

Check List

• New functionality has been documented.
• Public documentation issue/PR created
• Commits are signed per the DCO using --signoff

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 72cb9c6: SUCCESS

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.

Project coverage is 72.49%. Comparing base (8948c1f) to head (99e6943).

Files with missing lines	Patch %	Lines
...org/opensearch/common/blobstore/BlobContainer.java	0.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #18064      +/-   ##
============================================
- Coverage     72.50%   72.49%   -0.01%     
+ Complexity    67167    67113      -54     
============================================
  Files          5473     5473              
  Lines        310095   310097       +2     
  Branches      45062    45062              
============================================
- Hits         224841   224813      -28     
- Misses        66899    66915      +16     
- Partials      18355    18369      +14     

☔ 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.

[skumawat2025]

@x-INFiN1TY-x Please rebase your changes.

[github-actions]

✅ Gradle check result for 99e6943: SUCCESS

[github-actions]

❌ Gradle check result for 6461fe0: 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 : : #17552

• SegmentReplicationResizeRequestIT

[astute-decipher]

LGTM

[ashking94]

can we add the required interfaces in AsyncMultiStreamBlobContainer?

[github-actions]

❌ Gradle check result for 766204d: 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 a928b49: 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 : : #17937

• RethrottleTests.

[x-INFiN1TY-x]

can we add the required interfaces in AsyncMultiStreamBlobContainer?
cc : @ashking94 @Bukhtawar @astute-decipher

Thanks for raising this,
To enable asynchronous conditional uploads across providers, I’ve introduced the appropriate interface in AsyncMultiStreamBlobContainer, along with the corresponding override in AsyncMultiStreamEncryptedBlobContainer, ensuring consistent support for encrypted use cases.

This PR is specifically focused on defining and aligning the necessary interfaces to support this capability across the relevant components. The implementation details—including multipart handling login via AsyncTransferManager—are addressed in the related PR : #18093.

Please let me know if there’s anything further that needs to be adjusted, here's a diag detailing the intended downstream usage for the concerned interfaces. (Under review in #18093)

[astute-decipher]

Can there be case where the conditionalWriteOptions has multiple conditions and are contradicting? If yes do we need to have validation for same?

[x-INFiN1TY-x]

All the Concerned cloud storage providers support multiple conditional write options that can be employed concurrently, without needing to manually enforce checks for proper functioning, so we wouldn't require any validation for the same.

References :

1. AWS S3 conditional writes:

   • https://aws.amazon.com/about-aws/whats-new/2024/11/amazon-s3-functionality-conditional-writes/
   • https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-requests.html

2. Azure Blob Storage conditional headers:

   • https://learn.microsoft.com/en-us/rest/api/storageservices/specifying-conditional-headers-for-blob-service-operations
   • https://stackoverflow.com/questions/19358836/azure-blob-storage-error-multiple-condition-headers-are-not-supported

3. Google Cloud Storage generation preconditions:

   • https://cloud.google.com/python/docs/reference/storage/latest/generation_metageneration
   • https://stackoverflow.com/questions/67005882/how-to-upload-a-file-to-gcs-only-if-it-is-of-a-specific-version-in-java