From 22712d26c427091a47324b5f05fd0b493ee4be01 Mon Sep 17 00:00:00 2001 From: htuch Date: Thu, 19 Sep 2019 21:49:33 -0400 Subject: [PATCH] api: some comment cleanups in preparation for v3 proto transforms. (#8300) * Move trailing detached comments that protoc ignores to some anchored place. In the near future, this will be enforced by check_format. * Remove comments on reserved fields; we won't be using reserved in v3 and it's a bit of a pain preserving them. Risk level: Low Testing: Docs build, diff inspection, comparison against output of proto transform tool. Signed-off-by: Harvey Tuch --- api/envoy/api/v2/core/grpc_service.proto | 1 - api/envoy/api/v2/core/health_check.proto | 3 +-- api/envoy/api/v2/core/protocol.proto | 2 -- api/envoy/api/v2/route/route.proto | 7 ++---- api/envoy/config/bootstrap/v2/bootstrap.proto | 7 ++++-- .../config/filter/http/buffer/v2/buffer.proto | 2 +- .../dubbo_proxy/v2alpha1/dubbo_proxy.proto | 6 +++-- .../v2/http_connection_manager.proto | 2 +- api/envoy/config/trace/v2/trace.proto | 2 +- api/envoy/data/tap/v2alpha/transport.proto | 4 +-- .../service/auth/v2/attribute_context.proto | 25 ++++++++----------- api/envoy/service/tap/v2alpha/common.proto | 4 +-- 12 files changed, 30 insertions(+), 35 deletions(-) diff --git a/api/envoy/api/v2/core/grpc_service.proto b/api/envoy/api/v2/core/grpc_service.proto index 705c61f5a133..9b0ba80b93cc 100644 --- a/api/envoy/api/v2/core/grpc_service.proto +++ b/api/envoy/api/v2/core/grpc_service.proto @@ -160,7 +160,6 @@ message GrpcService { // request. google.protobuf.Duration timeout = 3; - // Field 4 reserved due to moving credentials inside the GoogleGrpc message reserved 4; // Additional metadata to include in streams initiated to the GrpcService. diff --git a/api/envoy/api/v2/core/health_check.proto b/api/envoy/api/v2/core/health_check.proto index 64396f8380a4..5bc496fdb68d 100644 --- a/api/envoy/api/v2/core/health_check.proto +++ b/api/envoy/api/v2/core/health_check.proto @@ -189,8 +189,7 @@ message HealthCheck { CustomHealthCheck custom_health_check = 13; } - reserved 10; // redis_health_check is deprecated by :ref:`custom_health_check - // ` + reserved 10; reserved "redis_health_check"; // The "no traffic interval" is a special health check interval that is used when a cluster has diff --git a/api/envoy/api/v2/core/protocol.proto b/api/envoy/api/v2/core/protocol.proto index 63137ec227f4..68103cb00e1b 100644 --- a/api/envoy/api/v2/core/protocol.proto +++ b/api/envoy/api/v2/core/protocol.proto @@ -1,5 +1,3 @@ -// [#protodoc-title: Protocol options] - syntax = "proto3"; package envoy.api.v2.core; diff --git a/api/envoy/api/v2/route/route.proto b/api/envoy/api/v2/route/route.proto index 3f859f20f901..ff7fa88a81de 100644 --- a/api/envoy/api/v2/route/route.proto +++ b/api/envoy/api/v2/route/route.proto @@ -1291,11 +1291,8 @@ message HeaderMatcher { // Specifies the name of the header in the request. string name = 1 [(validate.rules).string.min_bytes = 1]; - reserved 2; // value deprecated by :ref:`exact_match - // ` - - reserved 3; // regex deprecated by :ref:`regex_match - // ` + reserved 2; + reserved 3; // Specifies how the header match will be performed to route the request. oneof header_match_specifier { diff --git a/api/envoy/config/bootstrap/v2/bootstrap.proto b/api/envoy/config/bootstrap/v2/bootstrap.proto index b8f17de61870..5a3447167b81 100644 --- a/api/envoy/config/bootstrap/v2/bootstrap.proto +++ b/api/envoy/config/bootstrap/v2/bootstrap.proto @@ -293,15 +293,18 @@ message RuntimeLayer { string name = 1 [(validate.rules).string.min_bytes = 1]; oneof layer_specifier { + option (validate.required) = true; + // :ref:`Static runtime ` layer. // This follows the :ref:`runtime protobuf JSON representation encoding // `. Unlike static xDS resources, this static // layer is overridable by later layers in the runtime virtual filesystem. - option (validate.required) = true; - google.protobuf.Struct static_layer = 2; + DiskLayer disk_layer = 3; + AdminLayer admin_layer = 4; + RtdsLayer rtds_layer = 5; } } diff --git a/api/envoy/config/filter/http/buffer/v2/buffer.proto b/api/envoy/config/filter/http/buffer/v2/buffer.proto index ce6c0d6d1423..7f2f8c98239c 100644 --- a/api/envoy/config/filter/http/buffer/v2/buffer.proto +++ b/api/envoy/config/filter/http/buffer/v2/buffer.proto @@ -14,7 +14,7 @@ import "validate/validate.proto"; // Buffer :ref:`configuration overview `. message Buffer { - reserved 2; // formerly max_request_time + reserved 2; // The maximum request size that the filter will buffer before the connection // manager will stop buffering and return a 413 response. diff --git a/api/envoy/config/filter/network/dubbo_proxy/v2alpha1/dubbo_proxy.proto b/api/envoy/config/filter/network/dubbo_proxy/v2alpha1/dubbo_proxy.proto index a27d7001cb86..d4c6937e56ec 100644 --- a/api/envoy/config/filter/network/dubbo_proxy/v2alpha1/dubbo_proxy.proto +++ b/api/envoy/config/filter/network/dubbo_proxy/v2alpha1/dubbo_proxy.proto @@ -38,12 +38,14 @@ message DubboProxy { // Dubbo Protocol types supported by Envoy. enum ProtocolType { - Dubbo = 0; // the default protocol. + // the default protocol. + Dubbo = 0; } // Dubbo Serialization types supported by Envoy. enum SerializationType { - Hessian2 = 0; // the default serialization protocol. + // the default serialization protocol. + Hessian2 = 0; } // DubboFilter configures a Dubbo filter. diff --git a/api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto b/api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto index 05c351eb14d8..fae9786c3893 100644 --- a/api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto +++ b/api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto @@ -350,7 +350,7 @@ message HttpConnectionManager { // Whether to forward the subject of the client cert. Defaults to false. google.protobuf.BoolValue subject = 1; - reserved 2; // san deprecated by uri + reserved 2; // Whether to forward the entire client cert in URL encoded PEM format. This will appear in the // XFCC header comma separated from other values with the value Cert="PEM". diff --git a/api/envoy/config/trace/v2/trace.proto b/api/envoy/config/trace/v2/trace.proto index 43f5013b27f1..7b4df8bf5258 100644 --- a/api/envoy/config/trace/v2/trace.proto +++ b/api/envoy/config/trace/v2/trace.proto @@ -169,7 +169,7 @@ message OpenCensusConfig { // format: https://github.com/grpc/grpc/blob/master/doc/naming.md string ocagent_address = 12; - reserved 7; // Formerly zipkin_service_name. + reserved 7; enum TraceContext { // No-op default, no trace context is utilized. diff --git a/api/envoy/data/tap/v2alpha/transport.proto b/api/envoy/data/tap/v2alpha/transport.proto index c3a3d8b8eb86..9f3f79b4951f 100644 --- a/api/envoy/data/tap/v2alpha/transport.proto +++ b/api/envoy/data/tap/v2alpha/transport.proto @@ -31,10 +31,10 @@ message SocketEvent { // Data read by Envoy from the transport socket. message Read { + // TODO(htuch): Half-close for reads. + // Binary data read. Body data = 1; - - // TODO(htuch): Half-close for reads. } // Data written by Envoy to the transport socket. diff --git a/api/envoy/service/auth/v2/attribute_context.proto b/api/envoy/service/auth/v2/attribute_context.proto index cfb71ec0ce5f..b35e988d7b50 100644 --- a/api/envoy/service/auth/v2/attribute_context.proto +++ b/api/envoy/service/auth/v2/attribute_context.proto @@ -22,6 +22,17 @@ import "google/protobuf/timestamp.proto"; // Each attribute has a type and a name, which is logically defined as a proto message field // of the `AttributeContext`. The `AttributeContext` is a collection of individual attributes // supported by Envoy authorization system. +// [#comment: The following items are left out of this proto +// Request.Auth field for jwt tokens +// Request.Api for api management +// Origin peer that originated the request +// Caching Protocol +// request_context return values to inject back into the filter chain +// peer.claims -- from X.509 extensions +// Configuration +// - field mask to send +// - which return values from request_context are copied back +// - which return values are copied into request_headers] message AttributeContext { // This message defines attributes for a node that handles a network request. // The node can be either a service or an application that sends, forwards, @@ -63,8 +74,6 @@ message AttributeContext { // Represents an HTTP request or an HTTP-like request. HttpRequest http = 2; - - // More request types are added here as necessary. } // This message defines attributes for an HTTP request. @@ -137,15 +146,3 @@ message AttributeContext { // Dynamic metadata associated with the request. envoy.api.v2.core.Metadata metadata_context = 11; } - -// The following items are left out of this proto -// Request.Auth field for jwt tokens -// Request.Api for api management -// Origin peer that originated the request -// Caching Protocol -// request_context return values to inject back into the filter chain -// peer.claims -- from X.509 extensions -// Configuration -// - field mask to send -// - which return values from request_context are copied back -// - which return values are copied into request_headers diff --git a/api/envoy/service/tap/v2alpha/common.proto b/api/envoy/service/tap/v2alpha/common.proto index 54437b305469..4aa06568c85e 100644 --- a/api/envoy/service/tap/v2alpha/common.proto +++ b/api/envoy/service/tap/v2alpha/common.proto @@ -18,6 +18,8 @@ option java_package = "io.envoyproxy.envoy.service.tap.v2alpha"; // Tap configuration. message TapConfig { + // [#comment:TODO(mattklein123): Rate limiting] + // The match configuration. If the configuration matches the data source being tapped, a tap will // occur, with the result written to the configured output. MatchPredicate match_config = 1 [(validate.rules).message.required = true]; @@ -35,8 +37,6 @@ message TapConfig { // This field defaults to 100/:ref:`HUNDRED // `. envoy.api.v2.core.RuntimeFractionalPercent tap_enabled = 3; - - // [#comment:TODO(mattklein123): Rate limiting] } // Tap match configuration. This is a recursive structure which allows complex nested match