Custom Response Filter (proto)

This extension has the qualified name envoy.filters.http.custom_response

Note

This extension is work-in-progress. Functionality is incomplete and it is not intended for production use.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

• envoy.filters.http

This extension must be configured with one of the following type URLs:

• type.googleapis.com/envoy.extensions.filters.http.custom_response.v3.CustomResponse

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

The Custom Response Filter allows for replacing upstream responses.

extensions.filters.http.custom_response.v3.CustomResponse

[extensions.filters.http.custom_response.v3.CustomResponse proto]

The filter configuration is a collection of custom response policies in a matcher tree. The configuration can be defined at the filter, virtual host or route level. The response will be matched against the most specific to the least specific config, till a match is found.

{
  "custom_response_matcher": {...}
}

custom_response_matcher

(.xds.type.matcher.v3.Matcher) Matcher to match against the original response to select a Custom Response Policy that will override the original response. The matching is done by matching against the response status code, response header values, and/or request header values. Request inputs (for example HttpRequestHeaderMatchInput) match against the original downstream request, which allows selecting a custom response based on, e.g., the Accept request header. Example:

matcher_list:
  matchers:
    # Apply a locally stored custom response to any 4xx response.
  - predicate:
      single_predicate:
        input:
          name: 4xx_response
          typed_config:
            "@type": type.googleapis.com/envoy.type.matcher.v3.HttpResponseStatusCodeClassMatchInput
        value_match:
          exact: "4xx"
    on_match:
      action:
        name: action
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.http.custom_response.local_response_policy.v3.LocalResponsePolicy
          status_code: 499
          body:
            inline_string: "not allowed"
          body_format:
            json_format:
              status: "%RESPONSE_CODE%"
              message: "%LOCAL_REPLY_BODY%"
          response_headers_to_add:
          - header:
              key: "foo"
              value: "x-bar"
    # Redirect to different upstream if the status code is one of 502, 503 or 504.
  - predicate:
      or_matcher:
        predicate:
        - single_predicate:
            input:
              name: "502_response"
              typed_config:
                "@type": type.googleapis.com/envoy.type.matcher.v3.HttpResponseStatusCodeMatchInput
            value_match:
              exact: "502"
        - single_predicate:
            input:
              name: "503_response"
              typed_config:
                "@type": type.googleapis.com/envoy.type.matcher.v3.HttpResponseStatusCodeMatchInput
            value_match:
              exact: "503"
        - single_predicate:
            input:
              name: "504_response"
              typed_config:
                "@type": type.googleapis.com/envoy.type.matcher.v3.HttpResponseStatusCodeMatchInput
            value_match:
              exact: "504"
    on_match:
      action:
        name: action
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.http.custom_response.redirect_policy.v3.RedirectPolicy
          status_code: 299
          uri: "https://foo.example/gateway_error"
          response_headers_to_add:
          - header:
              key: "foo2"
              value: "x-bar2"
    # Apply a JSON custom response to 5xx responses when the request asks for JSON.
  - predicate:
      and_matcher:
        predicate:
        - single_predicate:
            input:
              name: 5xx_response
              typed_config:
                "@type": type.googleapis.com/envoy.type.matcher.v3.HttpResponseStatusCodeClassMatchInput
            value_match:
              exact: "5xx"
        - single_predicate:
            input:
              name: accept_request_header
              typed_config:
                "@type": type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
                header_name: accept
            value_match:
              exact: "application/json"
    on_match:
      action:
        name: action
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.http.custom_response.local_response_policy.v3.LocalResponsePolicy
          status_code: 500
          body_format:
            json_format:
              status: "%RESPONSE_CODE%"
              message: "%LOCAL_REPLY_BODY%"

– attention::

The first matched policy wins. Once the response is matched, matcher evaluations end.

Refer to Unified Matcher API documentation for more information on the matcher trees.

Tip

This extension category has the following known extensions:

• envoy.http.custom_response.local_response_policy

• envoy.http.custom_response.redirect_policy