Quick pass at some YARP improvements (#35119)

* Quick pass at some YARP improvements

* Update aspnetcore/fundamentals/servers/yarp/dests-health-checks.md

---------

Co-authored-by: Rick Anderson <[email protected]>

Author: benhopkinstech

aspnetcore/fundamentals/servers/yarp/config-providers.md

@@ -68,10 +68,10 @@ The configuration objects and collections supplied to the proxy should be read-o
 If the `IChangeToken` supports `ActiveChangeCallbacks`, once the proxy has processed the initial set of configurations it will register a callback with this token. If the provider does not support callbacks then `HasChanged` will be polled every 5 minutes.
 
 When the provider wants to provide a new configuration to the proxy it should:
-- load that configuration in the background. 
+- Load that configuration in the background. 
   - Route and cluster objects are immutable, so new instances have to be created for any new data.
   - Objects for unchanged routes and clusters can be re-used, or new instances can be created - changes will be detected by diffing them.
-- optionally validate the configuration using the [IConfigValidator](xref:Yarp.ReverseProxy.Configuration.IConfigValidator), and only then signal the `IChangeToken` from the prior `IProxyConfig` instance that new data is available. The proxy will call `GetConfig()` again to retrieve the new data.
+- Optionally validate the configuration using the [IConfigValidator](xref:Yarp.ReverseProxy.Configuration.IConfigValidator), and only then signal the `IChangeToken` from the prior `IProxyConfig` instance that new data is available. The proxy will call `GetConfig()` again to retrieve the new data.
 
 There are important differences when reloading configuration vs the first configuration load.
 - The new configuration will be diffed against the current one and only modified routes or clusters will be updated. The update will be applied atomically and will only affect new requests, not requests currently in progress.

aspnetcore/fundamentals/servers/yarp/dests-health-checks.md

@@ -84,12 +84,12 @@ Active health check settings can also be defined in code via the corresponding t
 
 `Cluster/HealthCheck/Active` section and [ActiveHealthCheckConfig](xref:Yarp.ReverseProxy.Configuration.ActiveHealthCheckConfig):
 
-- `Enabled` - flag indicating whether active health check is enabled for a cluster. Default `false`
-- `Interval` - period of sending health probing requests. Default `00:00:15`
-- `Timeout` - probing request timeout. Default `00:00:10`
-- `Policy` - name of a policy evaluating destinations' active health states. Mandatory parameter
-- `Path` -  health check path on all cluster's destinations. Default `null`.
-- `Query` -  health check query on all cluster's destinations. Default `null`.
+- `Enabled`: Flag indicating whether active health check is enabled for a cluster. Default `false`
+- `Interval`: Period of sending health probing requests. Default `00:00:15`
+- `Timeout`: Probing request timeout. Default `00:00:10`
+- `Policy`: Name of a policy evaluating destinations' active health states. Mandatory parameter
+- `Path`: Health check path on all cluster's destinations. Default `null`.
+- `Query`: Health check query on all cluster's destinations. Default `null`.
 
 `Destination` section and [DestinationConfig](xref:Yarp.ReverseProxy.Configuration.DestinationConfig).
 
@@ -346,10 +346,10 @@ public class FirstUnsuccessfulResponseHealthPolicy : IPassiveHealthCheckPolicy
 ## Available destination collection
 Destinations health state is used to determine which of them are eligible for receiving proxied requests. Each cluster maintains its own list of available destinations on `AvailableDestinations` property of the [ClusterDestinationState](xref:Yarp.ReverseProxy.Model.ClusterDestinationsState) type. That list gets rebuilt when any destination's health state changes. The [IClusterDestinationsUpdater](xref:Yarp.ReverseProxy.Health.IClusterDestinationsUpdater) controls that process and calls an [IAvailableDestinationsPolicy](xref:Yarp.ReverseProxy.Health.IAvailableDestinationsPolicy) configured on the cluster to actually choose the available destinations from the all cluster's destinations. There are the following built-in policies provided and custom ones can be implemented if necessary.
 
-- `HealthyAndUnknown` - inspects each `DestinationState` and adds it on the available destination list if all of the following statements are TRUE. If no destinations are available then requests will get a 503 error.
+- `HealthyAndUnknown` - Inspects each `DestinationState` and adds it on the available destination list if all of the following statements are TRUE. If no destinations are available then requests will get a 503 error.
     - Active health checks are disabled on the cluster OR `DestinationHealthState.Active != DestinationHealth.Unhealthy`
     - Passive health checks are disabled on the cluster OR `DestinationHealthState.Passive != DestinationHealth.Unhealthy`
-- `HealthyOrPanic` - calls `HealthyAndUnknown` policy at first to get the available destinations. If none of them are returned from this call, it marks all cluster's destinations as available. This is the default policy.
+- `HealthyOrPanic` - Calls `HealthyAndUnknown` policy at first to get the available destinations. If none of them are returned from this call, it marks all cluster's destinations as available. This is the default policy.
 
 **NOTE**: An available destination policy configured on a cluster will be always called regardless of if any health check is enabled on the given cluster. The health state of a disabled health check is set to `Unknown`.
 

aspnetcore/fundamentals/servers/yarp/diagnosing-yarp-issues.md

@@ -247,5 +247,5 @@ It can be attractive to use network tracing tools like [Fiddler](https://www.tel
 - Fiddler registers itself as a proxy and relies on applications using the default proxy to be able to monitor traffic. This works for inbound traffic from a browser to YARP, but will not capture the outbound requests as YARP is configured to not use the proxy settings for outbound traffic.
 - On windows Wireshark uses Npcap to capture packet data for network traffic, so it will capture both inbound and outbound traffic, and can be used to monitor HTTP traffic. Wireshark works out of the box for HTTP traffic.
 - HTTPS traffic is encrypted, and so is not automatically decryptable by network monitoring tools. Each tool has workarounds that may enable traffic to be monitored, but they require hacking around with certificates and trust relationships. Because YARP is making outbound requests, techniques for tricking browsers do not apply to the YARP process.
-  
+
 The protocol choice for outbound traffic is made based on the destination URL in the cluster configuration. If traffic monitoring is being used for diagnostics then, if possible, changing the outbound URLs to "http://" may be simplest approach to enable the monitoring tools to work, provided the issues being diagnosed are not transport protocol related.

aspnetcore/fundamentals/servers/yarp/grpc.md

@@ -20,7 +20,7 @@ ai-usage: ai-assisted
 
 gRPC requires HTTP/2 for most scenarios. HTTP/1.1 and HTTP/2 are enabled by default on ASP.NET Core servers (YARP's front end) but they require https (TLS) for HTTP/2 so YARP needs to be listening on a `https://` URL.
 
-HTTP/2 over http (non-TLS) is only supported on Kestrel and requires specific settings.  For details see [here](/aspnet/core/grpc/aspnetcore#server-options).
+HTTP/2 over http (non-TLS) is only supported on Kestrel and requires specific settings. For details see [here](/aspnet/core/grpc/aspnetcore#server-options).
 
 This shows configuring Kestrel to use HTTP/2 over http (non-TLS):
 ```json

aspnetcore/fundamentals/servers/yarp/http-client-config.md

@@ -26,7 +26,7 @@ These types are focused on defining serializable configuration. The code based c
 ### HttpClient
 HTTP client configuration is based on [HttpClientConfig](xref:Yarp.ReverseProxy.Configuration.HttpClientConfig) and represented by the following configuration schema. If you need a more granular approach, use a <!--check link--> [custom implementation](xref:fundamentals/servers/yarp/http-client-config#custom-iforwarderhttpclientfactory) of `IForwarderHttpClientFactory`.
 
-<!-- original linke [custom implementation](https://microsoft.github.io/reverse-proxy/articles/http-client-config.html#custom-iforwarderhttpclientfactory)   -->
+<!-- original linke [custom implementation](https://microsoft.github.io/reverse-proxy/articles/http-client-config.html#custom-iforwarderhttpclientfactory) -->
 ```JSON
 "HttpClient": {
   "SslProtocols": [ "<protocol-names>" ],

aspnetcore/fundamentals/servers/yarp/load-balancing.md

@@ -72,22 +72,27 @@ var clusters = new[]
 ## Built-in policies
 
 YARP ships with the following built-in policies:
+
 - `FirstAlphabetical`
 
-    Select the alphabetically first available destination without considering load. This is useful for dual destination fail-over systems.
+Select the alphabetically first available destination without considering load. This is useful for dual destination fail-over systems.
+
 - `Random`
 
-    Select a destination randomly.
+Select a destination randomly.
+
 - `PowerOfTwoChoices` (default)
 
-    Select two random destinations and then select the one with the least assigned requests.
-    This avoids the overhead of `LeastRequests` and the worst case for `Random` where it selects a busy destination.
+Select two random destinations and then select the one with the least assigned requests.
+This avoids the overhead of `LeastRequests` and the worst case for `Random` where it selects a busy destination.
+
 - `RoundRobin`
 
-    Select a destination by cycling through them in order.
+Select a destination by cycling through them in order.
+
 - `LeastRequests`
 
-    Select the destination with the least assigned requests. This requires examining all destinations.
+Select the destination with the least assigned requests. This requires examining all destinations.
 
 ## Extensibility
 

aspnetcore/fundamentals/servers/yarp/middleware.md

@@ -112,7 +112,7 @@ Middleware like session affinity and load balancing examine the `IReverseProxyFe
 
 `AvailableDestinations` lists the destinations currently considered eligible to handle the request. It is initialized to `AllDestinations`, excluding unhealthy ones if health checks are enabled. `AvailableDestinations` should be reduced to a single destination by the end of the pipeline or else one will be selected randomly from the remainder.
 
-`ProxiedDestination` is set by the proxy logic at the end of the pipeline to indicate which destination was ultimately used.  If there are no available destinations remaining then a 503 error response is sent.
+`ProxiedDestination` is set by the proxy logic at the end of the pipeline to indicate which destination was ultimately used. If there are no available destinations remaining then a 503 error response is sent.
 
 ```C#
 proxyPipeline.Use(async (context, next) =>

aspnetcore/fundamentals/servers/yarp/session-affinity.md

@@ -118,7 +118,7 @@ The `Cookie` and `CustomHeader` policies encrypt the key using Data Protection.
 ## Affinity failure policy
 If the affinity key cannot be decoded or no healthy destination found it's considered as a failure and an affinity failure policy is called to handle it. The policy has the full access to `HttpContext` and can send response to the client by itself. It returns a boolean value indicating whether the request processing can proceed down the pipeline or must be terminated.
 
-There are two built-in failure policies.  The default is `Redistribute`.
+There are two built-in failure policies. The default is `Redistribute`.
 1. `Redistribute` - tries to establish a new affinity to one of available healthy destinations by skipping the affinity lookup step and passing all healthy destination to the load balancer the same way it is done for a request without any affinity. Request processing continues. This is implemented by `RedistributeAffinityFailurePolicy`.
 
 2. `Return503Error` - sends a `503` response back to the client and request processing is terminated. This is implemented by `Return503ErrorAffinityFailurePolicy`

aspnetcore/fundamentals/servers/yarp/transforms-response.md

@@ -1,7 +1,7 @@
 ---
 uid: fundamentals/servers/yarp/transforms-response
 title: YARP Response and Response Trailer Transforms
-description: YARP Response and Response Trailer  Transforms
+description: YARP Response and Response Trailer Transforms
 author: samsp-msft
 ms.author: samsp
 ms.date: 2/6/2025

aspnetcore/fundamentals/servers/yarp/transforms.md

@@ -45,7 +45,7 @@ X-Forwarded-Host: IncomingHost:5000
 
 ## Transform Categories
 
-Transforms fall into a few categories: [Request](./transforms-request.md), [Response](./transforms-response.md), and [Response Trailers](./transforms-response.md#responsetrailer).  Request trailers are not supported because they are not supported by the underlying HttpClient.
+Transforms fall into a few categories: [Request](./transforms-request.md), [Response](./transforms-response.md), and [Response Trailers](./transforms-response.md#responsetrailer). Request trailers are not supported because they are not supported by the underlying HttpClient.
 
 If the built-in set of transforms is insufficient, then custom transforms can be added via [extensibility](./extensibility-transforms.md).