External Processing Filter

This extension may be referenced by the qualified name envoy.filters.http.ext_proc

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

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

Warning

This API is work-in-progress and is subject to breaking changes.

External Processing Filter

The External Processing filter allows an external service to act on HTTP traffic in a flexible way.

Current Implementation Status: The filter will send the “request_headers” and “response_headers” messages by default. In addition, if the “processing mode” is set , the “request_body” and “response_body” messages will be sent if the corresponding fields of the “processing_mode” are set to BUFFERED. The other body processing modes, and trailer processing, are not implemented yet. The filter will also respond to “immediate_response” messages at any point in the stream.

As designed, the filter supports up to six different processing steps, which are in the process of being implemented: * Request headers: IMPLEMENTED * Request body: Only BUFFERED mode is implemented * Request trailers: NOT IMPLEMENTED * Response headers: IMPLEMENTED * Response body: Only BUFFERED mode is implemented * Response trailers: NOT IMPLEMENTED

The filter communicates with an external gRPC service that can use it to do a variety of things with the request and response:

  • Access and modify the HTTP headers on the request, response, or both

  • Access and modify the HTTP request and response bodies

  • Access and modify the dynamic stream metadata

  • Immediately send an HTTP response downstream and terminate other processing

The filter communicates with the server using a gRPC bidirectional stream. After the initial request, the external server is in control over what additional data is sent to it and how it should be processed.

By implementing the protocol specified by the stream, the external server can choose:

  • Whether it receives the response message at all

  • Whether it receives the message body at all, in separate chunks, or as a single buffer

  • Whether subsequent HTTP requests are transmitted synchronously or whether they are sent asynchronously.

All of this together allows a server to process the filter traffic in fairly sophisticated ways. For example:

  • A server may choose to examine all or part of the HTTP message bodies depending on the content of the headers.

  • A server may choose to immediately reject some messages based on their HTTP headers (or other dynamic metadata) and more carefully examine others

  • A server may asynchronously monitor traffic coming through the filter by inspecting headers, bodies, or both, and then decide to switch to a synchronous processing mode, either permanently or temporarily.

The protocol itself is based on a bidirectional gRPC stream. Envoy will send the server ProcessingRequest messages, and the server must reply with ProcessingResponse.

extensions.filters.http.ext_proc.v3alpha.ExternalProcessor

[extensions.filters.http.ext_proc.v3alpha.ExternalProcessor proto]

{
  "grpc_service": "{...}",
  "failure_mode_allow": "...",
  "processing_mode": "{...}",
  "message_timeout": "{...}"
}
grpc_service

(config.core.v3.GrpcService) Configuration for the gRPC service that the filter will communicate with. The filter supports both the “Envoy” and “Google” gRPC clients.

failure_mode_allow

(bool) By default, if the gRPC stream cannot be established, or if it is closed prematurely with an error, the filter will fail. Specifically, if the response headers have not yet been delivered, then it will return a 500 error downstream. If they have been delivered, then instead the HTTP stream to the downstream client will be reset. With this parameter set to true, however, then if the gRPC stream is prematurely closed or could not be opened, processing continues without error.

processing_mode

(extensions.filters.http.ext_proc.v3alpha.ProcessingMode) Specifies default options for how HTTP headers, trailers, and bodies are sent. See ProcessingMode for details.

message_timeout

(Duration) Specifies the timeout for each individual message sent on the stream and when the filter is running in synchronous mode. Whenever the proxy sends a message on the stream that requires a response, it will reset this timer, and will stop processing and return an error (subject to the processing mode) if the timer expires before a matching response. is received. There is no timeout when the filter is running in asynchronous mode. Default is 200 milliseconds.