Allow clients to specify a waiting time before retrying when watching. (#72)

Author: Choc13

README.md

@@ -82,7 +82,9 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApplica
    An `Action<ConsulLoadExceptionContext>` that can be used to configure how exceptions thrown during the first load should be handled.
 * **`OnWatchException`**
 
-   An `Action<ConsulWatchExceptionContext>` that can be used to configure how exceptions thrown when watching for changes should be handled.
+   A `Func<ConsulWatchExceptionContext, TimeSpan>` that can be used to configure how exceptions thrown when watching for changes should be handled.
+   The `TimeSpan` that is returned is used to set a delay before retrying. 
+   The `ConsulWatchExceptionContext` provides data that can be used to implement a backoff strategy or to cancel watching altogether.
 * **`Optional`**
 
    A `bool` that indicates whether the config is optional. If `false` then it will throw during the first load if the config is missing for the given key. Defaults to `false`.

src/Winton.Extensions.Configuration.Consul/ConsulConfigurationClient.cs

@@ -33,10 +33,10 @@ public async Task<QueryResult<KVPair[]>> GetConfig(string key, CancellationToken
 
         public IChangeToken Watch(
             string key,
-            Action<ConsulWatchExceptionContext> onException,
+            Func<ConsulWatchExceptionContext, TimeSpan> onException,
             CancellationToken cancellationToken)
         {
-            Task.Run(() => PollForChanges(key, onException, cancellationToken));
+            Task.Run(() => PollForChanges(key, onException, cancellationToken), cancellationToken);
             return _reloadToken;
         }
 
@@ -79,9 +79,10 @@ private async Task<bool> HasValueChanged(string key, CancellationToken cancellat
 
         private async Task PollForChanges(
             string key,
-            Action<ConsulWatchExceptionContext> onException,
+            Func<ConsulWatchExceptionContext, TimeSpan> onException,
             CancellationToken cancellationToken)
         {
+            var consecutiveFailureCount = 0;
             while (!cancellationToken.IsCancellationRequested)
             {
                 try
@@ -94,11 +95,16 @@ private async Task PollForChanges(
                         previousToken.OnReload();
                         return;
                     }
+
+                    consecutiveFailureCount = 0;
                 }
                 catch (Exception exception)
                 {
-                    var exceptionContext = new ConsulWatchExceptionContext(cancellationToken, exception);
-                    onException?.Invoke(exceptionContext);
+                    TimeSpan wait =
+                        onException?.Invoke(
+                            new ConsulWatchExceptionContext(cancellationToken, exception, ++consecutiveFailureCount)) ??
+                        TimeSpan.FromSeconds(5);
+                    await Task.Delay(wait, cancellationToken);
                 }
             }
         }

src/Winton.Extensions.Configuration.Consul/ConsulConfigurationProvider.cs

@@ -48,7 +48,12 @@ public override void Load()
             }
             catch (AggregateException aggregateException)
             {
-                throw aggregateException.InnerException;
+                if (aggregateException.InnerException != null)
+                {
+                    throw aggregateException.InnerException;
+                }
+
+                throw;
             }
         }
 

src/Winton.Extensions.Configuration.Consul/ConsulConfigurationSource.cs

