Implement failure only transforms

docs/docfx/articles/transforms.md

@@ -724,7 +724,7 @@ This sets if all proxy response headers are copied to the client response. This
 |-----|-------|---------|----------|
 | ResponseHeader | The header name | (none) | yes |
 | Set/Append | The header value | (none) | yes |
-| When | Success/Always | Success | no |
+| When | Success/Always/Failure | Success | no |
 
 Config:
 ```JSON
@@ -736,10 +736,10 @@ Config:
 ```
 Code:
 ```csharp
-routeConfig = routeConfig.WithTransformResponseHeader(headerName: "HeaderName", value: "value", append: true, always: false);
+routeConfig = routeConfig.WithTransformResponseHeader(headerName: "HeaderName", value: "value", append: true, ResponseCondition.Success);
 ```
 ```C#
-transformBuilderContext.AddResponseHeader(headerName: "HeaderName", value: "value", append: true, always: false);
+transformBuilderContext.AddResponseHeader(headerName: "HeaderName", value: "value", append: true, always: ResponseCondition.Success);
 ```
 Example:
 ```
@@ -749,7 +749,7 @@ HeaderName: value
 This sets or appends the value for the named response header. Set replaces any existing header. Append adds an additional header with the given value.
 Note: setting "" as a header value is not recommended and can cause an undefined behavior.
 
-`When` specifies if the response header should be included for successful responses or for all responses. Any response with a status code less than 400 is considered a success.
+`When` specifies if the response header should be included for all, successful, or failure responses. Any response with a status code less than 400 is considered a success.
 
 ### ResponseHeaderRemove
 
@@ -758,7 +758,7 @@ Note: setting "" as a header value is not recommended and can cause an undefined
 | Key | Value | Default | Required |
 |-----|-------|---------|----------|
 | ResponseHeaderRemove | The header name | (none) | yes |
-| When | Success/Always | Success | no |
+| When | Success/Always/Failure | Success | no |
 
 Config:
 ```JSON
@@ -769,10 +769,10 @@ Config:
 ```
 Code:
 ```csharp
-routeConfig = routeConfig.WithTransformResponseHeaderRemove(headerName: "HeaderName", always: false);
+routeConfig = routeConfig.WithTransformResponseHeaderRemove(headerName: "HeaderName", ResponseCondition.Success);
 ```
 ```C#
-transformBuilderContext.AddResponseHeaderRemove(headerName: "HeaderName", always: false);
+transformBuilderContext.AddResponseHeaderRemove(headerName: "HeaderName", ResponseCondition.Success);
 ```
 Example:
 ```
@@ -782,7 +782,7 @@ AnotherHeader: another-value
 
 This removes the named response header.
 
-`When` specifies if the response header should be included for successful responses or for all responses. Any response with a status code less than 400 is considered a success.
+`When` specifies if the response header should be removed for all, successful, or failure responses. Any response with a status code less than 400 is considered a success.
 
 ### ResponseHeadersAllowed
 
@@ -847,7 +847,7 @@ This sets if all proxy response trailers are copied to the client response. This
 |-----|-------|---------|----------|
 | ResponseTrailer | The header name | (none) | yes |
 | Set/Append | The header value | (none) | yes |
-| When | Success/Always | Success | no |
+| When | Success/Always/Failure | Success | no |
 
 Config:
 ```JSON
@@ -859,10 +859,10 @@ Config:
 ```
 Code:
 ```csharp
-routeConfig = routeConfig.WithTransformResponseTrailer(headerName: "HeaderName", value: "value", append: true, always: false);
+routeConfig = routeConfig.WithTransformResponseTrailer(headerName: "HeaderName", value: "value", append: true, ResponseCondition.Success);
 ```
 ```C#
-transformBuilderContext.AddResponseTrailer(headerName: "HeaderName", value: "value", append: true, always: false);
+transformBuilderContext.AddResponseTrailer(headerName: "HeaderName", value: "value", append: true, ResponseCondition.Success);
 ```
 Example:
 ```
@@ -880,7 +880,7 @@ ResponseTrailer follows the same structure and guidance as [ResponseHeader](tran
 | Key | Value | Default | Required |
 |-----|-------|---------|----------|
 | ResponseTrailerRemove | The header name | (none) | yes |
-| When | Success/Always | Success | no |
+| When | Success/Always/Failure | Success | no |
 
 Config:
 ```JSON
@@ -891,10 +891,10 @@ Config:
 ```
 Code:
 ```csharp
