feat(BackendTrafficPolicy): Support matching on response header for response override

api/v1alpha1/shared_types.go

@@ -819,11 +819,33 @@ type ResponseOverride struct {
 }
 
 // CustomResponseMatch defines the configuration for matching a user response to return a custom one.
+// When both statusCodes and responseHeaders are specified, both must match.
+// +kubebuilder:validation:XValidation:rule="has(self.statusCodes) || has(self.responseHeaders)",message="at least one of statusCodes or responseHeaders must be specified"
 type CustomResponseMatch struct {
 	// Status code to match on. The match evaluates to true if any of the matches are successful.
+	//
+	// +optional
 	// +kubebuilder:validation:MinItems=1
 	// +kubebuilder:validation:MaxItems=50
-	StatusCodes []StatusCodeMatch `json:"statusCodes"`
+	StatusCodes []StatusCodeMatch `json:"statusCodes,omitempty"`
+
+	// Response headers to match on. The match evaluates to true if all matches are successful.
+	//
+	// +optional
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=16
+	ResponseHeaders []ResponseOverrideHeaderMatch `json:"responseHeaders,omitempty"`
+}
+
+// ResponseOverrideHeaderMatch defines the configuration for matching a response header.
+type ResponseOverrideHeaderMatch struct {
+	// Name of the HTTP header.
+	// The header name is case-insensitive.
+	// For example, "Foo" and "foo" are considered the same header.
+	Name gwapiv1.HTTPHeaderName `json:"name"`
+
+	// Value within the HTTP header to match against.
+	Value StringMatch `json:"value"`
 }
 
 // StatusCodeValueType defines the types of values for the status code match supported by Envoy Gateway.

charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml

@@ -2382,6 +2382,52 @@ spec:
                     match:
                       description: Match configuration.
                       properties:
+                        responseHeaders:
+                          description: Response headers to match on. The match evaluates
+                            to true if all matches are successful.
+                          items:
+                            description: ResponseOverrideHeaderMatch defines the configuration
+                              for matching a response header.
+                            properties:
+                              name:
+                                description: |-
+                                  Name of the HTTP header.
+                                  The header name is case-insensitive.
+                                  For example, "Foo" and "foo" are considered the same header.
+                                maxLength: 256
+                                minLength: 1
+                                pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
+                                type: string
+                              value:
+                                description: Value within the HTTP header to match
+                                  against.
+                                properties:
+                                  type:
+                                    default: Exact
+                                    description: Type specifies how to match against
+                                      a string.
+                                    enum:
+                                    - Exact
+                                    - Prefix
+                                    - Suffix
+                                    - RegularExpression
+                                    type: string
+                                  value:
+                                    description: Value specifies the string value
+                                      that the match must have.
+                                    maxLength: 1024
+                                    minLength: 1
+                                    type: string
+                                required:
+                                - value
+                                type: object
+                            required:
+                            - name
+                            - value
+                            type: object
+                          maxItems: 16
+                          minItems: 1
+                          type: array
                         statusCodes:
                           description: Status code to match on. The match evaluates
                             to true if any of the matches are successful.
@@ -2437,9 +2483,11 @@ spec:
                           maxItems: 50
                           minItems: 1
                           type: array
-                      required:
-                      - statusCodes
                       type: object
+                      x-kubernetes-validations:
+                      - message: at least one of statusCodes or responseHeaders must
+                          be specified
+                        rule: has(self.statusCodes) || has(self.responseHeaders)
                     redirect:
                       description: Redirect configuration
                       properties:

charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml

@@ -2381,6 +2381,52 @@ spec:
                     match:
                       description: Match configuration.
                       properties:
+                        responseHeaders:
+                          description: Response headers to match on. The match evaluates
+                            to true if all matches are successful.
+                          items:
+                            description: ResponseOverrideHeaderMatch defines the configuration
+                              for matching a response header.
+                            properties:
+                              name:
+                                description: |-
+                                  Name of the HTTP header.
+                                  The header name is case-insensitive.
+                                  For example, "Foo" and "foo" are considered the same header.
+                                maxLength: 256
+                                minLength: 1
+                                pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
+                                type: string
+                              value:
+                                description: Value within the HTTP header to match
+                                  against.
+                                properties:
+                                  type:
+                                    default: Exact
+                                    description: Type specifies how to match against
+                                      a string.
+                                    enum:
+                                    - Exact
+                                    - Prefix
+                                    - Suffix
+                                    - RegularExpression
+                                    type: string
+                                  value:
+                                    description: Value specifies the string value
+                                      that the match must have.
+                                    maxLength: 1024
+                                    minLength: 1
+                                    type: string
+                                required:
+                                - value
+                                type: object
+                            required:
+                            - name
+                            - value
+                            type: object
+                          maxItems: 16
+                          minItems: 1
+                          type: array
                         statusCodes:
                           description: Status code to match on. The match evaluates
                             to true if any of the matches are successful.
