Made reliabilty settings immutable, refactored associated code

Author: dylan-asos

USE_CASES.md

@@ -587,28 +587,37 @@ namespace Example
 <a name="transient_faults"></a>
 # Transient Fault Handling
 
-The SendGridClient provides functionality for handling transient errors that might occur when sending an HttpRequest. This includes client side timeouts while sending the mail, or any errors returned within the 500 range. 
+The SendGridClient provides functionality for handling transient errors that might occur when sending an HttpRequest. This includes client side timeouts while sending the mail, or certain errors returned within the 500 range. Errors within the 500 range are limited to 500 Internal Server Error, 502 Bad Gateway, 503 Service unavailable and 504 Gateway timeout.
 
 By default, retry behaviour is off, you must explicitly enable it by setting the retry count to a value greater than zero. To set the retry count, you must use the SendGridClient construct that takes a **SendGridClientOptions** object, allowing you to configure the **ReliabilitySettings**
 
 ### RetryCount
 
-The amount of times to retry the operation before reporting an exception to the caller. This is in addition to the initial attempt, so setting a value of 1 would result in 2 attempts - the initial attempt and the retry. Defaults to zero, so retry behaviour is not enabled. The maximum amount of retries permitted is 5. 
+The amount of times to retry the operation before reporting an exception to the caller. This is in addition to the initial attempt so setting a value of 1 would result in 2 attempts, the initial attempt and the retry. Defaults to zero, retry behaviour is not enabled. The maximum amount of retries permitted is 5. 
 
-### RetryInterval
+### MinimumBackOff
+
+The minimum amount of time to wait between retries. 
+
+### MaximumBackOff
+
+The maximum possible amount of time to wait between retries. The maximum value allowed is 30 seconds
+
+### DeltaBackOff
+
+The value that will be used to calculate a random delta in the exponential delay between retries.  A random element of time is factored into the delta calculation as this helps avoid many clients retrying at regular intervals.
 
-The policy implemented is a 'wait and retry'. The RetryInterval setting defines the amount of time to wait between operations that fail before attempting a retry. By default, this is set to 1 second - the maximum amount of time allowed is 30 seconds. 
 
 ## Examples
 