-routeConfig = routeConfig.WithTransformResponseTrailerRemove(headerName: "HeaderName", always: false);
+routeConfig = routeConfig.WithTransformResponseTrailerRemove(headerName: "HeaderName", ResponseCondition.Success);
 ```
 ```C#
-transformBuilderContext.AddResponseTrailerRemove(headerName: "HeaderName", always: false);
+transformBuilderContext.AddResponseTrailerRemove(headerName: "HeaderName", ResponseCondition.Success);
 ```
 Example:
 ```

src/ReverseProxy/Forwarder/HttpForwarder.cs

@@ -261,7 +261,7 @@ public async ValueTask<ForwarderError> SendAsync(
             // "http://a".Length = 8
             if (destinationPrefix == null || destinationPrefix.Length < 8)
             {
-                throw new ArgumentException(nameof(destinationPrefix));
+                throw new ArgumentException("Invalid destination prefix.", nameof(destinationPrefix));
             }
 
             var destinationRequest = new HttpRequestMessage();
@@ -481,8 +481,9 @@ private async ValueTask<ForwarderError> HandleRequestFailureAsync(HttpContext co
 
                 if (requestBodyCopyResult != StreamCopyResult.Success)
                 {
-                    await transformer.TransformResponseAsync(context, null);
-                    return HandleRequestBodyFailure(context, requestBodyCopyResult, requestBodyException!, requestException);
+                    var error = HandleRequestBodyFailure(context, requestBodyCopyResult, requestBodyException!, requestException);
+                    await transformer.TransformResponseAsync(context, proxyResponse: null);
+                    return error;
                 }
             }
 

src/ReverseProxy/Forwarder/HttpTransformer.cs

@@ -102,7 +102,7 @@ public virtual ValueTask TransformRequestAsync(HttpContext httpContext, HttpRequ
         /// `Transfer-Encoding: chunked`.
         /// </summary>
         /// <param name="httpContext">The incoming request.</param>
-        /// <param name="proxyResponse">The response from the destination.</param>
+        /// <param name="proxyResponse">The response from the destination. This can be null if the destination did not respond.</param>
         /// <returns>A bool indicating if the response should be proxied to the client or not. A derived implementation 
         /// that returns false may send an alternate response inline or return control to the caller for it to retry, respond, 
         /// etc.</returns>

src/ReverseProxy/Transforms/ResponseCondition.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Yarp.ReverseProxy.Transforms
+{
+    /// <summary>
+    /// Specifies the conditions under which a response transform will run.
+    /// </summary>
+    public enum ResponseCondition
+    {
+        /// <summary>
+        /// The transform runs for all conditions.
+        /// </summary>
+        Always,
+
+        /// <summary>
+        /// The transform only runs if there is a successful response with a status code less than 400.
+        /// </summary>
+        Success,
+
+        /// <summary>
+        /// The transform only runs if there is no response or a response with a 400+ status code.
+        /// </summary>
+        Failure
+    }
+}

src/ReverseProxy/Transforms/ResponseHeaderRemoveTransform.cs

@@ -11,20 +11,20 @@ namespace Yarp.ReverseProxy.Transforms
     /// </summary>
     public class ResponseHeaderRemoveTransform : ResponseTransform
     {
-        public ResponseHeaderRemoveTransform(string headerName, bool always)
+        public ResponseHeaderRemoveTransform(string headerName, ResponseCondition condition)
         {
             if (string.IsNullOrEmpty(headerName))
             {
                 throw new ArgumentException($"'{nameof(headerName)}' cannot be null or empty.", nameof(headerName));
             }
 
             HeaderName = headerName;
-            Always = always;
+            Condition = condition;
         }
 
         internal string HeaderName { get; }
 
-        internal bool Always { get; }
+        internal ResponseCondition Condition { get; }
 
         // Assumes the response status code has been set on the HttpContext already.
         /// <inheritdoc/>
@@ -35,7 +35,8 @@ public override ValueTask ApplyAsync(ResponseTransformContext context)
                 throw new ArgumentNullException(nameof(context));
             }
 
-            if (Always || Success(context))
+            if (Condition == ResponseCondition.Always
+                || Success(context) == (Condition == ResponseCondition.Success))
             {
                 context.HttpContext.Response.Headers.Remove(HeaderName);
             }

src/ReverseProxy/Transforms/ResponseHeaderValueTransform.cs

@@ -12,7 +12,7 @@ namespace Yarp.ReverseProxy.Transforms
     /// </summary>
     public class ResponseHeaderValueTransform : ResponseTransform
     {
-        public ResponseHeaderValueTransform(string headerName, string value, bool append, bool always)
+        public ResponseHeaderValueTransform(string headerName, string value, bool append, ResponseCondition condition)
         {
             if (string.IsNullOrEmpty(headerName))
             {
@@ -22,10 +22,10 @@ public ResponseHeaderValueTransform(string headerName, string value, bool append
             HeaderName = headerName;
             Value = value ?? throw new ArgumentNullException(nameof(value));
             Append = append;
-            Always = always;
+            Condition = condition;
         }
 
-        internal bool Always { get; }
+        internal ResponseCondition Condition { get; }
 
         internal bool Append { get; }
 
@@ -42,7 +42,8 @@ public override ValueTask ApplyAsync(ResponseTransformContext context)
                 throw new ArgumentNullException(nameof(context));
             }
 
-            if (Always || Success(context))
+            if (Condition == ResponseCondition.Always
+                || Success(context) == (Condition == ResponseCondition.Success))
             {
                 var existingHeader = TakeHeader(context, HeaderName);
                 if (Append)

src/ReverseProxy/Transforms/ResponseTrailerRemoveTransform.cs

@@ -13,20 +13,20 @@ namespace Yarp.ReverseProxy.Transforms
     /// </summary>
     public class ResponseTrailerRemoveTransform : ResponseTrailersTransform
     {
-        public ResponseTrailerRemoveTransform(string headerName, bool always)
+        public ResponseTrailerRemoveTransform(string headerName, ResponseCondition condition)
         {
             if (string.IsNullOrEmpty(headerName))
             {
                 throw new ArgumentException($"'{nameof(headerName)}' cannot be null or empty.", nameof(headerName));
             }
 
             HeaderName = headerName;
-            Always = always;
+            Condition = condition;
         }
 
         internal string HeaderName { get; }
 
-        internal bool Always { get; }
+        internal ResponseCondition Condition { get; }
 
         // Assumes the response status code has been set on the HttpContext already.
         /// <inheritdoc/>
@@ -39,7 +39,8 @@ public override ValueTask ApplyAsync(ResponseTrailersTransformContext context)
 
             Debug.Assert(context.ProxyResponse != null);
 
-            if (Always || Success(context))
+            if (Condition == ResponseCondition.Always
+                || Success(context) == (Condition == ResponseCondition.Success))
             {
                 var responseTrailersFeature = context.HttpContext.Features.Get<IHttpResponseTrailersFeature>();
                 var responseTrailers = responseTrailersFeature?.Trailers;

src/ReverseProxy/Transforms/ResponseTrailerValueTransform.cs

@@ -12,7 +12,7 @@ namespace Yarp.ReverseProxy.Transforms
     /// </summary>
     public class ResponseTrailerValueTransform : ResponseTrailersTransform
     {
-        public ResponseTrailerValueTransform(string headerName, string value, bool append, bool always)
+        public ResponseTrailerValueTransform(string headerName, string value, bool append, ResponseCondition condition)
         {
             if (string.IsNullOrEmpty(headerName))
             {
@@ -22,10 +22,10 @@ public ResponseTrailerValueTransform(string headerName, string value, bool appen
             HeaderName = headerName;
             Value = value ?? throw new ArgumentNullException(nameof(value));
             Append = append;
-            Always = always;
+            Condition = condition;
         }
 
-        internal bool Always { get; }
+        internal ResponseCondition Condition { get; }
 
         internal bool Append { get; }
 
@@ -42,7 +42,8 @@ public override ValueTask ApplyAsync(ResponseTrailersTransformContext context)
                 throw new ArgumentNullException(nameof(context));
             }
 
-            if (Always || Success(context))
+            if (Condition == ResponseCondition.Always
+                || Success(context) == (Condition == ResponseCondition.Success))
             {
                 var existingHeader = TakeHeader(context, HeaderName);
                 if (Append)

src/ReverseProxy/Transforms/ResponseTransformContext.cs

@@ -17,7 +17,7 @@ public class ResponseTransformContext
         public HttpContext HttpContext { get; init; } = default!;
 
         /// <summary>
-        /// The incoming proxy response.
+        /// The proxy response. This can be null if the destination did not respond.
         /// </summary>
         public HttpResponseMessage? ProxyResponse { get; init; }