matching: disable hcm integration by default

docs/root/configuration/http/http_filters/_include/composite.yaml

@@ -2,7 +2,6 @@ admin:
   access_log_path: /tmp/admin_access.log
   address:
     socket_address: { address: 0.0.0.0, port_value: 9901 }
-
 static_resources:
   listeners:
   - name: listener1
@@ -92,3 +91,11 @@ static_resources:
               socket_address:
                 address: 127.0.0.1
                 port_value: 50051
+
+layered_runtime:
+  layers:
+    - name: static-layer
+      static_layer:
+        envoy:
+          reloadable_features:
+            experimental_matching_api: true

docs/root/intro/arch_overview/advanced/matching/_include/complicated.yaml

@@ -91,3 +91,11 @@ static_resources:
                     socket_address:
                       address: 127.0.0.1
                       port_value: 8080
+
+layered_runtime:
+  layers:
+    - name: static-layer
+      static_layer:
+        envoy:
+          reloadable_features:
+            experimental_matching_api: true

docs/root/intro/arch_overview/advanced/matching/_include/request_response.yaml

@@ -77,3 +77,11 @@ static_resources:
                     socket_address:
                       address: 127.0.0.1
                       port_value: 8080
+
+layered_runtime:
+  layers:
+    - name: static-layer
+      static_layer:
+        envoy:
+          reloadable_features:
+            experimental_matching_api: true

docs/root/intro/arch_overview/advanced/matching/_include/simple.yaml

@@ -65,3 +65,11 @@ static_resources:
                     socket_address:
                       address: 127.0.0.1
                       port_value: 8080
+
+layered_runtime:
+  layers:
+    - name: static-layer
+      static_layer:
+        envoy:
+          reloadable_features:
+            experimental_matching_api: true

docs/root/version_history/current.rst

@@ -14,6 +14,9 @@ Minor Behavior Changes
 *Changes that may cause incompatibilities for some users, but should not for most*
 
 * access_log: add new access_log command operator ``%REQUEST_TX_DURATION%``.
+* http: disable the integration between :ref:`ExtensionWithMatcher <envoy_v3_api_msg_extensions.common.matching.v3.ExtensionWithMatcher>`
+  and HTTP filters by default to reflects its experimental status. This feature can be enabled by seting
+  ``envoy.reloadable_features.experimental_matching_api`` to true.
 * http: replaced setting ``envoy.reloadable_features.strict_1xx_and_204_response_headers`` with settings
   ``envoy.reloadable_features.require_strict_1xx_and_204_response_headers``
   (require upstream 1xx or 204 responses to not have Transfer-Encoding or non-zero Content-Length headers) and

source/common/http/match_wrapper/config.cc

@@ -87,6 +87,10 @@ Envoy::Http::FilterFactoryCb MatchWrapperConfig::createFilterFactoryFromProtoTyp
     const envoy::extensions::common::matching::v3::ExtensionWithMatcher& proto_config,
     const std::string& prefix, Server::Configuration::FactoryContext& context) {
 
+  if (!Runtime::runtimeFeatureEnabled("envoy.reloadable_features.experimental_matching_api")) {
+    throw EnvoyException("Experimental matching API is not enabled");
+  }
+
   ASSERT(proto_config.has_extension_config());
   auto& factory =
       Config::Utility::getAndCheckFactory<Server::Configuration::NamedHttpFilterConfigFactory>(

source/common/runtime/runtime_features.cc

@@ -112,6 +112,8 @@ constexpr const char* disabled_runtime_features[] = {
     "envoy.reloadable_features.remove_legacy_json",
     // Sentinel and test flag.
     "envoy.reloadable_features.test_feature_false",
+    // Allows the use of ExtensionWithMatcher to wrap a HTTP filter with a match tree.
+    "envoy.reloadable_features.experimental_matching_api",
 };
 
 RuntimeFeatures::RuntimeFeatures() {

test/common/http/match_wrapper/BUILD

@@ -15,5 +15,6 @@ envoy_cc_test(
         "//source/common/http/match_wrapper:config",
         "//test/mocks/server:factory_context_mocks",
         "//test/test_common:registry_lib",
+        "//test/test_common:test_runtime_lib",
     ],
 )

test/common/http/match_wrapper/config_test.cc

@@ -6,6 +6,7 @@
 
 #include "test/mocks/server/factory_context.h"
 #include "test/test_common/registry.h"
+#include "test/test_common/test_runtime.h"
 
 #include "gtest/gtest.h"
 
@@ -47,7 +48,42 @@ struct TestFactory : public Envoy::Server::Configuration::NamedHttpFilterConfigF
   }
 };
 
