refactor(Storage): Introduce RejectAndThrow upload validation mode and deprecate legacy modes

Introduces `UploadValidationMode.RejectAndThrow` to leverage server-side
validation, ensuring invalid uploads are rejected automatically before object creation.
Updates `UploadObjectOptions` to use this new mode as the default behavior.
Updates `UploadObjectTest`.
Deprecated the legacy `ThrowOnly` and `DeleteAndThrow` modes, as server-side
validation effectively unifies their end-state behaviors.

BREAKING CHANGE: The default upload validation mode has been switched to
`RejectAndThrow`. Under this mode, objects with mismatched hashes will no longer
be created in the bucket at all, changing the legacy `ThrowOnly` behavior which used to leave the invalid object intact.

Author: mahendra-google

apis/Google.Cloud.Storage.V1/Google.Cloud.Storage.V1.IntegrationTests/UploadObjectTest.cs

@@ -300,35 +300,19 @@ public void UploadObject_InvalidHash_None()
         }
 
         [Fact]
-        public void UploadObject_InvalidHash_ThrowOnly()
+        public void UploadObject_InvalidHash_RejectAndThrow()
         {
             var client = StorageClient.Create();
             var interceptor = new BreakUploadInterceptor();
             client.Service.HttpClient.MessageHandler.AddExecuteInterceptor(interceptor);
             var stream = GenerateData(50);
             var name = IdGenerator.FromGuid();
             var bucket = _fixture.MultiVersionBucket;
-            var options = new UploadObjectOptions { UploadValidationMode = UploadValidationMode.ThrowOnly };
+            var options = new UploadObjectOptions { UploadValidationMode = UploadValidationMode.RejectAndThrow };
             var exception = Assert.Throws<GoogleApiException>(() => client.UploadObject(bucket, name, null, stream, options));
             Assert.Equal(HttpStatusCode.BadRequest, exception.HttpStatusCode);
         }
 
-        [Fact]
-        public void UploadObject_InvalidHash_DeleteAndThrow()
-        {
-            var client = StorageClient.Create();
-            var interceptor = new BreakUploadInterceptor();
-            client.Service.HttpClient.MessageHandler.AddExecuteInterceptor(interceptor);
-            var stream = GenerateData(50);
-            var name = IdGenerator.FromGuid();
-            var bucket = _fixture.MultiVersionBucket;
-            var options = new UploadObjectOptions { UploadValidationMode = UploadValidationMode.DeleteAndThrow };
-            var exception = Assert.Throws<GoogleApiException>(() => client.UploadObject(bucket, name, null, stream, options));
-            Assert.Equal(HttpStatusCode.BadRequest, exception.HttpStatusCode);
-            var notFound = Assert.Throws<GoogleApiException>(() => _fixture.Client.GetObject(bucket, name));
-            Assert.Equal(HttpStatusCode.NotFound, notFound.HttpStatusCode);
-        }
-
         [Fact]
         public async Task UploadObjectAsync_InvalidHash_None()
         {
@@ -346,34 +330,17 @@ public async Task UploadObjectAsync_InvalidHash_None()
         }
 
         [Fact]
-        public async Task UploadObjectAsync_InvalidHash_ThrowOnly()
+        public async Task UploadObjectAsync_InvalidHash_RejectAndThrow()
         {
             var client = StorageClient.Create();
             var interceptor = new BreakUploadInterceptor();
             client.Service.HttpClient.MessageHandler.AddExecuteInterceptor(interceptor);
             var stream = GenerateData(50);
             var name = IdGenerator.FromGuid();
             var bucket = _fixture.MultiVersionBucket;
-            var options = new UploadObjectOptions { UploadValidationMode = UploadValidationMode.ThrowOnly };
-            var exception = await Assert.ThrowsAsync<GoogleApiException>(() => client.UploadObjectAsync(bucket, name, null, stream, options));
-            Assert.Equal(HttpStatusCode.BadRequest, exception.HttpStatusCode);
-        }
-
-        [Fact]
-        public async Task UploadObjectAsync_InvalidHash_DeleteAndThrow()
-        {
-            var client = StorageClient.Create();
-            var interceptor = new BreakUploadInterceptor();
-            client.Service.HttpClient.MessageHandler.AddExecuteInterceptor(interceptor);
-
-            var stream = GenerateData(50);
-            var name = IdGenerator.FromGuid();
-            var bucket = _fixture.MultiVersionBucket;
-            var options = new UploadObjectOptions { UploadValidationMode = UploadValidationMode.DeleteAndThrow };
+            var options = new UploadObjectOptions { UploadValidationMode = UploadValidationMode.RejectAndThrow };
             var exception = await Assert.ThrowsAsync<GoogleApiException>(() => client.UploadObjectAsync(bucket, name, null, stream, options));
             Assert.Equal(HttpStatusCode.BadRequest, exception.HttpStatusCode);
-            var notFound = await Assert.ThrowsAsync<GoogleApiException>(() => _fixture.Client.GetObjectAsync(bucket, name));
-            Assert.Equal(HttpStatusCode.NotFound, notFound.HttpStatusCode);
         }
 
         [Fact]

apis/Google.Cloud.Storage.V1/Google.Cloud.Storage.V1/UploadObjectOptions.cs

@@ -32,7 +32,7 @@ public sealed class UploadObjectOptions
         /// </summary>
         public const int MinimumChunkSize = ResumableUpload<Object>.MinimumChunkSize;
 
-        internal static UploadValidationMode DefaultValidationMode { get; } = V1.UploadValidationMode.DeleteAndThrow;
+        internal static UploadValidationMode DefaultValidationMode { get; } = V1.UploadValidationMode.RejectAndThrow;
 
         /// <summary>
         /// Precondition for upload: the object is only uploaded if the existing object's

apis/Google.Cloud.Storage.V1/Google.Cloud.Storage.V1/UploadValidationMode.cs

@@ -1,4 +1,4 @@
-// Copyright 2017 Google Inc. All Rights Reserved.
+// Copyright 2017 Google Inc. All Rights Reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+using System;
+
 namespace Google.Cloud.Storage.V1
 {
     /// <summary>
@@ -29,6 +31,7 @@ public enum UploadValidationMode
         /// if the resulting object has a different hash, an <see cref="UploadValidationException"/>
         /// is thrown, but the object remains present in Storage.
         /// </summary>
+        [Obsolete("ThrowOnly is deprecated. Server-side validation will now automatically reject the upload, matching the behavior of RejectAndThrow.")]
         ThrowOnly = 1,
 
         /// <summary>
@@ -38,6 +41,13 @@ public enum UploadValidationMode
         /// is thrown. If the deletion fails, that failure can be examined via
         /// <see cref="UploadValidationException.AdditionalFailures"/>
         /// </summary>
-        DeleteAndThrow = 2
+        [Obsolete("DeleteAndThrow is deprecated. Use RejectAndThrow instead, as the server now rejects the object before creation.")]
+        DeleteAndThrow = 2,
+
+        /// <summary>
+        /// The server validates the object hash during upload. If a hash mismatch is detected, 
+        /// the server rejects the upload entirely, preventing the object from being created. 
+        /// </summary>
+        RejectAndThrow = 3
     }
 }