@@ -2436,9 +2482,11 @@ spec:
                           maxItems: 50
                           minItems: 1
                           type: array
-                      required:
-                      - statusCodes
                       type: object
+                      x-kubernetes-validations:
+                      - message: at least one of statusCodes or responseHeaders must
+                          be specified
+                        rule: has(self.statusCodes) || has(self.responseHeaders)
                     redirect:
                       description: Redirect configuration
                       properties:

internal/gatewayapi/backendtrafficpolicy.go

@@ -2382,6 +2382,10 @@ func (t *Translator) buildResponseOverride(policy *egv1a1.BackendTrafficPolicy,
 			}
 		}
 
+		for _, h := range ro.Match.ResponseHeaders {
+			match.ResponseHeaders = append(match.ResponseHeaders, *irStringMatch(string(h.Name), h.Value))
+		}
+
 		if ro.Redirect != nil {
 			redirect := &ir.Redirect{
 				Scheme: ro.Redirect.Scheme,

internal/gatewayapi/testdata/backendtrafficpolicy-with-response-override.in.yaml

@@ -204,6 +204,32 @@ backendTrafficPolicies:
               - value: 403
           response:
             statusCode: 401
+        - match:
+            responseHeaders:
+              - name: X-Custom-Header
+                value:
+                  type: Exact
+                  value: custom-value
+          response:
+            contentType: text/plain
+            body:
+              inline: "matched response header"
+        - match:
+            statusCodes:
+              - value: 503
+            responseHeaders:
+              - name: X-Error-Type
+                value:
+                  type: Prefix
+                  value: "upstream-"
+              - name: X-Region
+                value:
+                  type: RegularExpression
+                  value: "^us-.*$"
+          response:
+            contentType: application/json
+            body:
+              inline: '{"error":"combined match"}'
   - apiVersion: gateway.envoyproxy.io/v1alpha1
     kind: BackendTrafficPolicy
     metadata:

internal/gatewayapi/testdata/backendtrafficpolicy-with-response-override.out.yaml

@@ -68,6 +68,35 @@ backendTrafficPolicies:
           value: 403
       response:
         statusCode: 401
+    - match:
+        responseHeaders:
+        - name: X-Custom-Header
+          value:
+            type: Exact
+            value: custom-value
+      response:
+        body:
+          inline: matched response header
+          type: null
+        contentType: text/plain
+    - match:
+        responseHeaders:
+        - name: X-Error-Type
+          value:
+            type: Prefix
+            value: upstream-
+        - name: X-Region
+          value:
+            type: RegularExpression
+            value: ^us-.*$
+        statusCodes:
+        - type: null
+          value: 503
+      response:
+        body:
+          inline: '{"error":"combined match"}'
+          type: null
+        contentType: application/json
     targetRef:
       group: gateway.networking.k8s.io
       kind: HTTPRoute
@@ -710,6 +739,29 @@ xdsIR:
               name: backendtrafficpolicy/default/policy-for-route-2/responseoverride/rule/0
               response:
                 statusCode: 401
+            - match:
+                responseHeaders:
+                - distinct: false
+                  exact: custom-value
+                  name: X-Custom-Header
+              name: backendtrafficpolicy/default/policy-for-route-2/responseoverride/rule/1
+              response:
+                body: bWF0Y2hlZCByZXNwb25zZSBoZWFkZXI=
+                contentType: text/plain
+            - match:
+                responseHeaders:
+                - distinct: false
+                  name: X-Error-Type
+                  prefix: upstream-
+                - distinct: false
+                  name: X-Region
+                  safeRegex: ^us-.*$
+                statusCodes:
+                - value: 503
+              name: backendtrafficpolicy/default/policy-for-route-2/responseoverride/rule/2
+              response:
+                body: eyJlcnJvciI6ImNvbWJpbmVkIG1hdGNoIn0=
+                contentType: application/json
       - destination:
           metadata:
             kind: HTTPRoute

internal/ir/xds.go

@@ -827,10 +827,14 @@ type ResponseOverrideRule struct {
 }
 
 // CustomResponseMatch defines the configuration for matching a user response to return a custom one.
+// When both statusCodes and responseHeaders are specified, both must match.
 // +k8s:deepcopy-gen=true
 type CustomResponseMatch struct {
 	// Status code to match on. The match evaluates to true if any of the matches are successful.
-	StatusCodes []StatusCodeMatch `json:"statusCodes"`
+	StatusCodes []StatusCodeMatch `json:"statusCodes,omitempty"`
+
+	// Response headers to match on. The match evaluates to true if all matches are successful.
+	ResponseHeaders []StringMatch `json:"responseHeaders,omitempty"`
 }
 
 // StatusCodeMatch defines the configuration for matching a status code.