+TEST(MatchWrapper, DisabledByDefault) {
+  NiceMock<Envoy::Server::Configuration::MockFactoryContext> factory_context;
+
+  const auto config =
+      TestUtility::parseYaml<envoy::extensions::common::matching::v3::ExtensionWithMatcher>(R"EOF(
+extension_config:
+  name: test
+  typed_config:
+    "@type": type.googleapis.com/google.protobuf.StringValue
+matcher:
+  matcher_tree:
+    input:
+      name: request-headers
+      typed_config:
+        "@type": type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
+        header_name: default-matcher-header
+    exact_match_map:
+        map:
+            match:
+                action:
+                    name: skip
+                    typed_config:
+                        "@type": type.googleapis.com/envoy.extensions.filters.common.matcher.action.v3.SkipFilter
+)EOF");
+
+  MatchWrapperConfig match_wrapper_config;
+  EXPECT_THROW_WITH_MESSAGE(
+      match_wrapper_config.createFilterFactoryFromProto(config, "", factory_context),
+      EnvoyException, "Experimental matching API is not enabled");
+}
+
 TEST(MatchWrapper, WithMatcher) {
+  TestScopedRuntime scoped_runtime;
+  Runtime::LoaderSingleton::getExisting()->mergeValues(
+      {{"envoy.reloadable_features.experimental_matching_api", "true"}});
+
   TestFactory test_factory;
   Envoy::Registry::InjectFactory<Envoy::Server::Configuration::NamedHttpFilterConfigFactory>
       inject_factory(test_factory);
@@ -95,6 +131,10 @@ TEST(MatchWrapper, WithMatcher) {
 }
 
 TEST(MatchWrapper, WithMatcherInvalidDataInput) {
+  TestScopedRuntime scoped_runtime;
+  Runtime::LoaderSingleton::getExisting()->mergeValues(
+      {{"envoy.reloadable_features.experimental_matching_api", "true"}});
+
   TestFactory test_factory;
   Envoy::Registry::InjectFactory<Envoy::Server::Configuration::NamedHttpFilterConfigFactory>
       inject_factory(test_factory);

test/config_test/config_test.cc

@@ -85,6 +85,14 @@ class ConfigTest {
     ScopedRuntimeInjector scoped_runtime(server_.runtime());
     ON_CALL(server_.runtime_loader_.snapshot_, deprecatedFeatureEnabled(_, _))
         .WillByDefault(Invoke([](absl::string_view, bool default_value) { return default_value; }));
+
+    // TODO(snowp): There's no way to override runtime flags per example file (since we mock out the
+    // runtime loader), so temporarily enable this flag explicitly here until we flip the default.
+    // This should allow the existing configuration examples to continue working despite the feature
+    // being disabled by default.
+    ON_CALL(*snapshot_,
+            runtimeFeatureEnabled("envoy.reloadable_features.experimental_matching_api"))
+        .WillByDefault(Return(true));
     ON_CALL(server_.runtime_loader_, threadsafeSnapshot()).WillByDefault(Invoke([this]() {
       return snapshot_;
     }));
@@ -156,7 +164,8 @@ class ConfigTest {
   Server::ListenerManagerImpl listener_manager_{server_, component_factory_, worker_factory_,
                                                 false};
   Random::RandomGeneratorImpl random_;
-  Runtime::SnapshotConstSharedPtr snapshot_{std::make_shared<NiceMock<Runtime::MockSnapshot>>()};
+  std::shared_ptr<Runtime::MockSnapshot> snapshot_{
+      std::make_shared<NiceMock<Runtime::MockSnapshot>>()};
   NiceMock<Api::MockOsSysCalls> os_sys_calls_;
   TestThreadsafeSingletonInjector<Api::OsSysCallsImpl> os_calls{&os_sys_calls_};
   NiceMock<Filesystem::MockInstance> file_system_;

test/extensions/filters/http/composite/composite_filter_integration_test.cc

@@ -15,6 +15,8 @@ class CompositeFilterIntegrationTest : public testing::TestWithParam<Network::Ad
       : HttpIntegrationTest(Http::CodecClient::Type::HTTP1, GetParam()) {}
 
   void initialize() override {
+    config_helper_.addRuntimeOverride("envoy.reloadable_features.experimental_matching_api",
+                                      "true");
     config_helper_.addFilter(R"EOF(
   name: composite
   typed_config:

test/integration/extension_discovery_integration_test.cc

@@ -129,6 +129,9 @@ class ExtensionDiscoveryIntegrationTest : public Grpc::GrpcClientIntegrationPara
   void initialize() override {
     defer_listener_finalization_ = true;
     setUpstreamCount(1);
+    config_helper_.addRuntimeOverride("envoy.reloadable_features.experimental_matching_api",
+                                      "true");
+
     // Add an xDS cluster for extension config discovery.
     config_helper_.addConfigModifier([](envoy::config::bootstrap::v3::Bootstrap& bootstrap) {
       auto* ecds_cluster = bootstrap.mutable_static_resources()->add_clusters();

test/integration/integration_test.cc

@@ -368,6 +368,7 @@ TEST_P(IntegrationTest, EnvoyProxying100ContinueWithDecodeDataPause) {
 // Verifies that we can construct a match tree with a filter, and that we are able to skip
 // filter invocation through the match tree.
 TEST_P(IntegrationTest, MatchingHttpFilterConstruction) {
+  config_helper_.addRuntimeOverride("envoy.reloadable_features.experimental_matching_api", "true");
   config_helper_.addFilter(R"EOF(
 name: matcher
 typed_config: