http: added a new dual header mutation filter that could be used as d…

…ownstream/upstream filter (#25658)

Check #24100 for more detailed context.

Risk Level: low. new L7 extension.
Testing: unit.
Docs Changes: added.
Release Notes: added.

Signed-off-by: wbpcode <[email protected]>

CODEOWNERS

@@ -295,6 +295,8 @@ extensions/filters/http/oauth2 @derekargueta @snowp
 /*/extensions/load_balancing_policies/maglev @wbpcode @UNOWNED
 # Early header mutation
 /*/extensions/http/early_header_mutation/header_mutation @wbpcode @UNOWNED
+# Header mutation
+/*/extensions/filters/http/header_mutation @wbpcode @htuch @soulxu
 
 # Intentionally exempt (treated as core code)
 /*/extensions/filters/common @UNOWNED @UNOWNED

api/BUILD

@@ -180,6 +180,7 @@ proto_library(
         "//envoy/extensions/filters/http/grpc_stats/v3:pkg",
         "//envoy/extensions/filters/http/grpc_web/v3:pkg",
         "//envoy/extensions/filters/http/gzip/v3:pkg",
+        "//envoy/extensions/filters/http/header_mutation/v3:pkg",
         "//envoy/extensions/filters/http/header_to_metadata/v3:pkg",
         "//envoy/extensions/filters/http/health_check/v3:pkg",
         "//envoy/extensions/filters/http/ip_tagging/v3:pkg",

api/envoy/extensions/filters/http/header_mutation/v3/BUILD

@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/config/common/mutation_rules/v3:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

api/envoy/extensions/filters/http/header_mutation/v3/header_mutation.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.header_mutation.v3;
+
+import "envoy/config/common/mutation_rules/v3/mutation_rules.proto";
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.header_mutation.v3";
+option java_outer_classname = "HeaderMutationProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/header_mutation/v3;header_mutationv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Header mutation filter configuration]
+// [#extension: envoy.filters.http.header_mutation]
+
+message Mutations {
+  // The request mutations are applied before the request is forwarded to the upstream cluster.
+  repeated config.common.mutation_rules.v3.HeaderMutation request_mutations = 1;
+
+  // The response mutations are applied before the response is sent to the downstream client.
+  repeated config.common.mutation_rules.v3.HeaderMutation response_mutations = 2;
+}
+
+// Per route configuration for the header mutation filter. If this is configured at multiple levels
+// (route level, virtual host level, and route table level), only the most specific one will be used.
+message HeaderMutationPerRoute {
+  Mutations mutations = 1;
+}
+
+// Configuration for the header mutation filter. The mutation rules in the filter configuration will
+// always be applied first and then the per-route mutation rules, if both are specified.
+message HeaderMutation {
+  Mutations mutations = 1;
+}

api/versioning/BUILD

@@ -118,6 +118,7 @@ proto_library(
         "//envoy/extensions/filters/http/grpc_stats/v3:pkg",
         "//envoy/extensions/filters/http/grpc_web/v3:pkg",
         "//envoy/extensions/filters/http/gzip/v3:pkg",
+        "//envoy/extensions/filters/http/header_mutation/v3:pkg",
         "//envoy/extensions/filters/http/header_to_metadata/v3:pkg",
         "//envoy/extensions/filters/http/health_check/v3:pkg",
         "//envoy/extensions/filters/http/ip_tagging/v3:pkg",

changelogs/current.yaml

@@ -157,6 +157,9 @@ new_features:
   change: |
     added :ref:`failed_status_in_metadata <envoy_v3_api_field_extensions.filters.http.jwt_authn.v3.JwtProvider.failed_status_in_metadata>` to support setting the JWT
     authentication failure status code and message in dynamic metadata.
+- area: http filter
+  change: |
+    added :ref:`header mutation http filter <config_http_filters_header_mutation>` which adds the ability to modify request and response headers in any position of HTTP filter chain.
 - area: matching
   change: |
     added :ref:`Filter State Input <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.FilterStateInput>` for matching based on filter state objects.

docs/root/configuration/http/http_filters/header_mutation_filter.rst

@@ -0,0 +1,25 @@
+.. _config_http_filters_header_mutation:
+
+Header Mutation
+===============
+
+* This filter should be configured with the type URL ``type.googleapis.com/envoy.extensions.filters.http.header_mutation.v3.HeaderMutation``.
+* :ref:`v3 API reference <envoy_v3_api_msg_extensions.filters.http.header_mutation.v3.HeaderMutation>`
+
+This is a filter that can be used to add, remove, append, or update HTTP headers. It can be added in any position in the filter chain
+and used as downstream or upstream HTTP filter. The filter can be configured to apply the header mutations to the request, response, or both.
+
+
+In most cases, this filter would be a more flexible alternative to the ``request_headers_to_add``, ``request_headers_to_remove``,
+``response_headers_to_add``, and ``response_headers_to_remove`` fields in the :ref:`route configuration <envoy_v3_api_msg_config.route.v3.RouteConfiguration>`.
+
+
+The filter provides complete control over the position and order of the header mutations. It may be used to influence later route picks if
+the route cache is cleared by a filter executing after the header mutation filter.
+
+
+In addition, this filter can be used as upstream filter and mutate the request headers after load balancing and host selection.
+
+
+Please note that as an encoder filter, this filter follows the standard rules of when it will execute in situations such as local replies - response
+headers will not be unconditionally added in cases where the filter would be bypassed.

docs/root/configuration/http/http_filters/http_filters.rst

@@ -34,6 +34,7 @@ HTTP filters
   grpc_json_transcoder_filter
   grpc_stats_filter
   grpc_web_filter
+  header_mutation_filter
   health_check_filter
   header_to_metadata_filter
   ip_tagging_filter

source/common/http/BUILD

@@ -576,3 +576,16 @@ envoy_cc_library(
         "//source/common/common:assert_lib",
     ],
 )
+
+envoy_cc_library(
+    name = "header_mutation_lib",
+    srcs = ["header_mutation.cc"],
+    hdrs = ["header_mutation.h"],
+    deps = [
+        ":header_map_lib",
+        ":utility_lib",
+        "//envoy/http:header_evaluator",
+        "//source/common/router:header_parser_lib",
+        "@envoy_api//envoy/config/common/mutation_rules/v3:pkg_cc_proto",
+    ],
+)

source/common/http/header_mutation.cc

@@ -0,0 +1,91 @@
+#include "source/common/http/header_mutation.h"
+
+#include "source/common/router/header_parser.h"
+
+namespace Envoy {
+namespace Http {
+
+namespace {
+
+using HeaderAppendAction = envoy::config::core::v3::HeaderValueOption::HeaderAppendAction;
+using HeaderValueOption = envoy::config::core::v3::HeaderValueOption;
+
+// TODO(wbpcode): Inherit from Envoy::Router::HeadersToAddEntry to make sure the formatter
+// has the same behavior as the router's formatter. We should try to find a more clean way
+// to reuse the formatter after the router's formatter is completely removed.
+class AppendMutation : public HeaderEvaluator, public Envoy::Router::HeadersToAddEntry {
+public:
+  AppendMutation(const HeaderValueOption& header_value_option)
+      : HeadersToAddEntry(header_value_option), header_name_(header_value_option.header().key()) {}
+
+  void evaluateHeaders(Http::HeaderMap& headers, const Http::RequestHeaderMap& request_headers,
+                       const Http::ResponseHeaderMap& response_headers,
+                       const StreamInfo::StreamInfo& stream_info) const override {
+    std::string value = formatter_->format(request_headers, response_headers, stream_info);
+
+    if (!value.empty() || add_if_empty_) {
+      switch (append_action_) {
+        PANIC_ON_PROTO_ENUM_SENTINEL_VALUES;
+      case HeaderValueOption::APPEND_IF_EXISTS_OR_ADD:
+        headers.addReferenceKey(header_name_, value);
+        return;
+      case HeaderValueOption::ADD_IF_ABSENT: {
+        auto header = headers.get(header_name_);
+        if (!header.empty()) {
+          return;
+        }
+        headers.addReferenceKey(header_name_, value);
+        break;
+      }
+      case HeaderValueOption::OVERWRITE_IF_EXISTS_OR_ADD:
+        headers.setReferenceKey(header_name_, value);
+        break;
+      }
+    }
+  }
+
+private:
+  Envoy::Http::LowerCaseString header_name_;
+};
+
+class RemoveMutation : public HeaderEvaluator {
+public:
+  RemoveMutation(const std::string& header_name) : header_name_(header_name) {}
+
+  void evaluateHeaders(Http::HeaderMap& headers, const Http::RequestHeaderMap&,
+                       const Http::ResponseHeaderMap&,
+                       const StreamInfo::StreamInfo&) const override {
+    headers.remove(header_name_);
+  }
+
+private:
+  const Envoy::Http::LowerCaseString header_name_;
+};
+} // namespace
+
+HeaderMutations::HeaderMutations(const ProtoHeaderMutatons& header_mutations) {
+  for (const auto& mutation : header_mutations) {
+    switch (mutation.action_case()) {
+    case envoy::config::common::mutation_rules::v3::HeaderMutation::ActionCase::kAppend:
+      header_mutations_.emplace_back(std::make_unique<AppendMutation>(mutation.append()));
+      break;
+    case envoy::config::common::mutation_rules::v3::HeaderMutation::ActionCase::kRemove:
+      header_mutations_.emplace_back(std::make_unique<RemoveMutation>(mutation.remove()));
+      break;
+    default:
+      PANIC_DUE_TO_PROTO_UNSET;
+    }
+  }
+}
+
+void HeaderMutations::evaluateHeaders(Http::HeaderMap& headers,
+                                      const Http::RequestHeaderMap& request_headers,
+                                      const Http::ResponseHeaderMap& response_headers,
+                                      const StreamInfo::StreamInfo& stream_info) const {
+  for (const auto& mutation : header_mutations_) {
+    mutation->evaluateHeaders(headers, request_headers, response_headers, stream_info);
+  }
+}
+
+} // namespace Http
+} // namespace Envoy

source/common/http/header_mutation.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include "envoy/config/common/mutation_rules/v3/mutation_rules.pb.h"
+#include "envoy/http/header_evaluator.h"
+
+#include "source/common/protobuf/protobuf.h"
+
+namespace Envoy {
+namespace Http {
+
+using ProtoHeaderMutatons =
+    Protobuf::RepeatedPtrField<envoy::config::common::mutation_rules::v3::HeaderMutation>;
+using ProtoHeaderValueOption = envoy::config::core::v3::HeaderValueOption;
+
+class HeaderMutations : public HeaderEvaluator {
+public:
+  HeaderMutations(const ProtoHeaderMutatons& header_mutations);
+
+  // Http::HeaderEvaluator
+  void evaluateHeaders(Http::HeaderMap& headers, const Http::RequestHeaderMap& request_headers,
+                       const Http::ResponseHeaderMap& response_headers,
+                       const StreamInfo::StreamInfo& stream_info) const override;
+
+private:
+  std::vector<std::unique_ptr<HeaderEvaluator>> header_mutations_;
+};
+
+} // namespace Http
+} // namespace Envoy

source/extensions/extensions_build_config.bzl

@@ -132,6 +132,7 @@ EXTENSIONS = {
     "envoy.filters.http.tap":                           "//source/extensions/filters/http/tap:config",
     "envoy.filters.http.wasm":                          "//source/extensions/filters/http/wasm:config",
     "envoy.filters.http.stateful_session":              "//source/extensions/filters/http/stateful_session:config",
+    "envoy.filters.http.header_mutation":               "//source/extensions/filters/http/header_mutation:config",
 
     #
     # Listener filters

source/extensions/extensions_metadata.yaml

@@ -504,6 +504,15 @@ envoy.filters.http.stateful_session:
   type_urls:
   - envoy.extensions.filters.http.stateful_session.v3.StatefulSession
   - envoy.extensions.filters.http.stateful_session.v3.StatefulSessionPerRoute
+envoy.filters.http.header_mutation:
+  categories:
+  - envoy.filters.http
+  - envoy.filters.http.upstream
+  security_posture: unknown
+  status: alpha
+  type_urls:
+  - envoy.extensions.filters.http.header_mutation.v3.HeaderMutation
+  - envoy.extensions.filters.http.header_mutation.v3.HeaderMutationPerRoute
 envoy.filters.listener.http_inspector:
   categories:
   - envoy.filters.listener

source/extensions/filters/http/header_mutation/BUILD

@@ -0,0 +1,38 @@
+load(
+    "//bazel:envoy_build_system.bzl",
+    "envoy_cc_extension",
+    "envoy_cc_library",
+    "envoy_extension_package",
+)
+
+licenses(["notice"])  # Apache 2
+
+envoy_extension_package()
+
+envoy_cc_library(
+    name = "header_mutation_lib",
+    srcs = ["header_mutation.cc"],
+    hdrs = ["header_mutation.h"],
+    deps = [
+        "//envoy/server:filter_config_interface",
+        "//source/common/config:utility_lib",
+        "//source/common/http:header_map_lib",
+        "//source/common/http:header_mutation_lib",
+        "//source/common/protobuf:utility_lib",
+        "//source/extensions/filters/http/common:pass_through_filter_lib",
+        "@envoy_api//envoy/extensions/filters/http/header_mutation/v3:pkg_cc_proto",
+    ],
+)
+
+envoy_cc_extension(
+    name = "config",
+    srcs = ["config.cc"],
+    hdrs = ["config.h"],
+    deps = [
+        ":header_mutation_lib",
+        "//envoy/registry",
+        "//source/common/protobuf:utility_lib",
+        "//source/extensions/filters/http/common:factory_base_lib",
+        "@envoy_api//envoy/extensions/filters/http/header_mutation/v3:pkg_cc_proto",
+    ],
+)

source/extensions/filters/http/header_mutation/config.cc

@@ -0,0 +1,37 @@
+#include "source/extensions/filters/http/header_mutation/config.h"
+
+#include <memory>
+
+#include "envoy/registry/registry.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace HttpFilters {
+namespace HeaderMutation {
+
+Http::FilterFactoryCb HeaderMutationFactoryConfig::createFilterFactoryFromProtoTyped(
+    const ProtoConfig& config, const std::string&, DualInfo,
+    Server::Configuration::ServerFactoryContext&) {
+  auto filter_config = std::make_shared<HeaderMutationConfig>(config);
+  return [filter_config](Http::FilterChainFactoryCallbacks& callbacks) -> void {
+    callbacks.addStreamFilter(std::make_shared<HeaderMutation>(filter_config));
+  };
+}
+
+Router::RouteSpecificFilterConfigConstSharedPtr
+HeaderMutationFactoryConfig::createRouteSpecificFilterConfigTyped(
+    const PerRouteProtoConfig& proto_config, Server::Configuration::ServerFactoryContext&,
+    ProtobufMessage::ValidationVisitor&) {
+  return std::make_shared<PerRouteHeaderMutation>(proto_config);
+}
+
+using UpstreamHeaderMutationFactoryConfig = HeaderMutationFactoryConfig;
+
+REGISTER_FACTORY(HeaderMutationFactoryConfig, Server::Configuration::NamedHttpFilterConfigFactory);
+REGISTER_FACTORY(UpstreamHeaderMutationFactoryConfig,
+                 Server::Configuration::UpstreamHttpFilterConfigFactory);
+
+} // namespace HeaderMutation
+} // namespace HttpFilters
+} // namespace Extensions
+} // namespace Envoy

