docs: document HTTP generic matching (#14864)

Signed-off-by: Snow Pettersen <snowp@lyft.com>

Mirrored from https://github.com/envoyproxy/envoy @ b3fb91f6e72486047071ed08621a917dd3ebcb5a

envoy/extensions/filters/common/matcher/action/v3/skip_action.proto

@@ -11,6 +11,14 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Common Match Actions]
 
-// Indicates that the associated filter should be skipped.
+// Configuration for the SkipFilter match action. When matching results in this action, the
+// associated filter will be ignored for all filter callbacks (e.g. `encodeHeaders`, `encodeData`,
+// etc. for HTTP filters) after the matcher arrives at the match, including the callback that
+// caused the match result. For example, when used with a HTTP filter and the match result was
+// resolved after receiving the HTTP response headers, the HTTP filter will *not* receive the
+// response header callback.
+//
+// As a result, if this match action is resolved before the first filter callback (e.g. HTTP request
+// headers), the filter will be completely skipped.
 message SkipFilter {
 }

envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto

@@ -882,12 +882,21 @@ message HttpFilter {
   oneof config_type {
     // Filter specific configuration which depends on the filter being instantiated. See the supported
     // filters for further documentation.
+    //
+    // To support configuring a :ref:`match tree <arch_overview_matching_api>`, use an
+    // :ref:`ExtensionWithMatcher <envoy_api_msg_extensions.common.matching.v3.ExtensionWithMatcher>`
+    // with the desired HTTP filter.
     // [#extension-category: envoy.filters.http]
     google.protobuf.Any typed_config = 4;
 
     // Configuration source specifier for an extension configuration discovery service.
     // In case of a failure and without the default configuration, the HTTP listener responds with code 500.
     // Extension configs delivered through this mechanism are not expected to require warming (see https://github.com/envoyproxy/envoy/issues/12061).
+    //
+    // To support configuring a :ref:`match tree <arch_overview_matching_api>`, use an
+    // :ref:`ExtensionWithMatcher <envoy_api_msg_extensions.common.matching.v3.ExtensionWithMatcher>`
+    // with the desired HTTP filter. This works for both the default filter configuration as well
+    // as for filters provided via the API.
     config.core.v3.ExtensionConfigSource config_discovery = 5;
   }
 

envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto

@@ -891,12 +891,21 @@ message HttpFilter {
   oneof config_type {
     // Filter specific configuration which depends on the filter being instantiated. See the supported
     // filters for further documentation.
+    //
+    // To support configuring a :ref:`match tree <arch_overview_matching_api>`, use an
+    // :ref:`ExtensionWithMatcher <envoy_api_msg_extensions.common.matching.v4alpha.ExtensionWithMatcher>`
+    // with the desired HTTP filter.
     // [#extension-category: envoy.filters.http]
     google.protobuf.Any typed_config = 4;
 
     // Configuration source specifier for an extension configuration discovery service.
     // In case of a failure and without the default configuration, the HTTP listener responds with code 500.
     // Extension configs delivered through this mechanism are not expected to require warming (see https://github.com/envoyproxy/envoy/issues/12061).
+    //
+    // To support configuring a :ref:`match tree <arch_overview_matching_api>`, use an
+    // :ref:`ExtensionWithMatcher <envoy_api_msg_extensions.common.matching.v4alpha.ExtensionWithMatcher>`
+    // with the desired HTTP filter. This works for both the default filter configuration as well
+    // as for filters provided via the API.
     config.core.v4alpha.ExtensionConfigSource config_discovery = 5;
   }