@@ -39,7 +39,7 @@ public ConsulConfigurationSource(string key, CancellationToken cancellationToken
 
         public Action<ConsulLoadExceptionContext> OnLoadException { get; set; }
 
-        public Action<ConsulWatchExceptionContext> OnWatchException { get; set; }
+        public Func<ConsulWatchExceptionContext, TimeSpan> OnWatchException { get; set; }
 
         public bool Optional { get; set; } = false;
 

src/Winton.Extensions.Configuration.Consul/ConsulWatchExceptionContext.cs

@@ -11,9 +11,13 @@ namespace Winton.Extensions.Configuration.Consul
     /// </summary>
     public sealed class ConsulWatchExceptionContext
     {
-        internal ConsulWatchExceptionContext(CancellationToken cancellationToken, Exception exception)
+        internal ConsulWatchExceptionContext(
+            CancellationToken cancellationToken,
+            Exception exception,
+            int consecutiveFailureCount)
         {
             Exception = exception;
+            ConsecutiveFailureCount = consecutiveFailureCount;
             CancellationToken = cancellationToken;
         }
 
@@ -22,6 +26,14 @@ internal ConsulWatchExceptionContext(CancellationToken cancellationToken, Except
         /// </summary>
         public CancellationToken CancellationToken { get; }
 
+        /// <summary>
+        ///     Gets the number of consecutive failures that have occurred while watching for configuration changes.
+        /// </summary>
+        /// <remarks>
+        ///     This can be used to vary the time between retries, for example to create an exponential backoff algorithm.
+        /// </remarks>
+        public int ConsecutiveFailureCount { get; }
+
         /// <summary>
         ///     Gets the <see cref="Exception" /> that occured.
         /// </summary>

src/Winton.Extensions.Configuration.Consul/IConsulConfigurationClient.cs

@@ -9,23 +9,44 @@
 
 namespace Winton.Extensions.Configuration.Consul
 {
-    /// <summary>Provides client access for getting and watching config values in Consul.</summary>
+    /// <summary>
+    ///     Provides client access for getting and watching config values in Consul.
+    /// </summary>
     internal interface IConsulConfigurationClient
     {
-        /// <summary>Gets the config from consul asynchronously.</summary>
-        /// <param name="key">The key at which the config is located.</param>
-        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
-        /// <returns>A task containing the result of the query for the config.</returns>
+        /// <summary>
+        ///     Gets the config from consul asynchronously.
+        /// </summary>
+        /// <param name="key">
+        ///     The key at which the config is located.
+        /// </param>
+        /// <param name="cancellationToken">
+        ///     A cancellation token that can be used to cancel the operation.
+        /// </param>
+        /// <returns>
+        ///     A task containing the result of the query for the config.
+        /// </returns>
         Task<QueryResult<KVPair[]>> GetConfig(string key, CancellationToken cancellationToken);
 
-        /// <summary>Watches for config changes at a specified key.</summary>
-        /// <param name="key">The key whose value should be watched for changes.</param>
-        /// <param name="onException">An action to be invoked if an exception occurs during the watch.</param>
-        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
-        /// <returns>An <see cref="IChangeToken" /> that will indicated when changes have occured.</returns>
+        /// <summary>
+        ///     Watches for config changes at a specified key.
+        /// </summary>
+        /// <param name="key">
+        ///     The key whose value should be watched for changes.
+        /// </param>
+        /// <param name="onException">
+        ///     A function to be invoked if an exception occurs during the watch which returns the time to wait before making
+        ///     another attempt.
+        /// </param>
+        /// <param name="cancellationToken">
+        ///     A cancellation token that can be used to cancel the operation.
+        /// </param>
+        /// <returns>
+        ///     An <see cref="IChangeToken" /> that will indicated when changes have occured.
+        /// </returns>
         IChangeToken Watch(
             string key,
-            Action<ConsulWatchExceptionContext> onException,
+            Func<ConsulWatchExceptionContext, TimeSpan> onException,
             CancellationToken cancellationToken);
     }
 }

src/Winton.Extensions.Configuration.Consul/IConsulConfigurationSource.cs

@@ -65,10 +65,14 @@ public interface IConsulConfigurationSource : IConfigurationSource
         Action<ConsulLoadExceptionContext> OnLoadException { get; set; }
 
         /// <summary>
-        ///     Gets or sets an <see cref="Action" /> that is invoked when an exception is raised whilst watching.
-        ///     Used by clients to acknowledge the excetion and possibly cancel the watcher.
+        ///     Gets or sets a <see cref="Func{ConsulWatchException, TimeSpan}" /> that is invoked when an exception is raised whilst watching.
+        ///     The <see cref="TimeSpan"/> returned by the function is waited before trying again.
         /// </summary>
-        Action<ConsulWatchExceptionContext> OnWatchException { get; set; }
+        /// <remarks>
+        ///     This function is useful for implementing backoff strategies.
+        ///     It also provides access to the <see cref="CancellationToken"/> which can be used to cancel the watch task.
+        /// </remarks>
+        Func<ConsulWatchExceptionContext, TimeSpan> OnWatchException { get; set; }
 
         /// <summary>
         ///     Gets or sets a value indicating whether the config is optional.

src/Winton.Extensions.Configuration.Consul/Winton.Extensions.Configuration.Consul.csproj

@@ -26,7 +26,7 @@
 
   <ItemGroup>
     <AdditionalFiles Include="../../stylecop.json" />
-    <None Include="../../LICENSE" Pack="true" PackagePath=""/>
+    <None Include="../../LICENSE" Pack="true" PackagePath="" />
   </ItemGroup>
 
   <ItemGroup>

test/Winton.Extensions.Configuration.Consul.Test/ConsulConfigurationClientTests.cs

@@ -130,7 +130,7 @@ private async Task ShouldCallReloadOnChangeTokenIfIndexForKeyHasUpdated()
             }
 
             [Fact]
-            private async Task ShouldInvokeExceptionActionWhenWatchThrowsException()
+            private async Task ShouldInvokeOnExceptionWhenWatchThrowsException()
             {
                 Exception actualException = null;
                 var expectedException = new Exception();
@@ -147,6 +147,7 @@ private async Task ShouldInvokeExceptionActionWhenWatchThrowsException()
                     {
                         actualException = exceptionContext.Exception;
                         configChangedCompletion.SetResult(true);
+                        return TimeSpan.FromSeconds(5);
                     },
                     default(CancellationToken));
 
@@ -200,7 +201,7 @@ private async Task ShouldUseLongPollingToPollForChanges()
 
                 await watchCompletion.Task;
 
-                Action verifying = () => _kvMock
+                _kvMock
                     .Verify(
                         kv => kv.List("Test", It.IsAny<QueryOptions>(), default(CancellationToken)),
                         Times.Exactly(6));

test/Winton.Extensions.Configuration.Consul.Test/ConsulConfigurationProviderTests.cs

@@ -260,7 +260,7 @@ public Reload()
                         ccc =>
                             ccc.Watch(
                                 "Test",
-                                It.IsAny<Action<ConsulWatchExceptionContext>>(),
+                                It.IsAny<Func<ConsulWatchExceptionContext, TimeSpan>>(),
                                 default(CancellationToken)))
                     .Returns(_firstChangeToken)
                     .Returns(new ConfigurationReloadToken());