source/extensions/filters/http/header_mutation/config.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include "envoy/extensions/filters/http/header_mutation/v3/header_mutation.pb.h"
+#include "envoy/extensions/filters/http/header_mutation/v3/header_mutation.pb.validate.h"
+
+#include "source/extensions/filters/http/common/factory_base.h"
+#include "source/extensions/filters/http/header_mutation/header_mutation.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace HttpFilters {
+namespace HeaderMutation {
+
+/**
+ * Config registration for the stateful session filter. @see NamedHttpFilterConfigFactory.
+ */
+class HeaderMutationFactoryConfig
+    : public Common::DualFactoryBase<ProtoConfig, PerRouteProtoConfig> {
+public:
+  HeaderMutationFactoryConfig() : DualFactoryBase("envoy.filters.http.header_mutation") {}
+
+private:
+  Http::FilterFactoryCb
+  createFilterFactoryFromProtoTyped(const ProtoConfig& proto_config,
+                                    const std::string& stats_prefix, DualInfo info,
+                                    Server::Configuration::ServerFactoryContext& context) override;
+  Router::RouteSpecificFilterConfigConstSharedPtr
+  createRouteSpecificFilterConfigTyped(const PerRouteProtoConfig& proto_config,
+                                       Server::Configuration::ServerFactoryContext&,
+                                       ProtobufMessage::ValidationVisitor&) override;
+};
+
+} // namespace HeaderMutation
+} // namespace HttpFilters
+} // namespace Extensions
+} // namespace Envoy