.. _envoy_v3_api_file_envoy/service/ext_proc/v3/external_processor.proto:

External processing service (proto)
===================================




A service that can access and modify HTTP requests and responses
as part of a filter chain.
The overall external processing protocol works like this:

1. Envoy sends to the service information about the HTTP request.
2. The service sends back a ProcessingResponse message that directs Envoy
   to either stop processing, continue without it, or send it the
   next chunk of the message body.
3. If so requested, Envoy sends the server chunks of the message body,
   or the entire body at once. In either case, the server sends back
   a ProcessingResponse after each message it receives.
4. If so requested, Envoy sends the server the HTTP trailers,
   and the server sends back a ProcessingResponse.
5. At this point, request processing is done, and we pick up again
   at step 1 when Envoy receives a response from the upstream server.
6. At any point above, if the server closes the gRPC stream cleanly,
   then Envoy proceeds without consulting the server.
7. At any point above, if the server closes the gRPC stream with an error,
   then Envoy returns a 500 error to the client, unless the filter
   was configured to ignore errors.

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.




.. _envoy_v3_api_msg_service.ext_proc.v3.ProcessingRequest:

service.ext_proc.v3.ProcessingRequest
-------------------------------------


:repo:`[service.ext_proc.v3.ProcessingRequest proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L59>`

This represents the different types of messages that Envoy can send
to an external processing server.



.. code-block:: json
  :force:

  {
    "async_mode": ...,
    "request_headers": {...},
    "response_headers": {...},
    "request_body": {...},
    "response_body": {...},
    "request_trailers": {...},
    "response_trailers": {...}
  }

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.async_mode:


async_mode
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 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.



.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_headers:


request_headers
  (:ref:`service.ext_proc.v3.HttpHeaders <envoy_v3_api_msg_service.ext_proc.v3.HttpHeaders>`) 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
  HeaderResponse message, an ImmediateResponse message, or close the stream.


  Each request message will include one of the following sub-messages. Which
  ones are set for a particular HTTP request/response depend on the
  processing mode.


  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_trailers>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_headers:


response_headers
  (:ref:`service.ext_proc.v3.HttpHeaders <envoy_v3_api_msg_service.ext_proc.v3.HttpHeaders>`) 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
  HeaderResponse message or close the stream.


  Each request message will include one of the following sub-messages. Which
  ones are set for a particular HTTP request/response depend on the
  processing mode.


  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_trailers>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_body:


request_body
  (:ref:`service.ext_proc.v3.HttpBody <envoy_v3_api_msg_service.ext_proc.v3.HttpBody>`) A chunk of the HTTP request body. Unless ``async_mode`` is true, the server must send back
  a BodyResponse message, an ImmediateResponse message, or close the stream.


  Each request message will include one of the following sub-messages. Which
  ones are set for a particular HTTP request/response depend on the
  processing mode.


  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_trailers>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_body:


response_body
  (:ref:`service.ext_proc.v3.HttpBody <envoy_v3_api_msg_service.ext_proc.v3.HttpBody>`) A chunk of the HTTP request body. Unless ``async_mode`` is ``true``, the server must send back
  a BodyResponse message or close the stream.


  Each request message will include one of the following sub-messages. Which
  ones are set for a particular HTTP request/response depend on the
  processing mode.


  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_trailers>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_trailers:


request_trailers
  (:ref:`service.ext_proc.v3.HttpTrailers <envoy_v3_api_msg_service.ext_proc.v3.HttpTrailers>`) The HTTP trailers for the request path. Unless ``async_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``.
  If there are no trailers on the original downstream request, then this message
  will only be sent (with empty trailers waiting to be populated) if the
  processing mode is set before the request headers are sent, such as
  in the filter configuration.


  Each request message will include one of the following sub-messages. Which
  ones are set for a particular HTTP request/response depend on the
  processing mode.


  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_trailers>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_trailers:


