package envoy.service.ext_proc.v3

Get desktop application:
View/edit binary Protocol Buffers messages

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 the message body in chunks, or the entire body at once. In either case, the server may send back a ProcessingResponse for each message it receives, or wait for certain amount of body chunks received before streams back the ProcessingResponse messages. 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.

• rpc Process (stream ProcessingRequest, stream ProcessingResponse)

  external_processor.proto:56

  This begins the bidirectional stream that Envoy will use to give the server control over what the filter does. The actual protocol is described by the ProcessingRequest and ProcessingResponse messages below.

  message ProcessingRequest

  external_processor.proto:85

  This represents the different types of messages that Envoy can send to an external processing server. [#next-free-field: 12]

  • oneof request

    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.

    • HttpHeaders request_headers = 2

      Information about the HTTP request headers, as well as peer info and additional properties. Unless ``observability_mode`` is ``true``, the server must send back a HeaderResponse message, an ImmediateResponse message, or close the stream.

    • HttpHeaders response_headers = 3

      Information about the HTTP response headers, as well as peer info and additional properties. Unless ``observability_mode`` is ``true``, the server must send back a HeaderResponse message or close the stream.

    • HttpBody request_body = 4

      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 response_body = 5

      A chunk of the HTTP response body. Unless ``observability_mode`` is ``true``, the server must send back a BodyResponse message or close the stream.

    • HttpTrailers request_trailers = 6

      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 response_trailers = 7

      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 the original upstream response has trailers.

  • optional config.core.v3.Metadata metadata_context = 8

    Dynamic metadata associated with the request.

  • map<string, google.protobuf.Struct> attributes = 9

    The values of properties selected by the ``request_attributes`` or ``response_attributes`` list in the configuration. Each entry in the list is populated from the standard :ref:`attributes <arch_overview_attributes>` supported across Envoy.

  • bool observability_mode = 10

    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.

  • optional ProtocolConfiguration protocol_config = 11

    Specify the filter protocol configurations to be sent to the server. ``protocol_config`` is only encoded in the first ``ProcessingRequest`` message from the client to the server.

  message ProcessingResponse

  external_processor.proto:166

  This represents the different types of messages the server may send back to Envoy when the ``observability_mode`` field in the received ProcessingRequest is set to false. * If the corresponding ``BodySendMode`` in the :ref:`processing_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.processing_mode>` is not set to ``FULL_DUPLEX_STREAMED``, then for every received ProcessingRequest, the server must send back exactly one ProcessingResponse message. * If it is set to ``FULL_DUPLEX_STREAMED``, the server must follow the API defined for this mode to send the ProcessingResponse messages. [#next-free-field: 11]

  • oneof response

    The response type that is sent by the server.

    • HeadersResponse request_headers = 1

      The server must send back this message in response to a message with the ``request_headers`` field set.

    • HeadersResponse response_headers = 2

      The server must send back this message in response to a message with the ``response_headers`` field set.

    • BodyResponse request_body = 3

      The server must send back this message in response to a message with the ``request_body`` field set.

    • BodyResponse response_body = 4

      The server must send back this message in response to a message with the ``response_body`` field set.

    • TrailersResponse request_trailers = 5

      The server must send back this message in response to a message with the ``request_trailers`` field set.

    • TrailersResponse response_trailers = 6

      The server must send back this message in response to a message with the ``response_trailers`` field set.

    • ImmediateResponse immediate_response = 7

      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.

  • optional google.protobuf.Struct dynamic_metadata = 8

    Optional metadata that will be emitted as dynamic metadata to be consumed by following filters. This metadata will be placed in the namespace(s) specified by the top-level field name(s) of the struct.

  • optional extensions.filters.http.ext_proc.v3.ProcessingMode mode_override = 9

    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, or :ref:`send_body_without_waiting_for_header_response <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.send_body_without_waiting_for_header_response>` is set to true.

  • optional google.protobuf.Duration override_message_timeout = 10

    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.

This message specifies the body mutation the server sends to Envoy.

Used in: CommonResponse

• oneof mutation

  The type of mutation for the body.

  • bytes body = 1

    The entire body to replace. Should only be used when the corresponding ``BodySendMode`` in the :ref:`processing_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.processing_mode>` is not set to ``FULL_DUPLEX_STREAMED``.

  • bool clear_body = 2

    Clear the corresponding body chunk. Should only be used when the corresponding ``BodySendMode`` in the :ref:`processing_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.processing_mode>` is not set to ``FULL_DUPLEX_STREAMED``. Clear the corresponding body chunk.

  • StreamedBodyResponse streamed_response = 3

    Must be used when the corresponding ``BodySendMode`` in the :ref:`processing_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.processing_mode>` is set to ``FULL_DUPLEX_STREAMED``.

This message is sent by the external server to Envoy after ``HttpBody`` was sent to it.

Used in: ProcessingResponse

• optional CommonResponse response = 1

  Details the modifications (if any) to be made by Envoy to the current request/response.

This message contains common fields between header and body responses. [#next-free-field: 6]

Used in: BodyResponse, HeadersResponse

• CommonResponse.ResponseStatus status = 1

  If set, provide additional direction on how the Envoy proxy should handle the rest of the HTTP filter chain.

• optional HeaderMutation header_mutation = 2

  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.

• optional BodyMutation body_mutation = 3

  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.

• optional config.core.v3.HeaderMap trailers = 4

  [#not-implemented-hide:] Add new trailers to the message. This may be used when responding to either a HttpHeaders or HttpBody message, but only if this message is returned along with the CONTINUE_AND_REPLACE status. The header value is encoded in the :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.

• bool clear_route_cache = 5

  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. This field is also ignored if the Envoy ext_proc filter is in the upstream filter chain.

The status of the response.

Used in: CommonResponse

• CONTINUE = 0

  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.

• CONTINUE_AND_REPLACE = 1

  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.

This message specifies a gRPC status for an ImmediateResponse message.

Used in: ImmediateResponse

• uint32 status = 1

  The actual gRPC status.

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

Used in: CommonResponse, ImmediateResponse, TrailersResponse

• repeated config.core.v3.HeaderValueOption set_headers = 1

  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 header value is encoded in the :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.

• repeated string remove_headers = 2

  Remove these HTTP headers. Attempts to remove system headers -- any header starting with ``:``, plus ``host`` -- will be ignored.

This message is sent by the external server to Envoy after ``HttpHeaders`` was sent to it.

Used in: ProcessingResponse

• optional CommonResponse response = 1

  Details the modifications (if any) to be made by Envoy to the current request/response.

This message is sent to the external server when the HTTP request and response bodies are received.

Used in: ProcessingRequest

• bytes body = 1

  The contents of the body in the HTTP request/response. Note that in streaming mode multiple ``HttpBody`` messages may be sent.

• bool end_of_stream = 2

  If ``true``, this will be the last ``HttpBody`` message that will be sent and no trailers will be sent for the current request/response.

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

Used in: ProcessingRequest

• optional config.core.v3.HeaderMap headers = 1

  The HTTP request headers. All header keys will be lower-cased, because HTTP header keys are case-insensitive. The header value is encoded in the :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.

• map<string, google.protobuf.Struct> attributes = 2

  [#not-implemented-hide:] This field is deprecated and not implemented. Attributes will be sent in the top-level :ref:`attributes <envoy_v3_api_field_service.ext_proc.v3.ProcessingRequest.attributes` field.

• bool end_of_stream = 3

  If ``true``, then there is no message body associated with this request or response.

This message is sent to the external server when the HTTP request and response trailers are received.

Used in: ProcessingRequest

• optional config.core.v3.HeaderMap trailers = 1

  The header value is encoded in the :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.

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. [#next-free-field: 6]

Used in: ProcessingResponse

• optional type.v3.HttpStatus status = 1

  The response code to return.

• optional HeaderMutation headers = 2

  Apply changes to the default headers, which will include content-type.

• bytes body = 3

  The message body to return with the response which is sent using the text/plain content type, or encoded in the grpc-message header.

• optional GrpcStatus grpc_status = 4

  If set, then include a gRPC status trailer.

• string details = 5

  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).

This message specifies the filter protocol configurations which will be sent to the ext_proc server in a :ref:`ProcessingRequest <envoy_v3_api_msg_service.ext_proc.v3.ProcessingRequest>`. If the server does not support these protocol configurations, it may choose to close the gRPC stream. If the server supports these protocol configurations, it should respond based on the API specifications.

Used in: ProcessingRequest

• extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode request_body_mode = 1

  Specify the filter configuration :ref:`request_body_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ProcessingMode.request_body_mode>`

• extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode response_body_mode = 2

  Specify the filter configuration :ref:`response_body_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ProcessingMode.response_body_mode>`

• bool send_body_without_waiting_for_header_response = 3

  Specify the filter configuration :ref:`send_body_without_waiting_for_header_response <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.send_body_without_waiting_for_header_response>` If the client is waiting for a header response from the server, setting ``true`` means the client will send body to the server as they arrive. Setting ``false`` means the client will buffer the arrived data and not send it to the server immediately.

The body response message corresponding to FULL_DUPLEX_STREAMED body mode.

Used in: BodyMutation

• bytes body = 1

  The body response chunk that will be passed to the upstream/downstream by Envoy.

• bool end_of_stream = 2

  The server sets this flag to true if it has received a body request with :ref:`end_of_stream <envoy_v3_api_field_service.ext_proc.v3.HttpBody.end_of_stream>` set to true, and this is the last chunk of body responses.

This message is sent by the external server to Envoy after ``HttpTrailers`` was sent to it.

Used in: ProcessingResponse

• optional HeaderMutation header_mutation = 1

  Details the modifications (if any) to be made by Envoy to the current request/response trailers.