Merge branch 'develop' into stable

Author: Pathoschild

Client/Client.csproj

@@ -1,20 +1,19 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
   <PropertyGroup>
     <TargetFrameworks>netstandard1.3;netstandard2.0;net45</TargetFrameworks>
     <AssemblyName>Pathoschild.Http.Client</AssemblyName>
     <RootNamespace>Pathoschild.Http.Client</RootNamespace>
     <PackageId>Pathoschild.Http.FluentClient</PackageId>
     <Title>FluentHttpClient</Title>
-    <Version>4.0.0</Version>
+    <Version>4.1.0</Version>
     <Authors>Pathoschild</Authors>
     <Description>A modern async HTTP client for REST APIs. Its fluent interface lets you send an HTTP request and parse the response in one go.</Description>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/Pathoschild/FluentHttpClient#readme</PackageProjectUrl>
     <PackageIcon>images/package-icon.png</PackageIcon>
     <RepositoryType>git</RepositoryType>
     <RepositoryUrl>https://github.com/Pathoschild/FluentHttpClient.git</RepositoryUrl>
-    <PackageReleaseNotes>See release notes at https://github.com/Pathoschild/FluentHttpClient/blob/develop/RELEASE-NOTES.md#40</PackageReleaseNotes>
+    <PackageReleaseNotes>See release notes at https://github.com/Pathoschild/FluentHttpClient/blob/develop/RELEASE-NOTES.md</PackageReleaseNotes>
     <PackageTags>wcf;web;webapi;HttpClient;FluentHttp;FluentHttpClient</PackageTags>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
@@ -36,5 +35,4 @@
   <ItemGroup>
     <None Include="package-icon.png" Pack="true" PackagePath="images/" />
   </ItemGroup>
-
 </Project>

Client/FluentClientExtensions.cs

@@ -3,7 +3,6 @@
 using System.IO;
 using System.Linq;
 using System.Net.Http;
-using System.Reflection;
 using System.Text;
 using System.Threading.Tasks;
 using Pathoschild.Http.Client.Extensibility;
