GeoRedundantReadMode (Azure#30368)

* infra for georedundancy mode

* tests and blobclientoptions

* clientoptions successfully build policy

* datalake options

* queue redundancy

* exportapi

* Update sdk/core/Azure.Core/src/Shared/Argument.cs

Co-authored-by: JoshLove-msft <[email protected]>

* Update sdk/core/Azure.Core/src/Shared/Argument.cs

Co-authored-by: Jesse Squire <[email protected]>

* Argument.AssertEnumDefined docstrings

* removed redundant options

* exportapi

* changelog

Co-authored-by: JoshLove-msft <[email protected]>
Co-authored-by: Jesse Squire <[email protected]>

Author: 3 people

sdk/core/Azure.Core/src/Shared/Argument.cs

@@ -180,6 +180,21 @@ public static void AssertInRange<T>(T value, T minimum, T maximum, string name)
             }
         }
 
+        /// <summary>
+        /// Throws if <paramref name="value"/> is not defined for <paramref name="enumType"/>.
+        /// </summary>
+        /// <param name="enumType">The type to validate against.</param>
+        /// <param name="value">The value to validate.</param>
+        /// <param name="name">The name of the parameter.</param>
+        /// <exception cref="ArgumentException"><paramref name="value"/> is not defined for <paramref name="enumType"/>.</exception>
+        public static void AssertEnumDefined(Type enumType, object value, string name)
+        {
+            if (!Enum.IsDefined(enumType, value))
+            {
+                throw new ArgumentException($"Value not defined for {enumType.FullName}.", name);
+            }
+        }
+
         /// <summary>
         /// Throws if <paramref name="value"/> has not been initialized; otherwise, returns <paramref name="value"/>.
         /// </summary>

sdk/storage/Azure.Storage.Blobs/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 12.14.0-beta.2 (Unreleased)
 
 ### Features Added
+- Added support for "secondary then primary" read operations when using geo-redundant accounts.
 - Added support for leading and trailing '/' characters in blob names when constructing URIs via builder.
 
 ### Breaking Changes

sdk/storage/Azure.Storage.Blobs/api/Azure.Storage.Blobs.netstandard2.0.cs

