Ringleader 1.0.2

Ringleader

Extends the NET Core default HttpClientFactory to support managing and applying contextually appropriate primary handlers (i.e. unique certificates for different endpoints) while retaining the benefits of handler pooling and typed client pipelines

What is the problem?

NET Core's Default HttpClientFactory implementation offers a ton of benefits in terms of managing HttpClient instances, including reuse and disposal of primary handlers and adding handler pipelines and policies using named or typed clients, as described at https://docs.microsoft.com/en-us/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests

All instances of a named or typed client will use the same primary handler configuration, with the handler shared in the pool. For most per-request settings, this may not be an issue, but as the primary handler cannot be reconfigured per request and is not exposed once the HttpClient is returned, there is no way to customize certificates based on some contextual element of the request.

Suppose that we have a typed client called CommerceHttpClient with a well-defined set of calls and a robust delegating handler and retry pipeline. The service behind our typed client authenticates via certificates, and there are maybe 4 or 5 different certificates needed depending on the subdomain in the URL of a given request. Under the default HttpClientFactory implementation, you would need to register a different typed client and pipeline for each subdomain so that the primary handler delegate configures the certificate correctly, and moreso you would have to perform this registration for all known iterations of the sites at the composition root. Yikes...

A quick web search for "change certificate per request httpclientfactory" shows that this is not an uncommon problem, and most of the answers are less than ideal, summing up to "create your HttpClient manually," which means you lose the benefits of HttpClientFactory.

What is this package?

By adding in a few additional classes and components that wrap the existing DefaultHttpClientFactory implementation, we can establish a pattern for requesting a typed client that has a primary handler properly scoped for a given context, assuming that you can translate that context into a string and map it to configuration for a primary handler. That could be part of your request URL, your logged in user, the current date, whatever. Best of all, we keep all the base functionality and benefits that the HttpClientFactory can offer!

Under the hood, Ringleader directs the DefaultHttpClientFactory to create unique primary handlers in the pool specific to not only the typed client, but the passed context, as well. They will be managed and recycled just like any other handlers, and shoud not interfere with any handlers generated by other clients that are generated using the standard HttpClientFactory approach, including even the typed client you set up for Ringleader if you instantiate it that way.