Configuration providers

The provider interface

Configuration files cover the common case of loading from IConfiguration. To load from anywhere else, implement IProxyConfigProvider and IProxyConfig yourself.

IProxyConfigProvider has a single method, GetConfig(), returning an IProxyConfig - a snapshot with the current routes and clusters, plus an IChangeToken the provider signals whenever that snapshot is out of date, which causes the proxy to call GetConfig() again.

Loading routes and clusters directly

For the simplest case - routes and clusters known entirely in code - InMemoryConfigProvider is a ready-made IProxyConfigProvider:

C#services.AddReverseProxy().LoadFromMemory(routes, clusters);

To change that configuration later, resolve InMemoryConfigProvider from the service container and call Update:

C#httpContext.RequestServices.GetRequiredService<InMemoryConfigProvider>()
    .Update(routes, clusters);

Provider lifecycle

Startup

IProxyConfigProvider is registered as a singleton. At startup, the proxy resolves it and calls GetConfig() once; the provider can:

• throw, if it can't produce valid configuration - this prevents the application from starting;
• block synchronously until the configuration is loaded, which delays startup until valid route data is available; or
• return an empty IProxyConfig immediately and load in the background, signaling its IChangeToken once real data is ready.

Whatever configuration is returned is validated, and an invalid result throws an exception that prevents startup - a provider can pre-validate with IConfigValidator first and exclude invalid entries itself instead.

Route and cluster objects handed to the proxy should be treated as read-only once returned from GetConfig().

Reloading

If the IChangeToken supports active change callbacks, the proxy registers one after the initial load; otherwise HasChanged is polled every 5 minutes. To publish a new configuration, a provider should load it in the background - building new route/cluster instances, since they're immutable, though unchanged ones can be reused - optionally validate it, and only then signal the previous IChangeToken. The proxy calls GetConfig() again in response and diffs the result against the current configuration, updating only what changed; the swap is atomic and only affects new requests, not ones already in flight.

If several reloads are signaled in quick succession, the proxy may skip some and load whatever is available by the time it catches up - each IProxyConfig is a full snapshot, not a diff, so nothing is lost by skipping an intermediate one.

Multiple providers

More than one IProxyConfigProvider can be registered as a singleton; all of them are resolved and their configuration combined, the same way multiple configuration file sections can be. A route from one provider can reference a cluster from another, but a single route or cluster can't be assembled from partial data spread across two providers.