External Processing Filter (proto)

This extension has the qualified name envoy.filters.http.ext_proc

Note

This extension is intended to be robust against both untrusted downstream and upstream traffic.

Tip

This extension extends and can be used with the following extension categories:

This extension must be configured with one of the following type URLs:

External Processing Filter Processing Mode

This configuration describes which parts of an HTTP request and response are sent to a remote server and how they are delivered.

extensions.filters.http.ext_proc.v3.ProcessingMode

[extensions.filters.http.ext_proc.v3.ProcessingMode proto]

{
  "request_header_mode": ...,
  "response_header_mode": ...,
  "request_body_mode": ...,
  "response_body_mode": ...,
  "request_trailer_mode": ...,
  "response_trailer_mode": ...
}

request_header_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.HeaderSendMode) How to handle the request header.

Note

This field is ignored in mode_override, since mode overrides can only affect messages exchanged after the request header is processed.

Defaults to SEND.

response_header_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.HeaderSendMode) How to handle the response header.

Defaults to SEND.

request_body_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode) How to handle the request body.

Defaults to NONE.

response_body_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode) How to handle the response body.

Defaults to NONE.

request_trailer_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.HeaderSendMode) How to handle the request trailers.

Defaults to SKIP.

response_trailer_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.HeaderSendMode) How to handle the response trailers.

Defaults to SKIP.

Enum extensions.filters.http.ext_proc.v3.ProcessingMode.HeaderSendMode

[extensions.filters.http.ext_proc.v3.ProcessingMode.HeaderSendMode proto]

Control how headers and trailers are handled.

DEFAULT

(DEFAULT) ⁣When used to configure the ext_proc filter processing_mode, the default HeaderSendMode depends on which part of the message is being processed. By default, request and response headers are sent, while trailers are skipped.

When used in mode_override or allowed_override_modes, a value of DEFAULT indicates that there is no change from the behavior that is configured for the filter in processing_mode.

SEND: ⁣Send the header or trailer.

SKIP: ⁣Do not send the header or trailer.

Enum extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode

[extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode proto]

Control how the request and response bodies are handled.

When body mutation by the external processor is enabled, the ext_proc filter will always remove the content length header in the following four cases, unless allow_content_length_header is enabled. This is because the content length cannot be guaranteed to be set correctly:

STREAMED BodySendMode: header processing completes before body mutation comes back.
BUFFERED_PARTIAL BodySendMode: body is buffered and could be injected in different phases.
BUFFERED BodySendMode + SKIP HeaderSendMode: header processing (e.g., update content-length) is skipped.
FULL_DUPLEX_STREAMED BodySendMode: header processing completes before body mutation comes back.

In Envoy’s HTTP/1 codec implementation, removing content length will enable chunked transfer encoding whenever feasible. The recipient (either client or server) must be able to parse and decode the chunked transfer coding (see details in RFC9112).

In BUFFERED BodySendMode + SEND HeaderSendMode, content length header is allowed but it is the external processor’s responsibility to set the content length correctly matched to the length of the mutated body. If they don’t match, the corresponding body mutation will be rejected and a local reply will be sent with an error message.

NONE: (DEFAULT) ⁣Do not send the body at all. This is the default.

STREAMED: ⁣Stream the body to the server in pieces as they are seen.

BUFFERED: ⁣Buffer the message body in memory and send the entire body at once. If the body exceeds the configured buffer limit, then the downstream system will receive an error.

BUFFERED_PARTIAL: ⁣Buffer the message body in memory and send the entire body in one chunk. If the body exceeds the configured buffer limit, then the body contents up to the buffer limit will be sent.

FULL_DUPLEX_STREAMED

⁣The ext_proc client (the data plane) streams the body to the server in pieces as they arrive.

The server may choose to buffer any number of chunks of data before processing them. After it finishes buffering, the server processes the buffered data. Then it splits the processed data into any number of chunks, and streams them back to the ext_proc client one by one. The server may continuously do so until the complete body is processed. The individual response chunk size is recommended to be no greater than 64K bytes, or max_receive_message_length if EnvoyGrpc is used.
The server may also choose to buffer the entire message, including the headers (if header mode is SEND), the entire body, and the trailers (if present), before sending back any response. The server response has to maintain the headers-body-trailers ordering.
Note that the server might also choose not to buffer data. That is, upon receiving a body request, it could process the data and send back a body response immediately.

In this body mode:

The corresponding trailer mode has to be set to SEND.
The client will send body and trailers (if present) to the server as they arrive. Sending the trailers (if present) is to inform the server that the complete body has arrived. In case there are no trailers, then the client will set end_of_stream to true as part of the last body chunk request to notify the server that no other data is to be sent.
The server needs to send StreamedBodyResponse to the client in the body response.
The client will stream the body chunks in the responses from the server to the upstream/downstream as they arrive.