From db2f5481fda0e012d4406fcdeb6283287030b15d Mon Sep 17 00:00:00 2001 From: "data-plane-api(Azure Pipelines)" Date: Fri, 21 May 2021 03:31:52 +0000 Subject: [PATCH] docs: mark matching API and related features as alpha (#16210) Marks the matching API more clearly as experimental and updates the composite filter security posture to reflect this. Signed-off-by: Snow Pettersen Mirrored from https://github.com/envoyproxy/envoy @ b6039234e526eeccdf332a7eb041729aaa1bc286 --- STYLE.md | 5 +++++ envoy/config/common/matcher/v3/matcher.proto | 2 +- envoy/config/common/matcher/v4alpha/matcher.proto | 2 +- envoy/extensions/common/matching/v3/extension_matcher.proto | 2 ++ .../common/matching/v4alpha/extension_matcher.proto | 2 ++ envoy/extensions/filters/http/composite/v3/composite.proto | 1 + 6 files changed, 12 insertions(+), 2 deletions(-) diff --git a/STYLE.md b/STYLE.md index 30599e19..63686095 100644 --- a/STYLE.md +++ b/STYLE.md @@ -34,6 +34,11 @@ In addition, the following conventions should be followed: implementation. These indicate that the entity is not implemented in Envoy and the entity should be hidden from the Envoy documentation. +* Use a `[#alpha:]` annotation in comments for messages that are considered alpha + and are not subject to the threat model. This is similar to the work-in-progress/alpha tagging + of extensions described below, but allows tagging messages that are used as part of the core API + as alpha without having to break it into its own file. + * Always use plural field names for `repeated` fields, such as `filters`. * Due to the fact that we consider JSON/YAML to be first class inputs, we cannot easily change a diff --git a/envoy/config/common/matcher/v3/matcher.proto b/envoy/config/common/matcher/v3/matcher.proto index d09dcbd0..d7deb71d 100644 --- a/envoy/config/common/matcher/v3/matcher.proto +++ b/envoy/config/common/matcher/v3/matcher.proto @@ -22,7 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // As an on_no_match might result in another matching tree being evaluated, this process // might repeat several times until the final OnMatch (or no match) is decided. // -// This API is a work in progress. +// [#alpha:] message Matcher { // What to do if a match is successful. message OnMatch { diff --git a/envoy/config/common/matcher/v4alpha/matcher.proto b/envoy/config/common/matcher/v4alpha/matcher.proto index fd5928e2..2027331b 100644 --- a/envoy/config/common/matcher/v4alpha/matcher.proto +++ b/envoy/config/common/matcher/v4alpha/matcher.proto @@ -23,7 +23,7 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO // As an on_no_match might result in another matching tree being evaluated, this process // might repeat several times until the final OnMatch (or no match) is decided. // -// This API is a work in progress. +// [#alpha:] message Matcher { option (udpa.annotations.versioning).previous_message_type = "envoy.config.common.matcher.v3.Matcher"; diff --git a/envoy/extensions/common/matching/v3/extension_matcher.proto b/envoy/extensions/common/matching/v3/extension_matcher.proto index 2d01e17b..e317d885 100644 --- a/envoy/extensions/common/matching/v3/extension_matcher.proto +++ b/envoy/extensions/common/matching/v3/extension_matcher.proto @@ -18,6 +18,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Wrapper around an existing extension that provides an associated matcher. This allows // decorating an existing extension with a matcher, which can be used to match against // relevant protocol data. +// +// [#alpha:] message ExtensionWithMatcher { // The associated matcher. config.common.matcher.v3.Matcher matcher = 1 [(validate.rules).message = {required: true}]; diff --git a/envoy/extensions/common/matching/v4alpha/extension_matcher.proto b/envoy/extensions/common/matching/v4alpha/extension_matcher.proto index bb71cc5a..88ac7c75 100644 --- a/envoy/extensions/common/matching/v4alpha/extension_matcher.proto +++ b/envoy/extensions/common/matching/v4alpha/extension_matcher.proto @@ -19,6 +19,8 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO // Wrapper around an existing extension that provides an associated matcher. This allows // decorating an existing extension with a matcher, which can be used to match against // relevant protocol data. +// +// [#alpha:] message ExtensionWithMatcher { option (udpa.annotations.versioning).previous_message_type = "envoy.extensions.common.matching.v3.ExtensionWithMatcher"; diff --git a/envoy/extensions/filters/http/composite/v3/composite.proto b/envoy/extensions/filters/http/composite/v3/composite.proto index 3afc1369..f8a3bd83 100644 --- a/envoy/extensions/filters/http/composite/v3/composite.proto +++ b/envoy/extensions/filters/http/composite/v3/composite.proto @@ -26,6 +26,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // :ref:`ExecuteFilterAction `) // which filter configuration to create and delegate to. // +// [#alpha:] message Composite { }