@@ -171,12 +170,20 @@ public static IClient SetRequestCoordinator(this IClient client, int maxRetries,
 
         /// <summary>Set the default request coordinator.</summary>
         /// <param name="client">The client.</param>
-        /// <param name="config">The retry configuration (or null for the default coordinator).</param>
+        /// <param name="config">The retry configuration to apply (or null for the default coordinator).</param>
         public static IClient SetRequestCoordinator(this IClient client, IRetryConfig? config)
         {
             return client.SetRequestCoordinator(new RetryCoordinator(config));
         }
 
+        /// <summary>Set the default request coordinator.</summary>
+        /// <param name="client">The client.</param>
+        /// <param name="configs">The retry configurations to apply (or null for the default behavior). Each configuration will have the opportunity to retry a request.</param>
+        public static IClient SetRequestCoordinator(this IClient client, IEnumerable<IRetryConfig?>? configs)
+        {
+            return client.SetRequestCoordinator(new RetryCoordinator(configs));
+        }
+
         /// <summary>Set default options for all requests.</summary>
         /// <param name="client">The client.</param>
         /// <param name="ignoreHttpErrors">Whether to ignore null arguments when the request is dispatched (or <c>null</c> to leave the option unchanged).</param>
@@ -217,18 +224,15 @@ public static IRequest WithBearerAuthentication(this IRequest request, string to
         /// <exception cref="InvalidOperationException">No MediaTypeFormatters are available on the API client for this content type.</exception>
         public static IRequest WithBody<T>(this IRequest request, T body)
         {
-            if (body == null)
-                throw new ArgumentNullException(nameof(body));
-
-            // HttpContent
-            if (typeof(HttpContent).GetTypeInfo().IsAssignableFrom(typeof(T).GetTypeInfo()))
-                return request.WithBody(p => (HttpContent)(object)body);
-
-            // model
-            return request.WithBody(p => p.Model(body));
+            return request.WithBody(builder => body switch
+            {
+                null => null,
+                HttpContent content => content,
+                _ => builder.Model(body)
+            });
         }
 
-        /// <summary>Set the request coordinator for this request</summary>
+        /// <summary>Set the request coordinator for this request.</summary>
         /// <param name="request">The request.</param>
         /// <param name="shouldRetry">A lambda which returns whether a request should be retried.</param>
         /// <param name="intervals">The intervals between each retry attempt.</param>
@@ -237,7 +241,7 @@ public static IRequest WithRequestCoordinator(this IRequest request, Func<HttpRe
             return request.WithRequestCoordinator(new RetryCoordinator(shouldRetry, intervals));
         }
 
-        /// <summary>Set the request coordinator for this request</summary>
+        /// <summary>Set the request coordinator for this request.</summary>
         /// <param name="request">The request.</param>
         /// <param name="maxRetries">The maximum number of times to retry a request before failing.</param>
         /// <param name="shouldRetry">A method which returns whether a request should be retried.</param>
@@ -247,14 +251,22 @@ public static IRequest WithRequestCoordinator(this IRequest request, int maxRetr
             return request.WithRequestCoordinator(new RetryCoordinator(maxRetries, shouldRetry, getDelay));
         }
 
-        /// <summary>Set the request coordinator for this request</summary>
+        /// <summary>Set the request coordinator for this request.</summary>
         /// <param name="request">The request.</param>
-        /// <param name="config">The retry config (or null to use the default behaviour).</param>
+        /// <param name="config">The retry config (or null for the default behavior).</param>
         public static IRequest WithRequestCoordinator(this IRequest request, IRetryConfig? config)
         {
             return request.WithRequestCoordinator(new RetryCoordinator(config));
         }
 
+        /// <summary>Set the request coordinator for this request.</summary>
+        /// <param name="request">The request.</param>
+        /// <param name="configs">The retry configurations to apply (or null for the default behavior). Each configuration will have the opportunity to retry a request.</param>
+        public static IRequest WithRequestCoordinator(this IRequest request, IEnumerable<IRetryConfig?>? configs)
+        {
+            return request.WithRequestCoordinator(new RetryCoordinator(configs));
+        }
+
         /// <summary>Set options for this request.</summary>
         /// <param name="request">The request.</param>
         /// <param name="ignoreHttpErrors">Whether to ignore null arguments when the request is dispatched (or <c>null</c> to leave the option unchanged).</param>

Client/IRequest.cs

@@ -43,7 +43,7 @@ public interface IRequest
         /// <summary>Set the body content of the HTTP request.</summary>
         /// <param name="bodyBuilder">The HTTP body builder.</param>
         /// <returns>Returns the request builder for chaining.</returns>
-        IRequest WithBody(Func<IBodyBuilder, HttpContent> bodyBuilder);
+        IRequest WithBody(Func<IBodyBuilder, HttpContent?> bodyBuilder);
 
         /// <summary>Set an HTTP header.</summary>
         /// <param name="key">The key of the HTTP header.</param>

Client/Internal/Request.cs

@@ -71,7 +71,7 @@ public Request(HttpRequestMessage message, MediaTypeFormatterCollection formatte
         /// <summary>Set the body content of the HTTP request.</summary>
         /// <param name="bodyBuilder">The HTTP body builder.</param>
         /// <returns>Returns the request builder for chaining.</returns>
-        public IRequest WithBody(Func<IBodyBuilder, HttpContent> bodyBuilder)
+        public IRequest WithBody(Func<IBodyBuilder, HttpContent?> bodyBuilder)
         {
             this.Message.Content = bodyBuilder(new BodyBuilder(this));
             return this;

Client/Retry/RetryCoordinator.cs

@@ -1,4 +1,6 @@
 using System;
+using System.Collections.Generic;
+using System.Linq;
 using System.Net;
 using System.Net.Http;
 using System.Threading.Tasks;
@@ -12,8 +14,8 @@ public class RetryCoordinator : IRequestCoordinator
         /*********
         ** Fields
         *********/
-        /// <summary>The retry configuration.</summary>
-        private readonly IRetryConfig Config;
+        /// <summary>The retry configurations to apply.</summary>
+        private readonly IRetryConfig[] Configs;
 
         /// <summary>The status code representing a request timeout.</summary>
         /// <remarks>HTTP 598 Network Read Timeout is the closest match, though it's non-standard so there's no <see cref="HttpStatusCode"/> constant. This is needed to avoid passing <c>null</c> into <see cref="IRetryConfig.ShouldRetry"/>, which isn't intuitive and would cause errors.</remarks>
@@ -37,10 +39,18 @@ public RetryCoordinator(int maxRetries, Func<HttpResponseMessage, bool> shouldRe
            : this(new RetryConfig(maxRetries, shouldRetry, getDelay)) { }
 
         /// <summary>Construct an instance.</summary>
-        /// <param name="config">The retry configuration.</param>
+        /// <param name="config">The retry configuration to apply.</param>
         public RetryCoordinator(IRetryConfig? config)
+            : this(new[] { config }) { }
+
+        /// <summary>Construct an instance.</summary>
+        /// <param name="configs">The retry configurations to apply. Each config will be given the opportunity to retry a request.</param>
+        public RetryCoordinator(IEnumerable<IRetryConfig?>? configs)
         {
-            this.Config = config ?? RetryConfig.None();
+            this.Configs = configs
+                ?.Where(config => config != null)
+                .Select(config => config!)
+                .ToArray() ?? new IRetryConfig[0];
         }
 
         /// <summary>Dispatch an HTTP request.</summary>
@@ -50,7 +60,6 @@ public RetryCoordinator(IRetryConfig? config)
         public async Task<HttpResponseMessage> ExecuteAsync(IRequest request, Func<IRequest, Task<HttpResponseMessage>> dispatcher)
         {
             int attempt = 0;
-            int maxAttempt = 1 + this.Config.MaxRetries;
             while (true)
             {
                 // dispatch request
@@ -65,14 +74,28 @@ public async Task<HttpResponseMessage> ExecuteAsync(IRequest request, Func<IRequ
                     response = request.Message.CreateResponse(this.TimeoutStatusCode);
                 }
 
-                // exit if done
-                if (!this.Config.ShouldRetry(response))
+                // find the applicable retry configuration
+                IRetryConfig? retryConfig = null;
+                foreach (var config in this.Configs)
+                {
+                    if (config.ShouldRetry(response))
+                    {
+                        retryConfig = config;
+                        break;
+                    }
+                }
+
+                // exit if we can't retry
+                if (retryConfig == null)
                     return response;
+
+                // throw exception if we've exceeded max retries
+                int maxAttempt = 1 + retryConfig.MaxRetries;
                 if (attempt >= maxAttempt)
-                    throw new ApiException(new Response(response, request.Formatters), $"The HTTP request {(response != null ? "failed" : "timed out")}, and the retry coordinator gave up after the maximum {this.Config.MaxRetries} retries");
+                    throw new ApiException(new Response(response, request.Formatters), $"The HTTP request {(response != null ? "failed" : "timed out")}, and the retry coordinator gave up after the maximum {retryConfig.MaxRetries} retries");
 
                 // set up retry
-                TimeSpan delay = this.Config.GetDelay(attempt, response);
+                TimeSpan delay = retryConfig.GetDelay(attempt, response);
                 if (delay.TotalMilliseconds > 0)
                     await Task.Delay(delay).ConfigureAwait(false);
             }

README.md

@@ -44,6 +44,7 @@ The client works on most platforms (including Linux, Mac, and Windows):
 
 | platform                    | min version |
 | :-------------------------- | :---------- |
+| .NET                        | 5.0         |
 | .NET Core                   | 1.0         |
 | .NET Framework              | 4.5         |
 | [.NET Standard][]           | 1.3         |
@@ -224,6 +225,51 @@ client
    );
 ```
 
+### Chained retry policies
+You can also wrap retry logic into `IRetryConfig` implementations:
+
+```c#
+/// <summary>A retry policy which retries with incremental backoff.</summary>
+public class RetryWithBackoffConfig : IRetryConfig
+{
+    /// <summary>The maximum number of times to retry a request before failing.</summary>
+    public int MaxRetries => 3;
+
+    /// <summary>Get whether a request should be retried.</summary>
+    /// <param name="response">The last HTTP response received.</param>
+    public bool ShouldRetry(HttpResponseMessage response)
+    {
+        return request.StatusCode != HttpStatusCode.OK;
+    }
+
+    /// <summary>Get the time to wait until the next retry.</summary>
+    /// <param name="attempt">The retry index (starting at 1).</param>
+    /// <param name="response">The last HTTP response received.</param>
+    public TimeSpan GetDelay(int attempt, HttpResponseMessage response)
+    {
+        return TimeSpan.FromSeconds(attempt * 5); // wait 5, 10, and 15 seconds
+    }
+}
+```
+
+Then you can add one or more retry policies, and they'll each be given the opportunity to retry
+a request:
+
+```c#
+client
+   .SetRequestCoordinator(new[]
+   {
+      new TokenExpiredRetryConfig(),
+      new DatabaseTimeoutRetryConfig(),
+      new RetryWithBackoffConfig()
+   });
+```
+
+Note that there's one retry count across all retry policies. For example, if
+`TokenExpiredRetryConfig` retries once before falling back to `RetryWithBackoffConfig`, the latter
+will receive `2` as its first retry count. If you need more granular control, see [_custom
+retry/coordination policy_](#custom-retrycoordination-policy).
+
 ### Cancellation tokens
 The client fully supports [.NET cancellation tokens](https://msdn.microsoft.com/en-us/library/dd997364.aspx)
 if you need to abort requests:

RELEASE-NOTES.md

@@ -1,4 +1,10 @@
 # Release notes
+## 4.1
+Released 11 March 2021.
+
+* Added support for [chained retry policies](README.md#chained-retry-policies) (thanks to Jericho!).
+* Fixed `WithBody(null)` no longer allowed in 4.0.
+
 ## 4.0
 Released 13 May 2020.
 

Tests/Client/RequestTests.cs

@@ -551,7 +551,7 @@ public void WithHeader(string methodName, string key, string value)
             IRequest request = this
                 .ConstructRequest(methodName)
                 .WithHeader(key, value);
-            var header = request.Message.Headers.FirstOrDefault(p => p.Key == key);
+            var header = request.Message.Headers.FirstOrDefault(p => string.Equals(p.Key, key, StringComparison.OrdinalIgnoreCase));
 
             // assert
             this.AssertEqual(request.Message, methodName, ignoreArguments: true);

Tests/Tests.csproj

@@ -1,5 +1,4 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
   <PropertyGroup>
     <TargetFrameworks>netcoreapp1.1;netcoreapp2.0;net451</TargetFrameworks>
     <AssemblyName>Pathoschild.Http.Tests</AssemblyName>
@@ -32,5 +31,4 @@
   <ItemGroup>
     <Service Include="{82a7f48d-3b50-4b1e-b82e-3ada8210c358}" />
   </ItemGroup>
-
 </Project>