docs/proto: Adding comments to fields/enums that have no comments (#37018)

An internal tool we have notified us that some API fields and enum-values that we use do not have comments. I've added some comments, and updated some of the ext-proc comments to make it a bit clearer. Signed-off-by: Adi Suissa-Peleg <adip@google.com> Mirrored from https://github.com/envoyproxy/envoy @ 522c94a5e7804057433d8d5cc79aa236a564c279
3 weeks ago · 2f2e77908f
parent cbb7b6e3fb
commit 2f2e77908f
3 changed files with 89 additions and 16 deletions
--- a/envoy/config/core/v3/base.proto
+++ b/envoy/config/core/v3/base.proto
@ -453,6 +453,7 @@ message HeaderValueOption {
 message HeaderMap {
  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HeaderMap";

+  // A list of header names and their values.
  repeated HeaderValue headers = 1;
 }

--- a/envoy/service/ext_proc/v3/external_processor.proto
+++ b/envoy/service/ext_proc/v3/external_processor.proto
@ -45,7 +45,6 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // In other words, the process is a request/response conversation, but
 // using a gRPC stream to make it easier for the server to
 // maintain state.
-
 service ExternalProcessor {
  // This begins the bidirectional stream that Envoy will use to
  // give the server control over what the filter does. The actual
@ -129,6 +128,7 @@ message ProcessingRequest {
 // set to false, the server must send back exactly one ProcessingResponse message.
 // [#next-free-field: 11]
 message ProcessingResponse {
+  // The response type that is sent by the server.
  oneof response {
    option (validate.required) = true;

@ -220,19 +220,25 @@ message HttpHeaders {
  map<string, google.protobuf.Struct> attributes = 2
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

-  // If true, then there is no message body associated with this
+  // If ``true``, then there is no message body associated with this
  // request or response.
  bool end_of_stream = 3;
 }

-// This message contains the message body that Envoy sends to the external server.
+// This message is sent to the external server when the HTTP request and
+// response bodies are received.
 message HttpBody {
+  // The contents of the body in the HTTP request/response. Note that in
+  // streaming mode multiple ``HttpBody`` messages may be sent.
  bytes body = 1;

+  // If ``true``, this will be the last ``HttpBody`` message that will be sent and no
+  // trailers will be sent for the current request/response.
  bool end_of_stream = 2;
 }

-// This message contains the trailers.
+// This message is sent to the external server when the HTTP request and
+// response trailers are received.
 message HttpTrailers {
  // The header value is encoded in the
  // :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.
@ -241,25 +247,34 @@ message HttpTrailers {

 // The following are messages that may be sent back by the server.

-// This message must be sent in response to an HttpHeaders message.
+// This message is sent by the external server to Envoy after ``HttpHeaders`` was
+// sent to it.
 message HeadersResponse {
+  // Details the modifications (if any) to be made by Envoy to the current
+  // request/response.
  CommonResponse response = 1;
 }

-// This message must be sent in response to an HttpTrailers message.
-message TrailersResponse {
-  // Instructions on how to manipulate the trailers
-  HeaderMutation header_mutation = 1;
-}
-
-// This message must be sent in response to an HttpBody message.
+// This message is sent by the external server to Envoy after ``HttpBody`` was
+// sent to it.
 message BodyResponse {
+  // Details the modifications (if any) to be made by Envoy to the current
+  // request/response.
  CommonResponse response = 1;
 }

+// This message is sent by the external server to Envoy after ``HttpTrailers`` was
+// sent to it.
+message TrailersResponse {
+  // Details the modifications (if any) to be made by Envoy to the current
+  // request/response trailers.
+  HeaderMutation header_mutation = 1;
+}
+
 // This message contains common fields between header and body responses.
 // [#next-free-field: 6]
 message CommonResponse {
+  // The status of the response.
  enum ResponseStatus {
    // Apply the mutation instructions in this message to the
    // request or response, and then continue processing the filter
@ -322,7 +337,7 @@ message CommonResponse {
 // to the downstream codec, or reset the stream.
 // [#next-free-field: 6]
 message ImmediateResponse {
-  // The response code to return
+  // The response code to return.
  type.v3.HttpStatus status = 1 [(validate.rules).message = {required: true}];

  // Apply changes to the default headers, which will include content-type.
@ -343,7 +358,7 @@ message ImmediateResponse {

 // This message specifies a gRPC status for an ImmediateResponse message.
 message GrpcStatus {
-  // The actual gRPC status
+  // The actual gRPC status.
  uint32 status = 1;
 }

@ -365,11 +380,12 @@ message HeaderMutation {
 // Replace the entire message body chunk received in the corresponding
 // HttpBody message with this new body, or clear the body.
 message BodyMutation {
+  // The type of mutation for the body.
  oneof mutation {
-    // The entire body to replace
+    // The entire body to replace.
    bytes body = 1;

-    // Clear the corresponding body chunk
+    // Clear the corresponding body chunk.
    bool clear_body = 2;
  }
 }
--- a/envoy/type/v3/http_status.proto
+++ b/envoy/type/v3/http_status.proto
@ -21,116 +21,172 @@ enum StatusCode {
  // `enum` type.
  Empty = 0;

+  // Continue - ``100`` status code.
  Continue = 100;

+  // OK - ``200`` status code.
  OK = 200;

+  // Created - ``201`` status code.
  Created = 201;

+  // Accepted - ``202`` status code.
  Accepted = 202;

+  // NonAuthoritativeInformation - ``203`` status code.
  NonAuthoritativeInformation = 203;

+  // NoContent - ``204`` status code.
  NoContent = 204;

+  // ResetContent - ``205`` status code.
  ResetContent = 205;

+  // PartialContent - ``206`` status code.
  PartialContent = 206;

+  // MultiStatus - ``207`` status code.
  MultiStatus = 207;

+  // AlreadyReported - ``208`` status code.
  AlreadyReported = 208;

+  // IMUsed - ``226`` status code.
  IMUsed = 226;

+  // MultipleChoices - ``300`` status code.
  MultipleChoices = 300;

+  // MovedPermanently - ``301`` status code.
  MovedPermanently = 301;

+  // Found - ``302`` status code.
  Found = 302;

+  // SeeOther - ``303`` status code.
  SeeOther = 303;

+  // NotModified - ``304`` status code.
  NotModified = 304;

+  // UseProxy - ``305`` status code.
  UseProxy = 305;

+  // TemporaryRedirect - ``307`` status code.
  TemporaryRedirect = 307;

+  // PermanentRedirect - ``308`` status code.
  PermanentRedirect = 308;

+  // BadRequest - ``400`` status code.
  BadRequest = 400;

+  // Unauthorized - ``401`` status code.
  Unauthorized = 401;

+  // PaymentRequired - ``402`` status code.
  PaymentRequired = 402;

+  // Forbidden - ``403`` status code.
  Forbidden = 403;

+  // NotFound - ``404`` status code.
  NotFound = 404;

+  // MethodNotAllowed - ``405`` status code.
  MethodNotAllowed = 405;

+  // NotAcceptable - ``406`` status code.
  NotAcceptable = 406;

+  // ProxyAuthenticationRequired - ``407`` status code.
  ProxyAuthenticationRequired = 407;

+  // RequestTimeout - ``408`` status code.
  RequestTimeout = 408;

+  // Conflict - ``409`` status code.
  Conflict = 409;

+  // Gone - ``410`` status code.
  Gone = 410;

+  // LengthRequired - ``411`` status code.
  LengthRequired = 411;

+  // PreconditionFailed - ``412`` status code.
  PreconditionFailed = 412;

+  // PayloadTooLarge - ``413`` status code.
  PayloadTooLarge = 413;

+  // URITooLong - ``414`` status code.
  URITooLong = 414;

+  // UnsupportedMediaType - ``415`` status code.
  UnsupportedMediaType = 415;

+  // RangeNotSatisfiable - ``416`` status code.
  RangeNotSatisfiable = 416;

+  // ExpectationFailed - ``417`` status code.
  ExpectationFailed = 417;

+  // MisdirectedRequest - ``421`` status code.
  MisdirectedRequest = 421;

+  // UnprocessableEntity - ``422`` status code.
  UnprocessableEntity = 422;

+  // Locked - ``423`` status code.
  Locked = 423;

+  // FailedDependency - ``424`` status code.
  FailedDependency = 424;

+  // UpgradeRequired - ``426`` status code.
  UpgradeRequired = 426;

+  // PreconditionRequired - ``428`` status code.
  PreconditionRequired = 428;

+  // TooManyRequests - ``429`` status code.
  TooManyRequests = 429;

+  // RequestHeaderFieldsTooLarge - ``431`` status code.
  RequestHeaderFieldsTooLarge = 431;

+  // InternalServerError - ``500`` status code.
  InternalServerError = 500;

+  // NotImplemented - ``501`` status code.
  NotImplemented = 501;

+  // BadGateway - ``502`` status code.
  BadGateway = 502;

+  // ServiceUnavailable - ``503`` status code.
  ServiceUnavailable = 503;

+  // GatewayTimeout - ``504`` status code.
  GatewayTimeout = 504;

+  // HTTPVersionNotSupported - ``505`` status code.
  HTTPVersionNotSupported = 505;

+  // VariantAlsoNegotiates - ``506`` status code.
  VariantAlsoNegotiates = 506;

+  // InsufficientStorage - ``507`` status code.
  InsufficientStorage = 507;

+  // LoopDetected - ``508`` status code.
  LoopDetected = 508;

+  // NotExtended - ``510`` status code.
  NotExtended = 510;

+  // NetworkAuthenticationRequired - ``511`` status code.
  NetworkAuthenticationRequired = 511;
 }