-In this example, we are setting RetryCount to 1, with an interval between attempts of 5 seconds. This means that if the inital attempt to send mail fails, then it will wait 5 seconds then try again a single time. 
+In this example we are setting RetryCount to 2, with a mimimum wait time of 1 seconds, a maximum of 10 seconds and a delta of 3 seconds
 
 ```csharp
 
 var options = new SendGridClientOptions
 {
     ApiKey = "Your-Api-Key",
-    ReliabilitySettings = {RetryCount = 1, RetryInterval = TimeSpan.FromSeconds(5)}
+    ReliabilitySettings = new ReliabilitySettings(2, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(3))
 };
 
 var client = new SendGridClient(options);
@@ -622,7 +631,7 @@ The SendGridClientOptions object defines all the settings that can be set for th
 var options = new SendGridClientOptions
 {
     ApiKey = "Your-Api-Key",
-    ReliabilitySettings = {RetryCount = 1, RetryInterval = TimeSpan.FromSeconds(5)},
+    ReliabilitySettings = new ReliabilitySettings(2, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(3)),
     Host = "Your-Host",
     UrlPath = "Url-Path",
     Version = "3",

src/SendGrid/Reliability/ReliabilitySettings.cs

@@ -7,104 +7,82 @@ namespace SendGrid.Helpers.Reliability
     /// </summary>
     public class ReliabilitySettings
     {
-        private int maximumNumberOfRetries;
-
-        private TimeSpan minimumBackOff;
-        private TimeSpan maximumBackOff;
-        private TimeSpan deltaBackOff;
-
         /// <summary>
-        /// Initializes a new instance of the <see cref="ReliabilitySettings"/> class.
+        /// Initializes a new instance of the <see cref="ReliabilitySettings"/> class with default settings.
         /// </summary>
         public ReliabilitySettings()
+            : this(0, TimeSpan.Zero, TimeSpan.Zero, TimeSpan.Zero)
         {
-            this.maximumNumberOfRetries = 0;
-            this.minimumBackOff = TimeSpan.FromSeconds(1);
-            this.deltaBackOff = TimeSpan.FromSeconds(1);
-            this.maximumBackOff = TimeSpan.FromSeconds(10);
         }
 
         /// <summary>
-        ///     Gets or sets the maximum number of retries to execute against when sending an HTTP Request before throwing an exception. Defaults to 0 (no retries, you must explicitly enable)
+        /// Initializes a new instance of the <see cref="ReliabilitySettings"/> class.
         /// </summary>
-        public int MaximumNumberOfRetries
+        /// <param name="maximumNumberOfRetries">The maximum number of retries to execute against when sending an HTTP Request before throwing an exception</param>
+        /// <param name="minimumBackoff">The minimum amount of time to wait between between HTTP retries</param>
+        /// <param name="maximumBackOff">the maximum amount of time to wait between between HTTP retries</param>
+        /// <param name="deltaBackOff">the value that will be used to calculate a random delta in the exponential delay between retries</param>
+        public ReliabilitySettings(int maximumNumberOfRetries, TimeSpan minimumBackoff, TimeSpan maximumBackOff, TimeSpan deltaBackOff)
         {
-            get
+            if (maximumNumberOfRetries < 0)
             {
-                return this.maximumNumberOfRetries;
+                throw new ArgumentOutOfRangeException(nameof(maximumNumberOfRetries), "maximumNumberOfRetries must be greater than 0");
             }
 
-            set
+            if (maximumNumberOfRetries > 5)
             {
-                if (value < 0)
-                {
-                    throw new ArgumentException("Retry count must be greater than zero");
-                }
-
-                if (value > 5)
-                {
-                    throw new ArgumentException("The maximum number of retries that can be attempted is 5");
-                }
-
-                this.maximumNumberOfRetries = value;
+                throw new ArgumentOutOfRangeException(nameof(maximumNumberOfRetries), "The maximum number of retries allowed is 5");
             }
-        }
 
-        /// <summary>
-        /// Gets or sets the interval between HTTP retries. Defaults to 1 second
-        /// </summary>
-        public TimeSpan MinimumBackOff
-        {
-            get
+            if (minimumBackoff.Ticks < 0)
             {
-                return this.minimumBackOff;
+                throw new ArgumentOutOfRangeException(nameof(minimumBackoff), "minimumBackoff must be greater than 0");
             }
 
-            set
+            if (maximumBackOff.Ticks < 0)
             {
-                if (value.TotalSeconds > 30)
-                {
-                    throw new ArgumentException("The maximum setting for minimum back off is 30 seconds");
-                }
-
-                this.minimumBackOff = value;
+                throw new ArgumentOutOfRangeException(nameof(maximumBackOff), "maximumBackOff must be greater than 0");
             }
-        }
 
-        public TimeSpan MaximumBackOff
-        {
-            get
+            if (maximumBackOff.TotalSeconds > 30)
             {
-                return this.maximumBackOff;
+                throw new ArgumentOutOfRangeException(nameof(maximumBackOff), "maximumBackOff must be less than 30 seconds");
             }
 
-            set
+            if (deltaBackOff.Ticks < 0)
             {
-                if (value.TotalSeconds > 30)
-                {
-                    throw new ArgumentException("The maximum setting to back off for is 30 seconds");
-                }
-
-                this.maximumBackOff = value;
+                throw new ArgumentOutOfRangeException(nameof(deltaBackOff), "deltaBackOff must be greater than 0");
             }
-        }
 
-        public TimeSpan DeltaBackOff
-        {
-            get
+            if (minimumBackoff.TotalMilliseconds > maximumBackOff.TotalMilliseconds)
             {
-                return this.deltaBackOff;
+                throw new ArgumentOutOfRangeException(nameof(minimumBackoff), "minimumBackoff must be less than maximumBackOff");
             }
 
-            set
-            {
-                if (value.TotalSeconds > 30)
-                {
-                    throw new ArgumentException("The maximum delta interval is 5 seconds");
-                }
-
-                this.deltaBackOff = value;
-            }
+            this.MaximumNumberOfRetries = maximumNumberOfRetries;
+            this.MinimumBackOff = minimumBackoff;
+            this.DeltaBackOff = deltaBackOff;
+            this.MaximumBackOff = maximumBackOff;
         }
+
+        /// <summary>
+        ///     Gets the maximum number of retries to execute against when sending an HTTP Request before throwing an exception. Defaults to 0 (no retries, you must explicitly enable)
+        /// </summary>
+        public int MaximumNumberOfRetries { get; }
+
+        /// <summary>
+        /// Gets the minimum amount of time to wait between between HTTP retries. Defaults to 1 second
+        /// </summary>
+        public TimeSpan MinimumBackOff { get; }
+
+        /// <summary>
+        /// Gets the maximum amount of time to wait between between HTTP retries. Defaults to 10 seconds
+        /// </summary>
+        public TimeSpan MaximumBackOff { get; }
+
+        /// <summary>
+        /// Gets the value that will be used to calculate a random delta in the exponential delay between retries. Defaults to 1 second
+        /// </summary>
+        public TimeSpan DeltaBackOff { get; }
     }
 }

src/SendGrid/SendGridClientOptions.cs

@@ -1,5 +1,6 @@
 namespace SendGrid
 {
+    using System;
     using System.Collections.Generic;
     using SendGrid.Helpers.Reliability;
 
@@ -8,21 +9,27 @@
     /// </summary>
     public class SendGridClientOptions
     {
+        private ReliabilitySettings reliabilitySettings = new ReliabilitySettings();
+
         /// <summary>
         /// Initializes a new instance of the <see cref="SendGridClientOptions"/> class.
         /// </summary>
         public SendGridClientOptions()
         {
-            ReliabilitySettings = new ReliabilitySettings();
             RequestHeaders = new Dictionary<string, string>();
             Host = "https://api.sendgrid.com";
             Version = "v3";
         }
 
         /// <summary>
-        /// Gets the reliability settings to use on HTTP Requests
+        /// Gets or sets the reliability settings to use on HTTP Requests
         /// </summary>
-        public ReliabilitySettings ReliabilitySettings { get; }
+        public ReliabilitySettings ReliabilitySettings
+        {
+            get => this.reliabilitySettings;
+
+            set => this.reliabilitySettings = value ?? throw new ArgumentNullException(nameof(value));
+        }
 
         /// <summary>
         /// Gets or sets the SendGrid API key

tests/SendGrid.Tests/Integration.cs

@@ -6141,7 +6141,7 @@ public async Task TestRetryBehaviourThrowsTimeoutException()
             var options = new SendGridClientOptions
             {
                 ApiKey = fixture.apiKey,
-                ReliabilitySettings = { MaximumNumberOfRetries = 1 },
+                ReliabilitySettings = new ReliabilitySettings(1, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(1)),
                 Host = "http://localhost:4010"
             };
 
@@ -6169,7 +6169,7 @@ public async Task TestRetryBehaviourSucceedsOnSecondAttempt()
             var options = new SendGridClientOptions
             {
                 ApiKey = fixture.apiKey,
-                ReliabilitySettings = { MaximumNumberOfRetries = 1 }
+                ReliabilitySettings = new ReliabilitySettings(1, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(1))
             };
 
             var id = "test_url_param";

tests/SendGrid.Tests/Reliability/ReliabilitySettingsTests.cs

@@ -0,0 +1,106 @@
+namespace SendGrid.Tests.Reliability
+{
+    using System;
+
+    using Helpers.Reliability;
+    using Xunit;
+
+    public class ReliabilitySettingsTests
+    {
+        [Fact]
+        public void ShouldNotAllowNegativeRetryCount()
+        {
+            var exception = Assert.Throws<ArgumentOutOfRangeException>(() => 
+                new ReliabilitySettings(-1, 
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(1)));
+
+            Assert.Contains("maximumNumberOfRetries must be greater than 0", exception.Message);
+        }
+
+        [Fact]
+        public void ShouldNotAllowNegativeMinimumBackoffTime()
+        {
+            var exception = Assert.Throws<ArgumentOutOfRangeException>(() =>
+                new ReliabilitySettings(1,
+                    TimeSpan.FromSeconds(-1),
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(1)));
+
+            Assert.Contains("minimumBackoff must be greater than 0", exception.Message);
+        }
+
+        [Fact]
+        public void ShouldNotAllowNegativeMaximumBackoffTime()
+        {
+            var exception = Assert.Throws<ArgumentOutOfRangeException>(() =>
+                new ReliabilitySettings(1,
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(-11),
+                    TimeSpan.FromSeconds(1)));
+
+            Assert.Contains("maximumBackOff must be greater than 0", exception.Message);
+        }
+
+        [Fact]
+        public void ShouldNotAllowNegativeDeltaBackoffTime()
+        {
+            var exception = Assert.Throws<ArgumentOutOfRangeException>(() =>
+                new ReliabilitySettings(1,
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(-1)));
+
+            Assert.Contains("deltaBackOff must be greater than 0", exception.Message);
+        }
+
+        [Fact]
+        public void ShouldNotAllowRetryCountGreaterThan5()
+        {
+            var exception = Assert.Throws<ArgumentOutOfRangeException>(() =>
+                new ReliabilitySettings(6,
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(1)));
+
+            Assert.Contains("The maximum number of retries allowed is 5", exception.Message);
+        }
+
+        [Fact]
+        public void ShouldNotAllowMinimumBackOffGreaterThanMaximumBackoff()
+        {
+            var exception = Assert.Throws<ArgumentOutOfRangeException>(() =>
+                new ReliabilitySettings(1,
+                    TimeSpan.FromSeconds(11),
+                    TimeSpan.FromSeconds(10),
+                    TimeSpan.FromSeconds(1)));
+
+            Assert.Contains("minimumBackoff must be less than maximumBackOff", exception.Message);
+        }
+
+        [Fact]
+        public void ShouldNotAllowMaximumBackOffGreaterThan30Seconds()
+        {
+            var exception = Assert.Throws<ArgumentOutOfRangeException>(() =>
+                new ReliabilitySettings(1,
+                    TimeSpan.FromSeconds(1),
+                    TimeSpan.FromSeconds(31),
+                    TimeSpan.FromSeconds(1)));
+
+            Assert.Contains("maximumBackOff must be less than 30 seconds", exception.Message);
+        }
+
+        [Fact]
+        public void ShouldPassValidValuesFromDefaultConstruct()
+        {
+            var defaultSettings = new ReliabilitySettings();
+
+            Assert.Equal(TimeSpan.Zero, defaultSettings.MaximumBackOff);
+            Assert.Equal(TimeSpan.Zero, defaultSettings.MinimumBackOff);
+            Assert.Equal(TimeSpan.Zero, defaultSettings.DeltaBackOff);
+            Assert.Equal(0, defaultSettings.MaximumNumberOfRetries);
+        }
+    }
+}
+