api: Add observability mode in ext_proc (#32696)

---------

Signed-off-by: tyxia <tyxia@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 14f27cb2678774110ecdf7338355b969f9b669fb

envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto

@@ -97,8 +97,12 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // <arch_overview_advanced_filter_state_sharing>` object in a namespace matching the filter
 // name.
 //
-// [#next-free-field: 17]
+// [#next-free-field: 18]
 message ExternalProcessor {
+  reserved 4;
+
+  reserved "async_mode";
+
   // Configuration for the gRPC service that the filter will communicate with.
   // The filter supports both the "Envoy" and "Google" gRPC clients.
   config.core.v3.GrpcService grpc_service = 1 [(validate.rules).message = {required: true}];
@@ -116,14 +120,6 @@ message ExternalProcessor {
   // sent. See ProcessingMode for details.
   ProcessingMode processing_mode = 3;
 
-  // [#not-implemented-hide:]
-  // If true, send each part of the HTTP request or response specified by ProcessingMode
-  // asynchronously -- in other words, send the message on the gRPC stream and then continue
-  // filter processing. If false, which is the default, suspend filter execution after
-  // each message is sent to the remote service and wait up to "message_timeout"
-  // for a reply.
-  bool async_mode = 4;
-
   // Envoy provides a number of :ref:`attributes <arch_overview_attributes>`
   // for expressive policies. Each attribute name provided in this field will be
   // matched against that list and populated in the request_headers message.
@@ -206,6 +202,30 @@ message ExternalProcessor {
 
   // Options related to the sending and receiving of dynamic metadata.
   MetadataOptions metadata_options = 16;
+
+  // If true, send each part of the HTTP request or response specified by ProcessingMode
+  // without pausing on filter chain iteration. It is "Send and Go" mode that can be used
+  // by external processor to observe Envoy data and status. In this mode:
+  //
+  // 1. Only STREAMED body processing mode is supported and any other body processing modes will be
+  // ignored. NONE mode(i.e., skip body processing) will still work as expected.
+  //
+  // 2. External processor should not send back processing response, as any responses will be ignored.
+  // This also means that
+  // :ref:`message_timeout <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.message_timeout>`
+  // restriction doesn't apply to this mode.
+  //
+  // 3. External processor may still close the stream to indicate that no more messages are needed.
+  //
+  // .. warning::
+  //
+  //    Flow control is necessary mechanism to prevent the fast sender (either downstream client or upstream server)
+  //    from overwhelming the external processor when its processing speed is slower.
+  //    This protective measure is being explored and developed but has not been ready yet, so please use your own
+  //    discretion when enabling this feature.
+  //    This work is currently tracked under https://github.com/envoyproxy/envoy/issues/33319.
+  //
+  bool observability_mode = 17;
 }
 
 // The MetadataOptions structure defines options for the sending and receiving of

envoy/service/ext_proc/v3/external_processor.proto

@@ -57,20 +57,11 @@ service ExternalProcessor {
 
 // This represents the different types of messages that Envoy can send
 // to an external processing server.
-// [#next-free-field: 10]
+// [#next-free-field: 11]
 message ProcessingRequest {
-  // Specify whether the filter that sent this request is running in synchronous
-  // or asynchronous mode. The choice of synchronous or asynchronous mode
-  // can be set in the filter configuration, and defaults to false.
-  //
-  // * A value of ``false`` indicates that the server must respond
-  //   to this message by either sending back a matching ProcessingResponse message,
-  //   or by closing the stream.
-  // * A value of ``true`` indicates that the server must not respond to this
-  //   message, although it may still close the stream to indicate that no more messages
-  //   are needed.
-  //
-  bool async_mode = 1;
+  reserved 1;
+
+  reserved "async_mode";
 
   // Each request message will include one of the following sub-messages. Which
   // ones are set for a particular HTTP request/response depend on the
@@ -79,31 +70,31 @@ message ProcessingRequest {
     option (validate.required) = true;
 
     // Information about the HTTP request headers, as well as peer info and additional
-    // properties. Unless ``async_mode`` is ``true``, the server must send back a
+    // properties. Unless ``observability_mode`` is ``true``, the server must send back a
     // HeaderResponse message, an ImmediateResponse message, or close the stream.
     HttpHeaders request_headers = 2;
 
     // Information about the HTTP response headers, as well as peer info and additional
-    // properties. Unless ``async_mode`` is ``true``, the server must send back a
+    // properties. Unless ``observability_mode`` is ``true``, the server must send back a
     // HeaderResponse message or close the stream.
     HttpHeaders response_headers = 3;
 
-    // A chunk of the HTTP request body. Unless ``async_mode`` is true, the server must send back
+    // A chunk of the HTTP request body. Unless ``observability_mode`` is true, the server must send back
     // a BodyResponse message, an ImmediateResponse message, or close the stream.
     HttpBody request_body = 4;
 
-    // A chunk of the HTTP response body. Unless ``async_mode`` is ``true``, the server must send back
+    // A chunk of the HTTP response body. Unless ``observability_mode`` is ``true``, the server must send back
     // a BodyResponse message or close the stream.
     HttpBody response_body = 5;
 
-    // The HTTP trailers for the request path. Unless ``async_mode`` is ``true``, the server
+    // The HTTP trailers for the request path. Unless ``observability_mode`` is ``true``, the server
     // must send back a TrailerResponse message or close the stream.
     //
     // This message is only sent if the trailers processing mode is set to ``SEND`` and
     // the original downstream request has trailers.
     HttpTrailers request_trailers = 6;
 
-    // The HTTP trailers for the response path. Unless ``async_mode`` is ``true``, the server
+    // The HTTP trailers for the response path. Unless ``observability_mode`` is ``true``, the server
     // must send back a TrailerResponse message or close the stream.
     //
     // This message is only sent if the trailers processing mode is set to ``SEND`` and
@@ -119,9 +110,22 @@ message ProcessingRequest {
   // in the list is populated from the standard
   // :ref:`attributes <arch_overview_attributes>` supported across Envoy.
   map<string, google.protobuf.Struct> attributes = 9;
+
+  // Specify whether the filter that sent this request is running in :ref:`observability_mode
+  // <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.observability_mode>`
+  // and defaults to false.
+  //
+  // * A value of ``false`` indicates that the server must respond
+  //   to this message by either sending back a matching ProcessingResponse message,
+  //   or by closing the stream.
+  // * A value of ``true`` indicates that the server should not respond to this message, as any
+  //   responses will be ignored. However, it may still close the stream to indicate that no more messages
+  //   are needed.
+  //
+  bool observability_mode = 10;
 }
 
-// For every ProcessingRequest received by the server with the ``async_mode`` field
+// For every ProcessingRequest received by the server with the ``observability_mode`` field
 // set to false, the server must send back exactly one ProcessingResponse message.
 // [#next-free-field: 11]
 message ProcessingResponse {