[API Proposal]: Expose Resilience HTTP Message Handler

[kmcclellan]

Background and motivation

I'm attempting to migrate from Microsoft.Extensions.Http.Polly to Microsoft.Extensions.Http.Resilience (see dotnet/docs#40841).

However, in my code base there are some scenarios where I want to bypass IHttpClientBuilder and instantiate an HTTP delegating message handler directly. The former library exposes a public PolicyHttpMessageHandler for this purpose. Can we consider exposing this library's handler?

To motivate, I'll illustrate two reasons I have found for bypassing the builder.

1. To prevent duplicate handlers from being registered when AddResilienceHandler is called more than once.
2. To configure multiple resilience handlers at once using the client name.

These can both be accomplished with a custom implementation of IConfigureNamedOptions<HttpClientFactoryOptions>:

class ConfigureHttpResilience : IConfigureNamedOptions<HttpClientFactoryOptions>
{
        public void Configure(string? name, HttpClientFactoryOptions options)
        {
            if (name != null)
            {
                // Create a custom resilience pipeline using the client name.
                var pipeline = GetPipeline(name);

                // Can't do this since ResilienceHandler is not public!
                options.HttpMessageHandlerBuilderActions.Add(
                    builder => builder.AdditionalHandlers.Add(new ResilienceHandler(x => pipeline)));
            }
        }
}

public static IServiceCollection AddHttpResilience(this IServiceCollection services)
{
    // "Try" prevents duplicates if this method is called more than once.
    services.TryAddEnumerable(
        ServiceDescriptor.Singleton<IConfigureOptions<HttpClientFactoryOptions>, ConfigureHttpResilience>());

    return services;
}

API Proposal

public class ResilienceHttpMessageHandler : DelegatingHandler
{
    public ResilienceHttpMessageHandler(ResiliencePipeline<HttpResponseMessage> pipeline)
    {
        throw new NotImplementedException();
    }

    public ResilienceHttpMessageHandler(Func<HttpRequestMessage, ResiliencePipeline<HttpResponseMessage>> pipelineProvider)
    {
        throw new NotImplementedException();
    }

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        throw new NotImplementedException();
    }
}

API Usage

options.HttpMessageHandlerBuilderActions.Add(x => x.AdditionalHandlers.Add(new ResilienceHttpMessageHandler(pipeline)));

Alternative Designs

No response

Risks

Future changes to the handler's public constructors are more likely to be breaking.

[joperezr]

Thanks for logging the proposal @kmcclellan 😃

Tagging @martintmk and @geeknoid so that they can have a closer look at the proposal.

[martintmk]

@joperezr LGTM

I was even thinking about exposing it too, but decided until there is a real use-case for this.

[wjrogers]

Please consider exposing ResilienceKeys.RequestMessage, too. If you don't want to make the key itself public, you could provide a GetRequestMessage(this ResilienceContext) extension method? Having access to the request in custom strategy logic is very useful.

[IGx89]

Here's a use case I believe from the official docs: https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/http/httpclient-guidelines#resilience-policies-with-static-clients. Currently attempting to follow that guidance using resilient pipelines but not having any luck so far.