response_trailers
  (:ref:`service.ext_proc.v3.HttpTrailers <envoy_v3_api_msg_service.ext_proc.v3.HttpTrailers>`) The HTTP trailers for the response path. Unless ``async_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``.
  If there are no trailers on the original downstream request, then this message
  will only be sent (with empty trailers waiting to be populated) if the
  processing mode is set before the request headers are sent, such as
  in the filter configuration.


  Each request message will include one of the following sub-messages. Which
  ones are set for a particular HTTP request/response depend on the
  processing mode.


  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.response_trailers>` must be set.


.. _envoy_v3_api_msg_service.ext_proc.v3.ProcessingResponse:

service.ext_proc.v3.ProcessingResponse
--------------------------------------


:repo:`[service.ext_proc.v3.ProcessingResponse proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L122>`

For every ProcessingRequest received by the server with the ``async_mode`` field
set to false, the server must send back exactly one ProcessingResponse message.



.. code-block:: json
  :force:

  {
    "request_headers": {...},
    "response_headers": {...},
    "request_body": {...},
    "response_body": {...},
    "request_trailers": {...},
    "response_trailers": {...},
    "immediate_response": {...},
    "mode_override": {...},
    "override_message_timeout": {...}
  }

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers:


request_headers
  (:ref:`service.ext_proc.v3.HeadersResponse <envoy_v3_api_msg_service.ext_proc.v3.HeadersResponse>`) The server must send back this message in response to a message with the
  ``request_headers`` field set.


  

  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers>`, :ref:`immediate_response <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers:


response_headers
  (:ref:`service.ext_proc.v3.HeadersResponse <envoy_v3_api_msg_service.ext_proc.v3.HeadersResponse>`) The server must send back this message in response to a message with the
  ``response_headers`` field set.


  

  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers>`, :ref:`immediate_response <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body:


request_body
  (:ref:`service.ext_proc.v3.BodyResponse <envoy_v3_api_msg_service.ext_proc.v3.BodyResponse>`) The server must send back this message in response to a message with
  the ``request_body`` field set.


  

  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers>`, :ref:`immediate_response <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body:


response_body
  (:ref:`service.ext_proc.v3.BodyResponse <envoy_v3_api_msg_service.ext_proc.v3.BodyResponse>`) The server must send back this message in response to a message with
  the ``response_body`` field set.


  

  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers>`, :ref:`immediate_response <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers:


request_trailers
  (:ref:`service.ext_proc.v3.TrailersResponse <envoy_v3_api_msg_service.ext_proc.v3.TrailersResponse>`) The server must send back this message in response to a message with
  the ``request_trailers`` field set.


  

  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers>`, :ref:`immediate_response <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers:


response_trailers
  (:ref:`service.ext_proc.v3.TrailersResponse <envoy_v3_api_msg_service.ext_proc.v3.TrailersResponse>`) The server must send back this message in response to a message with
  the ``response_trailers`` field set.


  

  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers>`, :ref:`immediate_response <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response:


immediate_response
  (:ref:`service.ext_proc.v3.ImmediateResponse <envoy_v3_api_msg_service.ext_proc.v3.ImmediateResponse>`) If specified, attempt to create a locally generated response, send it
  downstream, and stop processing additional filters and ignore any
  additional messages received from the remote server for this request or
  response. If a response has already started -- for example, if this
  message is sent response to a ``response_body`` message -- then
  this will either ship the reply directly to the downstream codec,
  or reset the stream.


  

  Precisely one of :ref:`request_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_headers>`, :ref:`response_headers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_headers>`, :ref:`request_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_body>`, :ref:`response_body <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_body>`, :ref:`request_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.request_trailers>`, :ref:`response_trailers <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.response_trailers>`, :ref:`immediate_response <envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.immediate_response>` must be set.

.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.mode_override:


mode_override
  (:ref:`extensions.filters.http.ext_proc.v3.ProcessingMode <envoy_v3_api_msg_extensions.filters.http.ext_proc.v3.ProcessingMode>`) Override how parts of the HTTP request and response are processed
  for the duration of this particular request/response only. Servers
  may use this to intelligently control how requests are processed
  based on the headers and other metadata that they see.
  This field is only applicable when servers responding to the header requests.
  If it is set in the response to the body or trailer requests, it will be ignored by Envoy.
  It is also ignored by Envoy when the ext_proc filter config
  :ref:`allow_mode_override
  <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.allow_mode_override>`
  is set to false.


.. _envoy_v3_api_field_service.ext_proc.v3.ProcessingResponse.override_message_timeout:


override_message_timeout
  (`Duration <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration>`_) When ext_proc server receives a request message, in case it needs more
  time to process the message, it sends back a ProcessingResponse message
  with a new timeout value. When Envoy receives this response message,
  it ignores other fields in the response, just stop the original timer,
  which has the timeout value specified in
  :ref:`message_timeout
  <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.message_timeout>`
  and start a new timer with this ``override_message_timeout`` value and keep the
  Envoy ext_proc filter state machine intact.
  Has to be >= 1ms and <=
  :ref:`max_message_timeout <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.max_message_timeout>`
  Such message can be sent at most once in a particular Envoy ext_proc filter processing state.
  To enable this API, one has to set ``max_message_timeout`` to a number >= 1ms.



.. _envoy_v3_api_msg_service.ext_proc.v3.HttpHeaders:

service.ext_proc.v3.HttpHeaders
-------------------------------


:repo:`[service.ext_proc.v3.HttpHeaders proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L197>`

This message is sent to the external server when the HTTP request and responses
are first received.



.. code-block:: json
  :force:

  {
    "headers": {...},
    "end_of_stream": ...
  }

.. _envoy_v3_api_field_service.ext_proc.v3.HttpHeaders.headers:


headers
  (:ref:`config.core.v3.HeaderMap <envoy_v3_api_msg_config.core.v3.HeaderMap>`) The HTTP request headers. All header keys will be
  lower-cased, because HTTP header keys are case-insensitive.
  The ``headers`` encoding is based on the runtime guard
  envoy_reloadable_features_send_header_raw_value setting.
  When it is true, the header value is encoded in the
  :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.
  When it is false, the header value is encoded in the
  :ref:`value <envoy_v3_api_field_config.core.v3.HeaderValue.value>` field.


.. _envoy_v3_api_field_service.ext_proc.v3.HttpHeaders.end_of_stream:


end_of_stream
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) If true, then there is no message body associated with this
  request or response.





.. _envoy_v3_api_msg_service.ext_proc.v3.HttpBody:

service.ext_proc.v3.HttpBody
----------------------------


:repo:`[service.ext_proc.v3.HttpBody proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L222>`

This message contains the message body that Envoy sends to the external server.



.. code-block:: json
  :force:

  {
    "body": ...,
    "end_of_stream": ...
  }

.. _envoy_v3_api_field_service.ext_proc.v3.HttpBody.body:


body
  (`bytes <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 

.. _envoy_v3_api_field_service.ext_proc.v3.HttpBody.end_of_stream:


end_of_stream
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 


.. _envoy_v3_api_msg_service.ext_proc.v3.HttpTrailers:

service.ext_proc.v3.HttpTrailers
--------------------------------


:repo:`[service.ext_proc.v3.HttpTrailers proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L229>`

This message contains the trailers.



.. code-block:: json
  :force:

  {
    "trailers": {...}
  }

.. _envoy_v3_api_field_service.ext_proc.v3.HttpTrailers.trailers:


trailers
  (:ref:`config.core.v3.HeaderMap <envoy_v3_api_msg_config.core.v3.HeaderMap>`) The ``trailers`` encoding is based on the runtime guard
  envoy_reloadable_features_send_header_raw_value setting.
  When it is true, the header value is encoded in the
  :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.
  When it is false, the header value is encoded in the
  :ref:`value <envoy_v3_api_field_config.core.v3.HeaderValue.value>` field.



.. _envoy_v3_api_msg_service.ext_proc.v3.HeadersResponse:

service.ext_proc.v3.HeadersResponse
-----------------------------------


:repo:`[service.ext_proc.v3.HeadersResponse proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L242>`

This message must be sent in response to an HttpHeaders message.



.. code-block:: json
  :force:

  {
    "response": {...}
  }

.. _envoy_v3_api_field_service.ext_proc.v3.HeadersResponse.response:


response
  (:ref:`service.ext_proc.v3.CommonResponse <envoy_v3_api_msg_service.ext_proc.v3.CommonResponse>`) 


.. _envoy_v3_api_msg_service.ext_proc.v3.TrailersResponse:

service.ext_proc.v3.TrailersResponse
------------------------------------


:repo:`[service.ext_proc.v3.TrailersResponse proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L247>`

This message must be sent in response to an HttpTrailers message.



.. code-block:: json
  :force:

  {
    "header_mutation": {...}
  }

.. _envoy_v3_api_field_service.ext_proc.v3.TrailersResponse.header_mutation:


header_mutation
  (:ref:`service.ext_proc.v3.HeaderMutation <envoy_v3_api_msg_service.ext_proc.v3.HeaderMutation>`) Instructions on how to manipulate the trailers



.. _envoy_v3_api_msg_service.ext_proc.v3.BodyResponse:

service.ext_proc.v3.BodyResponse
--------------------------------


:repo:`[service.ext_proc.v3.BodyResponse proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L253>`

This message must be sent in response to an HttpBody message.



.. code-block:: json
  :force:

  {
    "response": {...}
  }

.. _envoy_v3_api_field_service.ext_proc.v3.BodyResponse.response:


response
  (:ref:`service.ext_proc.v3.CommonResponse <envoy_v3_api_msg_service.ext_proc.v3.CommonResponse>`) 


.. _envoy_v3_api_msg_service.ext_proc.v3.CommonResponse:

service.ext_proc.v3.CommonResponse
----------------------------------


:repo:`[service.ext_proc.v3.CommonResponse proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L259>`

This message contains common fields between header and body responses.



.. code-block:: json
  :force:

  {
    "status": ...,
    "header_mutation": {...},
    "body_mutation": {...},
    "clear_route_cache": ...
  }

.. _envoy_v3_api_field_service.ext_proc.v3.CommonResponse.status:


status
  (:ref:`service.ext_proc.v3.CommonResponse.ResponseStatus <envoy_v3_api_enum_service.ext_proc.v3.CommonResponse.ResponseStatus>`) If set, provide additional direction on how the Envoy proxy should
  handle the rest of the HTTP filter chain.


.. _envoy_v3_api_field_service.ext_proc.v3.CommonResponse.header_mutation:


header_mutation
  (:ref:`service.ext_proc.v3.HeaderMutation <envoy_v3_api_msg_service.ext_proc.v3.HeaderMutation>`) Instructions on how to manipulate the headers. When responding to an
  HttpBody request, header mutations will only take effect if
  the current processing mode for the body is BUFFERED.


.. _envoy_v3_api_field_service.ext_proc.v3.CommonResponse.body_mutation:


body_mutation
  (:ref:`service.ext_proc.v3.BodyMutation <envoy_v3_api_msg_service.ext_proc.v3.BodyMutation>`) Replace the body of the last message sent to the remote server on this
  stream. If responding to an HttpBody request, simply replace or clear
  the body chunk that was sent with that request. Body mutations may take
  effect in response either to ``header`` or ``body`` messages. When it is
  in response to ``header`` messages, it only take effect if the
  :ref:`status <envoy_v3_api_field_service.ext_proc.v3.CommonResponse.status>`
  is set to CONTINUE_AND_REPLACE.


.. _envoy_v3_api_field_service.ext_proc.v3.CommonResponse.clear_route_cache:


clear_route_cache
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Clear the route cache for the current client request. This is necessary
  if the remote server modified headers that are used to calculate the route.
  This field is ignored in the response direction.


.. _envoy_v3_api_enum_service.ext_proc.v3.CommonResponse.ResponseStatus:

Enum service.ext_proc.v3.CommonResponse.ResponseStatus
------------------------------------------------------


:repo:`[service.ext_proc.v3.CommonResponse.ResponseStatus proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L260>`




.. _envoy_v3_api_enum_value_service.ext_proc.v3.CommonResponse.ResponseStatus.CONTINUE:


CONTINUE
  *(DEFAULT)* ⁣Apply the mutation instructions in this message to the
  request or response, and then continue processing the filter
  stream as normal. This is the default.


.. _envoy_v3_api_enum_value_service.ext_proc.v3.CommonResponse.ResponseStatus.CONTINUE_AND_REPLACE:


CONTINUE_AND_REPLACE
  ⁣Apply the specified header mutation, replace the body with the body
  specified in the body mutation (if present), and do not send any
  further messages for this request or response even if the processing
  mode is configured to do so.

  When used in response to a request_headers or response_headers message,
  this status makes it possible to either completely replace the body
  while discarding the original body, or to add a body to a message that
  formerly did not have one.

  In other words, this response makes it possible to turn an HTTP GET
  into a POST, PUT, or PATCH.




.. _envoy_v3_api_msg_service.ext_proc.v3.ImmediateResponse:

service.ext_proc.v3.ImmediateResponse
-------------------------------------


:repo:`[service.ext_proc.v3.ImmediateResponse proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L324>`

This message causes the filter to attempt to create a locally
generated response, send it  downstream, stop processing
additional filters, and ignore any additional messages received
from the remote server for this request or response. If a response
has already started, then  this will either ship the reply directly
to the downstream codec, or reset the stream.



.. code-block:: json
  :force:

  {
    "status": {...},
    "headers": {...},
    "body": ...,
    "grpc_status": {...},
    "details": ...
  }

.. _envoy_v3_api_field_service.ext_proc.v3.ImmediateResponse.status:


status
  (:ref:`type.v3.HttpStatus <envoy_v3_api_msg_type.v3.HttpStatus>`, *REQUIRED*) The response code to return


.. _envoy_v3_api_field_service.ext_proc.v3.ImmediateResponse.headers:


headers
  (:ref:`service.ext_proc.v3.HeaderMutation <envoy_v3_api_msg_service.ext_proc.v3.HeaderMutation>`) Apply changes to the default headers, which will include content-type.


.. _envoy_v3_api_field_service.ext_proc.v3.ImmediateResponse.body:


body
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) The message body to return with the response which is sent using the
  text/plain content type, or encoded in the grpc-message header.


.. _envoy_v3_api_field_service.ext_proc.v3.ImmediateResponse.grpc_status:


grpc_status
  (:ref:`service.ext_proc.v3.GrpcStatus <envoy_v3_api_msg_service.ext_proc.v3.GrpcStatus>`) If set, then include a gRPC status trailer.


.. _envoy_v3_api_field_service.ext_proc.v3.ImmediateResponse.details:


details
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) A string detailing why this local reply was sent, which may be included
  in log and debug output (e.g. this populates the %RESPONSE_CODE_DETAILS%
  command operator field for use in access logging).



.. _envoy_v3_api_msg_service.ext_proc.v3.GrpcStatus:

service.ext_proc.v3.GrpcStatus
------------------------------


:repo:`[service.ext_proc.v3.GrpcStatus proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L345>`

This message specifies a gRPC status for an ImmediateResponse message.



.. code-block:: json
  :force:

  {
    "status": ...
  }

.. _envoy_v3_api_field_service.ext_proc.v3.GrpcStatus.status:


status
  (`uint32 <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) The actual gRPC status



.. _envoy_v3_api_msg_service.ext_proc.v3.HeaderMutation:

service.ext_proc.v3.HeaderMutation
----------------------------------


:repo:`[service.ext_proc.v3.HeaderMutation proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L352>`

Change HTTP headers or trailers by appending, replacing, or removing
headers.



.. code-block:: json
  :force:

  {
    "set_headers": [],
    "remove_headers": []
  }

.. _envoy_v3_api_field_service.ext_proc.v3.HeaderMutation.set_headers:


set_headers
  (**repeated** :ref:`config.core.v3.HeaderValueOption <envoy_v3_api_msg_config.core.v3.HeaderValueOption>`) Add or replace HTTP headers. Attempts to set the value of
  any ``x-envoy`` header, and attempts to set the ``:method``,
  ``:authority``, ``:scheme``, or ``host`` headers will be ignored.
  The ``set_headers`` encoding is based on the runtime guard
  envoy_reloadable_features_send_header_raw_value setting.
  When it is true, the header value is encoded in the
  :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.
  When it is false, the header value is encoded in the
  :ref:`value <envoy_v3_api_field_config.core.v3.HeaderValue.value>` field.


.. _envoy_v3_api_field_service.ext_proc.v3.HeaderMutation.remove_headers:


remove_headers
  (**repeated** `string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Remove these HTTP headers. Attempts to remove system headers --
  any header starting with ``:``, plus ``host`` -- will be ignored.



.. _envoy_v3_api_msg_service.ext_proc.v3.BodyMutation:

service.ext_proc.v3.BodyMutation
--------------------------------


:repo:`[service.ext_proc.v3.BodyMutation proto] <api/envoy/service/ext_proc/v3/external_processor.proto#L371>`

Replace the entire message body chunk received in the corresponding
HttpBody message with this new body, or clear the body.



.. code-block:: json
  :force:

  {
    "body": ...,
    "clear_body": ...
  }

.. _envoy_v3_api_field_service.ext_proc.v3.BodyMutation.body:


body
  (`bytes <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) The entire body to replace


  

  Only one of :ref:`body <envoy_v3_api_field_service.ext_proc.v3.BodyMutation.body>`, :ref:`clear_body <envoy_v3_api_field_service.ext_proc.v3.BodyMutation.clear_body>` may be set.

.. _envoy_v3_api_field_service.ext_proc.v3.BodyMutation.clear_body:


clear_body
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Clear the corresponding body chunk


  

  Only one of :ref:`body <envoy_v3_api_field_service.ext_proc.v3.BodyMutation.body>`, :ref:`clear_body <envoy_v3_api_field_service.ext_proc.v3.BodyMutation.clear_body>` may be set.