docs: add cncf/xds protos

api/BUILD

@@ -285,12 +285,23 @@ proto_library(
     ],
 )
 
+proto_library(
+    name = "xds_protos",
+    visibility = ["//visibility:public"],
+    deps = [
+        "@com_github_cncf_udpa//xds/core/v3:pkg",
+        "@com_github_cncf_udpa//xds/type/matcher/v3:pkg",
+        "@com_github_cncf_udpa//xds/type/v3:pkg",
+    ],
+)
+
 proto_library(
     name = "all_protos",
     visibility = ["//visibility:public"],
     deps = [
         ":v2_protos",
         ":v3_protos",
+        ":xds_protos",
     ],
 )
 

api/bazel/repository_locations.bzl

@@ -33,9 +33,9 @@ REPOSITORY_LOCATIONS_SPEC = dict(
         project_desc = "xDS API Working Group (xDS-WG)",
         project_url = "https://github.com/cncf/xds",
         # During the UDPA -> xDS migration, we aren't working with releases.
-        version = "0fa49ea1db0ccf084453766a755b2e76434d99fc",
-        sha256 = "9369c65e20201ea43e2c293cf024f58167dd727d864706481972ccdf3aacdaab",
-        release_date = "2022-01-12",
+        version = "7f1daf1720fc185f3b63f70d25aefaeef83d88d7",
+        sha256 = "62c0daaff43fd9a62c280bf2b0c2b670372b24377ea5e9ea4302cf748dd53cba",
+        release_date = "2022-03-14",
         strip_prefix = "xds-{version}",
         urls = ["https://github.com/cncf/xds/archive/{version}.tar.gz"],
         use_category = ["api"],

api/envoy/extensions/matching/common_inputs/network/v3/network_inputs.proto

@@ -13,39 +13,46 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // [#protodoc-title: Common Network Matching Inputs]
 
 // Specifies that matching should be performed by the destination IP address.
+// [#extension: envoy.matching.inputs.destination_ip]
 message DestinationIPInput {
 }
 
 // Specifies that matching should be performed by the destination port.
+// [#extension: envoy.matching.inputs.destination_port]
 message DestinationPortInput {
 }
 
 // Specifies that matching should be performed by the source IP address.
+// [#extension: envoy.matching.inputs.source_ip]
 message SourceIPInput {
 }
 
 // Specifies that matching should be performed by the source port.
+// [#extension: envoy.matching.inputs.source_port]
 message SourcePortInput {
 }
 
 // Input that matches by the directly connected source IP address (this
 // will only be different from the source IP address when using a listener
 // filter that overrides the source address, such as the :ref:`Proxy Protocol
 // listener filter <config_listener_filters_proxy_protocol>`).
+// [#extension: envoy.matching.inputs.direct_source_ip]
 message DirectSourceIPInput {
 }
 
 // Input that matches by the source IP type.
 // Specifies the source IP match type. The values include:
 //
 // * ``local`` - matches a connection originating from the same host,
+// [#extension: envoy.matching.inputs.source_type]
 message SourceTypeInput {
 }
 
 // Input that matches by the requested server name (e.g. SNI in TLS).
 //
 // :ref:`TLS Inspector <config_listener_filters_tls_inspector>` provides the requested server name based on SNI,
 // when TLS protocol is detected.
+// [#extension: envoy.matching.inputs.server_name]
 message ServerNameInput {
 }
 
@@ -56,6 +63,7 @@ message ServerNameInput {
 // * ``raw_buffer`` - default, used when no transport protocol is detected,
 // * ``tls`` - set by :ref:`envoy.filters.listener.tls_inspector <config_listener_filters_tls_inspector>`
 //   when TLS protocol is detected.
+// [#extension: envoy.matching.inputs.transport_protocol]
 message TransportProtocolInput {
 }
 
@@ -84,5 +92,6 @@ message TransportProtocolInput {
 //   However, the use of ALPN is pretty much limited to the HTTP/2 traffic on the Internet,
 //   and matching on values other than ``h2`` is going to lead to a lot of false negatives,
 //   unless all connecting clients are known to use ALPN.
+// [#extension: envoy.matching.inputs.application_protocol]
 message ApplicationProtocolInput {
 }

api/envoy/type/matcher/v3/http_inputs.proto

@@ -18,6 +18,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // e.g. if the request contains two 'foo' headers with value 'bar' and 'baz', the input
 // string will be 'bar,baz'.
 // [#comment:TODO(snowp): Link to unified matching docs.]
+// [#extension: envoy.matching.inputs.request_headers]
 message HttpRequestHeaderMatchInput {
   // The request header to match on.
   string header_name = 1
@@ -29,6 +30,7 @@ message HttpRequestHeaderMatchInput {
 // e.g. if the request contains two 'foo' headers with value 'bar' and 'baz', the input
 // string will be 'bar,baz'.
 // [#comment:TODO(snowp): Link to unified matching docs.]
+// [#extension: envoy.matching.inputs.request_trailers]
 message HttpRequestTrailerMatchInput {
   // The request trailer to match on.
   string header_name = 1
@@ -40,6 +42,7 @@ message HttpRequestTrailerMatchInput {
 // e.g. if the response contains two 'foo' headers with value 'bar' and 'baz', the input
 // string will be 'bar,baz'.
 // [#comment:TODO(snowp): Link to unified matching docs.]
+// [#extension: envoy.matching.inputs.response_headers]
 message HttpResponseHeaderMatchInput {
   // The response header to match on.
   string header_name = 1
@@ -51,6 +54,7 @@ message HttpResponseHeaderMatchInput {
 // e.g. if the request contains two 'foo' headers with value 'bar' and 'baz', the input
 // string will be 'bar,baz'.
 // [#comment:TODO(snowp): Link to unified matching docs.]
+// [#extension: envoy.matching.inputs.response_trailers]
 message HttpResponseTrailerMatchInput {
   // The response trailer to match on.
   string header_name = 1

docs/BUILD

@@ -104,6 +104,12 @@ genquery(
     scope = ["@envoy_api//:v3_protos"],
 )
 
+genquery(
+    name = "xds_proto_srcs",
+    expression = "labels(srcs, labels(deps, @envoy_api//:xds_protos))",
+    scope = ["@envoy_api//:xds_protos"],
+)
+
 genrule(
     name = "empty_protos_rst",
     srcs = [":empty_extensions.json"],
@@ -129,6 +135,20 @@ genrule(
     tools = ["//tools/docs:generate_api_rst"],
 )
 
+genrule(
+    name = "xds_rst",
+    srcs = [
+        "//tools/protodoc:xds_protodoc",
+        ":xds_proto_srcs",
+    ],
+    outs = ["xds_rst.tar"],
+    cmd = """
+    $(location //tools/docs:generate_api_rst) \\
+        $(location xds_proto_srcs) $(locations //tools/protodoc:xds_protodoc) $@
+    """,
+    tools = ["//tools/docs:generate_api_rst"],
+)
+
 pkg_files(
     name = "sphinx_base",
     srcs = glob(
@@ -179,6 +199,7 @@ pkg_tar(
         ":empty_protos_rst",
         ":extensions_security_rst",
         ":external_deps_rst",
+        ":xds_rst",
     ],
 )
 

docs/root/api-v3/common_messages/common_messages.rst

@@ -33,3 +33,18 @@ Common messages
   ../extensions/matching/input_matchers/ip/v3/ip.proto
   ../extensions/matching/common_inputs/environment_variable/v3/input.proto
   ../extensions/matching/common_inputs/network/v3/network_inputs.proto
+  ../../xds/type/v3/range.proto
+  ../../xds/type/v3/typed_struct.proto
+  ../../xds/type/matcher/v3/ip.proto
+  ../../xds/type/matcher/v3/matcher.proto
+  ../../xds/type/matcher/v3/range.proto
+  ../../xds/type/matcher/v3/regex.proto
+  ../../xds/type/matcher/v3/string.proto
+  ../../xds/core/v3/authority.proto
+  ../../xds/core/v3/cidr.proto
+  ../../xds/core/v3/collection_entry.proto
+  ../../xds/core/v3/context_params.proto
+  ../../xds/core/v3/extension.proto
+  ../../xds/core/v3/resource.proto
+  ../../xds/core/v3/resource_locator.proto
+  ../../xds/core/v3/resource_name.proto

docs/root/intro/arch_overview/advanced/matching/matching_api.rst

@@ -16,6 +16,59 @@ better performance than the linear list matching as seen in Envoy's HTTP routing
 use of extension points to make it easy to extend to different inputs based on protocol or
 environment data as well as custom sublinear matchers and direct matchers.
 
+Inputs and Matching Algorithms
+##############################
+
+Matching inputs define a way to extract the input value used for matching.
+The input functions are context-sensitive. For example, HTTP header inputs are
+applicable only in HTTP contexts, e.g. for matching HTTP requests.
+
+.. _extension_category_envoy.matching.http.input:
+
+HTTP Input Functions
+********************
+
+These input functions are available for matching HTTP requests:
+
+* :ref:`Request header value <extension_envoy.matching.inputs.request_headers>`.
+* :ref:`Request trailer value <extension_envoy.matching.inputs.request_trailers>`.
+* :ref:`Response header value <extension_envoy.matching.inputs.response_headers>`.
+* :ref:`Response trailer value <extension_envoy.matching.inputs.response_trailers>`.
+
+.. _extension_category_envoy.matching.network.input:
+
+Network Input Functions
+***********************
+
+These input functions are available for matching TCP connections:
+
+* :ref:`Destination IP <extension_envoy.matching.inputs.destination_ip>`.
+* :ref:`Destination port <extension_envoy.matching.inputs.destination_port>`.
+* :ref:`Source IP <extension_envoy.matching.inputs.source_ip>`.
+* :ref:`Direct source IP <extension_envoy.matching.inputs.direct_source_ip>`.
+* :ref:`Source port <extension_envoy.matching.inputs.source_port>`.
+* :ref:`Source type <extension_envoy.matching.inputs.source_type>`.
+* :ref:`Server name <extension_envoy.matching.inputs.server_name>`.
+* :ref:`Transport protocol <extension_envoy.matching.inputs.transport_protocol>`.
+* :ref:`Application protocol <extension_envoy.matching.inputs.application_protocol>`.
+
+Common Input Functons
+*********************
+
+These input functions are available in any context:
+
+* :ref:`Environment variable <extension_envoy.matching.common_inputs.environment_variable>`.
+
+Custom Matching Algorithms
+**************************
+
+In addition to the built-in exact and prefix matchers, these custom matchers
+are available in some contexts:
+
+.. _extension_envoy.matching.custom_matchers.trie_matcher:
+
+* :ref:`Trie-based IP matcher <envoy_v3_api_msg_.xds.type.matcher.v3.IPMatcher>` applies to network inputs.
+
 Filter Integration
 ##################
 

source/common/http/matching/inputs.h

@@ -51,7 +51,7 @@ class HttpHeadersDataInputFactoryBase : public Matcher::DataInputFactory<HttpMat
 public:
   explicit HttpHeadersDataInputFactoryBase(const std::string& name) : name_(name) {}
 
-  std::string name() const override { return name_; }
+  std::string name() const override { return "envoy.matching.inputs." + name_; }
 
   Matcher::DataInputFactoryCb<HttpMatchingData>
   createDataInputFactoryCb(const Protobuf::Message& config,
@@ -85,7 +85,7 @@ class HttpRequestHeadersDataInputFactory
     : public HttpHeadersDataInputFactoryBase<
           HttpRequestHeadersDataInput, envoy::type::matcher::v3::HttpRequestHeaderMatchInput> {
 public:
-  HttpRequestHeadersDataInputFactory() : HttpHeadersDataInputFactoryBase("request-headers") {}
+  HttpRequestHeadersDataInputFactory() : HttpHeadersDataInputFactoryBase("request_headers") {}
 };
 
 class HttpResponseHeadersDataInput : public HttpHeadersDataInputBase<ResponseHeaderMap> {
@@ -102,7 +102,7 @@ class HttpResponseHeadersDataInputFactory
     : public HttpHeadersDataInputFactoryBase<
           HttpResponseHeadersDataInput, envoy::type::matcher::v3::HttpResponseHeaderMatchInput> {
 public:
-  HttpResponseHeadersDataInputFactory() : HttpHeadersDataInputFactoryBase("response-headers") {}
+  HttpResponseHeadersDataInputFactory() : HttpHeadersDataInputFactoryBase("response_headers") {}
 };
 
 class HttpRequestTrailersDataInput : public HttpHeadersDataInputBase<RequestTrailerMap> {
@@ -119,7 +119,7 @@ class HttpRequestTrailersDataInputFactory
     : public HttpHeadersDataInputFactoryBase<
           HttpRequestTrailersDataInput, envoy::type::matcher::v3::HttpRequestTrailerMatchInput> {
 public:
-  HttpRequestTrailersDataInputFactory() : HttpHeadersDataInputFactoryBase("request-trailers") {}
+  HttpRequestTrailersDataInputFactory() : HttpHeadersDataInputFactoryBase("request_trailers") {}
 };
 
 class HttpResponseTrailersDataInput : public HttpHeadersDataInputBase<ResponseTrailerMap> {
@@ -137,7 +137,7 @@ class HttpResponseTrailersDataInputFactory
     : public HttpHeadersDataInputFactoryBase<
           HttpRequestTrailersDataInput, envoy::type::matcher::v3::HttpRequestTrailerMatchInput> {
 public:
-  HttpResponseTrailersDataInputFactory() : HttpHeadersDataInputFactoryBase("response-trailers") {}
+  HttpResponseTrailersDataInputFactory() : HttpHeadersDataInputFactoryBase("response_trailers") {}
 };
 } // namespace Matching
 } // namespace Http

source/common/network/matching/inputs.h

@@ -15,7 +15,7 @@ class BaseFactory : public Matcher::DataInputFactory<MatchingData> {
   explicit BaseFactory(const std::string& name) : name_(name) {}
 
 public:
-  std::string name() const override { return name_; }
+  std::string name() const override { return "envoy.matching.inputs." + name_; }
 
   Matcher::DataInputFactoryCb<MatchingData>
   createDataInputFactoryCb(const Protobuf::Message&, ProtobufMessage::ValidationVisitor&) override {
@@ -39,7 +39,7 @@ class DestinationIPInputFactory
           DestinationIPInput,
           envoy::extensions::matching::common_inputs::network::v3::DestinationIPInput> {
 public:
-  DestinationIPInputFactory() : BaseFactory("destination-ip") {}
+  DestinationIPInputFactory() : BaseFactory("destination_ip") {}
 };
 
 class DestinationPortInput : public Matcher::DataInput<MatchingData> {
@@ -52,7 +52,7 @@ class DestinationPortInputFactory
           DestinationPortInput,
           envoy::extensions::matching::common_inputs::network::v3::DestinationPortInput> {
 public:
-  DestinationPortInputFactory() : BaseFactory("destination-port") {}
+  DestinationPortInputFactory() : BaseFactory("destination_port") {}
 };
 
 class SourceIPInput : public Matcher::DataInput<MatchingData> {
@@ -64,7 +64,7 @@ class SourceIPInputFactory
     : public BaseFactory<SourceIPInput,
                          envoy::extensions::matching::common_inputs::network::v3::SourceIPInput> {
 public:
-  SourceIPInputFactory() : BaseFactory("source-ip") {}
+  SourceIPInputFactory() : BaseFactory("source_ip") {}
 };
 
 class SourcePortInput : public Matcher::DataInput<MatchingData> {
@@ -76,7 +76,7 @@ class SourcePortInputFactory
     : public BaseFactory<SourcePortInput,
                          envoy::extensions::matching::common_inputs::network::v3::SourcePortInput> {
 public:
-  SourcePortInputFactory() : BaseFactory("source-port") {}
+  SourcePortInputFactory() : BaseFactory("source_port") {}
 };
 
 class DirectSourceIPInput : public Matcher::DataInput<MatchingData> {
@@ -89,7 +89,7 @@ class DirectSourceIPInputFactory
           DirectSourceIPInput,
           envoy::extensions::matching::common_inputs::network::v3::DirectSourceIPInput> {
 public:
-  DirectSourceIPInputFactory() : BaseFactory("direct-source-ip") {}
+  DirectSourceIPInputFactory() : BaseFactory("direct_source_ip") {}
 };
 
 class SourceTypeInput : public Matcher::DataInput<MatchingData> {
@@ -101,7 +101,7 @@ class SourceTypeInputFactory
     : public BaseFactory<SourceTypeInput,
                          envoy::extensions::matching::common_inputs::network::v3::SourceTypeInput> {
 public:
-  SourceTypeInputFactory() : BaseFactory("source-type") {}
+  SourceTypeInputFactory() : BaseFactory("source_type") {}
 };
 
 class ServerNameInput : public Matcher::DataInput<MatchingData> {
@@ -113,7 +113,7 @@ class ServerNameInputFactory
     : public BaseFactory<ServerNameInput,
                          envoy::extensions::matching::common_inputs::network::v3::ServerNameInput> {
 public:
-  ServerNameInputFactory() : BaseFactory("server-name") {}
+  ServerNameInputFactory() : BaseFactory("server_name") {}
 };
 
 class TransportProtocolInput : public Matcher::DataInput<MatchingData> {
@@ -126,7 +126,7 @@ class TransportProtocolInputFactory
           TransportProtocolInput,
           envoy::extensions::matching::common_inputs::network::v3::TransportProtocolInput> {
 public:
-  TransportProtocolInputFactory() : BaseFactory("transport-protocol") {}
+  TransportProtocolInputFactory() : BaseFactory("transport_protocol") {}
 };
 
 class ApplicationProtocolInput : public Matcher::DataInput<MatchingData> {
@@ -139,7 +139,7 @@ class ApplicationProtocolInputFactory
           ApplicationProtocolInput,
           envoy::extensions::matching::common_inputs::network::v3::ApplicationProtocolInput> {
 public:
-  ApplicationProtocolInputFactory() : BaseFactory("application-protocol") {}
+  ApplicationProtocolInputFactory() : BaseFactory("application_protocol") {}
 };
 
 } // namespace Matching