@@ -55,6 +55,7 @@ public BlobClientOptions(Azure.Storage.Blobs.BlobClientOptions.ServiceVersion ve
         public Azure.Storage.Blobs.Models.CustomerProvidedKey? CustomerProvidedKey { get { throw null; } set { } }
         public bool EnableTenantDiscovery { get { throw null; } set { } }
         public string EncryptionScope { get { throw null; } set { } }
+        public Azure.Storage.GeoRedundantReadMode GeoRedundantReadMode { get { throw null; } set { } }
         public System.Uri GeoRedundantSecondaryUri { get { throw null; } set { } }
         public bool PreserveBlobNameSlashes { get { throw null; } set { } }
         public Azure.Storage.TransferValidationOptions TransferValidation { get { throw null; } }

sdk/storage/Azure.Storage.Blobs/api/Azure.Storage.Blobs.netstandard2.1.cs

@@ -55,6 +55,7 @@ public BlobClientOptions(Azure.Storage.Blobs.BlobClientOptions.ServiceVersion ve
         public Azure.Storage.Blobs.Models.CustomerProvidedKey? CustomerProvidedKey { get { throw null; } set { } }
         public bool EnableTenantDiscovery { get { throw null; } set { } }
         public string EncryptionScope { get { throw null; } set { } }
+        public Azure.Storage.GeoRedundantReadMode GeoRedundantReadMode { get { throw null; } set { } }
         public System.Uri GeoRedundantSecondaryUri { get { throw null; } set { } }
         public bool PreserveBlobNameSlashes { get { throw null; } set { } }
         public Azure.Storage.TransferValidationOptions TransferValidation { get { throw null; } }

sdk/storage/Azure.Storage.Blobs/src/BlobClientOptions.cs

@@ -135,6 +135,13 @@ public enum ServiceVersion
         /// </summary>
         public Uri GeoRedundantSecondaryUri { get; set; }
 
+        /// <summary>
+        /// Strategy to take when sending requests and retries between primary and secondary endpoints.
+        /// Ignored when <see cref="GeoRedundantSecondaryUri"/> is not set.
+        /// Defaults to <see cref="GeoRedundantReadMode.PrimaryThenSecondary"/>.
+        /// </summary>
+        public GeoRedundantReadMode GeoRedundantReadMode { get; set; }
+
         /// <summary>
         /// Configures whether to send or receive checksum headers for blob uploads and downloads. Downloads
         /// can optionally validate that the content matches the checksum.
@@ -299,7 +306,7 @@ private void AddHeadersAndQueryParameters()
         /// <returns>An HttpPipeline to use for Storage requests.</returns>
         internal HttpPipeline Build(HttpPipelinePolicy authentication = null)
         {
-            return this.Build(authentication, GeoRedundantSecondaryUri);
+            return this.Build(authentication, GeoRedundantSecondaryUri, GeoRedundantReadMode);
         }
 
         /// <summary>
@@ -309,7 +316,7 @@ internal HttpPipeline Build(HttpPipelinePolicy authentication = null)
         /// <returns>An HttpPipeline to use for Storage requests.</returns>
         internal HttpPipeline Build(object credentials)
         {
-            return this.Build(credentials, GeoRedundantSecondaryUri);
+            return this.Build(credentials, GeoRedundantSecondaryUri, GeoRedundantReadMode);
         }
 
         /// <inheritdoc />

sdk/storage/Azure.Storage.Blobs/tests/BlobClientOptionsTests.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Threading;
+using Azure.Core;
+using Azure.Core.TestFramework;
+using Azure.Storage.Test.Shared;
+using NUnit.Framework;
+
+namespace Azure.Storage.Blobs.Tests
+{
+    public class BlobClientOptionsTests
+    {
+        [Test]
+        public void SetGeoRedundancyMode()
+        {
+            const string primaryHost = "foo.blob.core.windows.net";
+            var primaryUri = new Uri("https://" + primaryHost);
+            const string secondaryHost = "foo-secondary.blob.core.windows.net";
+            var secondaryUri = new Uri("https://" + secondaryHost);
+
+            // set mode that changes first request
+            var options = new BlobClientOptions
+            {
+                GeoRedundantSecondaryUri = secondaryUri,
+                GeoRedundantReadMode = GeoRedundantReadMode.SecondaryThenPrimary,
+                Transport = new MockTransport(new MockResponse(200))
+            };
+            // policy to observe change in pipeline (observe changed to secondary host)
+            options.AddPolicy(
+                new AssertMessageContentsPolicy(checkRequest: r => Assert.AreEqual(secondaryHost, r.Uri.Host))
+                {
+                    CheckRequest = true
+                },
+                HttpPipelinePosition.PerRetry);
+
+            var request = new MockRequest()
+            {
+                Method = RequestMethod.Get,
+            };
+            // original request to primary host
+            request.Uri.Reset(primaryUri);
+
+            // Act
+            options.Build().SendRequest(request, CancellationToken.None);
+
+            // Assertion in pipeline
+        }
+    }
+}

sdk/storage/Azure.Storage.Common/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 12.13.0-beta.2 (Unreleased)
 
 ### Features Added
+- Added support for "secondary then primary" read operations when using geo-redundant accounts.
 
 ### Breaking Changes
 

sdk/storage/Azure.Storage.Common/api/Azure.Storage.Common.netstandard2.0.cs

@@ -20,6 +20,11 @@ public DownloadTransferValidationOptions() { }
         public bool AutoValidateChecksum { get { throw null; } set { } }
         public Azure.Storage.StorageChecksumAlgorithm ChecksumAlgorithm { get { throw null; } set { } }
     }
+    public enum GeoRedundantReadMode
+    {
+        PrimaryThenSecondary = 0,
+        SecondaryThenPrimary = 1,
+    }
     public enum StorageChecksumAlgorithm
     {
         Auto = 0,

sdk/storage/Azure.Storage.Common/src/GeoRedundantReadMode.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Azure.Storage
+{
+    /// <summary>
+    /// Pattern for retrying a read request between geo-redundant primary and secondary endpoints.
+    /// </summary>
+    public enum GeoRedundantReadMode
+    {
+        /// <summary>
+        /// Altnernate between primary and secondary endpoints, attempting primary first.
+        /// </summary>
+        PrimaryThenSecondary = 0,
+
+        /// <summary>
+        /// Altnernate between primary and secondary endpoints, attempting secondary first.
+        /// </summary>
+        SecondaryThenPrimary = 1
+    }
+}

sdk/storage/Azure.Storage.Common/src/Shared/GeoRedundantReadPolicy.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 using System;
+using System.Net.Mail;
 using Azure.Core;
 using Azure.Core.Pipeline;
 
@@ -15,13 +16,17 @@ internal class GeoRedundantReadPolicy : HttpPipelineSynchronousPolicy
     {
         private readonly string _secondaryStorageHost;
 
-        public GeoRedundantReadPolicy(Uri secondaryStorageUri)
+        private readonly GeoRedundantReadMode _mode;
+
+        public GeoRedundantReadPolicy(Uri secondaryStorageUri, GeoRedundantReadMode mode)
         {
             if (secondaryStorageUri == null)
             {
                 throw Errors.ArgumentNull(nameof(secondaryStorageUri));
             }
+            Argument.AssertEnumDefined(typeof(GeoRedundantReadMode), mode, nameof(mode));
             _secondaryStorageHost = secondaryStorageUri.Host;
+            _mode = mode;
         }
 
         public override void OnSendingRequest(HttpMessage message)
@@ -39,10 +44,28 @@ public override void OnSendingRequest(HttpMessage message)
                     out var alternateHostObj)
                 ? alternateHostObj as string
                 : null;
+            // first message
             if (alternateHost == null)
             {
-                // queue up the secondary host for subsequent retries
-                message.SetProperty(Constants.GeoRedundantRead.AlternateHostKey, _secondaryStorageHost);
+                string primaryHost = message.Request.Uri.Host;
+
+                // set appropriate first host
+                message.Request.Uri.Host = _mode switch
+                {
+                    GeoRedundantReadMode.PrimaryThenSecondary => primaryHost,
+                    GeoRedundantReadMode.SecondaryThenPrimary => _secondaryStorageHost,
+                    _ => throw BadModeError()
+                };
+
+                // queue up the appropriate host for subsequent retry
+                message.SetProperty(
+                    Constants.GeoRedundantRead.AlternateHostKey,
+                    _mode switch
+                    {
+                        GeoRedundantReadMode.PrimaryThenSecondary => _secondaryStorageHost,
+                        GeoRedundantReadMode.SecondaryThenPrimary => primaryHost,
+                        _ => throw BadModeError()
+                    });
                 return;
             }
 
@@ -75,5 +98,8 @@ public override void OnSendingRequest(HttpMessage message)
             message.Request.Uri.Host = alternateHost;
             message.SetProperty(Constants.GeoRedundantRead.AlternateHostKey, lastTriedHost);
         }
+
+        private InvalidOperationException BadModeError() => new(
+                $"Unexpected mode {Enum.GetName(typeof(GeoRedundantReadMode), _mode)} when alternating between primary and secondary endpoints.");
     }
 }