External Processing Filter (proto)

This extension has 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:

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

External Processing Filter

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

Current Implementation Status: All options and processing modes are implemented except for the following:

  • Request and response attributes are not sent and not processed.

  • Dynamic metadata in responses from the external processor is ignored.

  • “async mode” is not implemented.

extensions.filters.http.ext_proc.v3.ExternalProcessor

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

The filter communicates with an external gRPC service called an “external processor” that can 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.

  • To modify request or response trailers if they already exist

The filter supports up to six different processing steps. Each is represented by a gRPC stream message that is sent to the external processor. For each message, the processor must send a matching response.

  • Request headers: Contains the headers from the original HTTP request.

  • Request body: Delivered if they are present and sent in a single message if the BUFFERED or BUFFERED_PARTIAL mode is chosen, in multiple messages if the STREAMED mode is chosen, and not at all otherwise.

  • Request trailers: Delivered if they are present and if the trailer mode is set to SEND.

  • Response headers: Contains the headers from the HTTP response. Keep in mind that if the upstream system sends them before processing the request body that this message may arrive before the complete body.

  • Response body: Sent according to the processing mode like the request body.

  • Response trailers: Delivered according to the processing mode like the request trailers.

By default, the processor sends only the request and response headers messages. This may be changed to include any of the six steps by changing the processing_mode setting of the filter configuration, or by setting the mode_override of any response from the external processor. The latter is only enabled if allow_mode_override is set to true. This way, a processor may, for example, use information in the request header to determine whether the message body must be examined, or whether the proxy should simply stream it straight through.

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.

Stats about each gRPC call are recorded in a dynamic filter state object in a namespace matching the filter name.

{
  "grpc_service": {...},
  "failure_mode_allow": ...,
  "processing_mode": {...},
  "message_timeout": {...},
  "stat_prefix": ...,
  "mutation_rules": {...},
  "max_message_timeout": {...},
  "disable_clear_route_cache": ...,
  "forward_rules": {...},
  "filter_metadata": {...},
  "allow_mode_override": ...,
  "disable_immediate_response": ...
}
grpc_service

(config.core.v3.GrpcService, REQUIRED) 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.v3.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. Zero is a valid config which means the timer will be triggered immediately. If not configured, default is 200 milliseconds.

stat_prefix

(string) Optional additional prefix to use when emitting statistics. This allows to distinguish emitted statistics between configured ext_proc filters in an HTTP filter chain.

mutation_rules

(config.common.mutation_rules.v3.HeaderMutationRules) Rules that determine what modifications an external processing server may make to message headers. If not set, all headers may be modified except for “host”, “:authority”, “:scheme”, “:method”, and headers that start with the header prefix set via header_prefix (which is usually “x-envoy”). Note that changing headers such as “host” or “:authority” may not in itself change Envoy’s routing decision, as routes can be cached. To also force the route to be recomputed, set the clear_route_cache field to true in the same response.

max_message_timeout

(Duration) Specify the upper bound of override_message_timeout If not specified, by default it is 0, which will effectively disable the override_message_timeout API.

disable_clear_route_cache

(bool) Prevents clearing the route-cache when the clear_route_cache field is set in an external processor response.

forward_rules

(extensions.filters.http.ext_proc.v3.HeaderForwardingRules) Allow headers matching the forward_rules to be forwarded to the external processing server. If not set, all headers are forwarded to the external processing server.

filter_metadata

(Struct) Additional metadata to be added to the filter state for logging purposes. The metadata will be added to StreamInfo’s filter state under the namespace corresponding to the ext_proc filter name.

allow_mode_override

(bool) If allow_mode_override is set to true, the filter config processing_mode can be overridden by the response message from the external processing server mode_override. If not set, mode_override API in the response message will be ignored.

disable_immediate_response

(bool) If set to true, ignore the immediate_response message in an external processor response. In such case, no local reply will be sent. Instead, the stream to the external processor will be closed. There will be no more external processing for this stream from now on.

extensions.filters.http.ext_proc.v3.HeaderForwardingRules

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

The HeaderForwardingRules structure specifies what headers are allowed to be forwarded to the external processing server.

This works as below:

  1. If neither allowed_headers nor disallowed_headers is set, all headers are forwarded.

  2. If both allowed_headers and disallowed_headers are set, only headers in the allowed_headers but not in the disallowed_headers are forwarded.

  3. If allowed_headers is set, and disallowed_headers is not set, only headers in the allowed_headers are forwarded.

  4. If disallowed_headers is set, and allowed_headers is not set, all headers except headers in the disallowed_headers are forwarded.

{
  "allowed_headers": {...},
  "disallowed_headers": {...}
}
allowed_headers

(type.matcher.v3.ListStringMatcher) If set, specifically allow any header in this list to be forwarded to the external processing server. This can be overridden by the below disallowed_headers.

disallowed_headers

(type.matcher.v3.ListStringMatcher) If set, specifically disallow any header in this list to be forwarded to the external processing server. This overrides the above allowed_headers if a header matches both.

extensions.filters.http.ext_proc.v3.ExtProcPerRoute

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

Extra settings that may be added to per-route configuration for a virtual host or cluster.

{
  "disabled": ...,
  "overrides": {...}
}
disabled

(bool) Disable the filter for this particular vhost or route. If disabled is specified in multiple per-filter-configs, the most specific one will be used.

Precisely one of disabled, overrides must be set.

overrides

(extensions.filters.http.ext_proc.v3.ExtProcOverrides) Override aspects of the configuration for this route. A set of overrides in a more specific configuration will override a “disabled” flag set in a less-specific one.

Precisely one of disabled, overrides must be set.

extensions.filters.http.ext_proc.v3.ExtProcOverrides

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

Overrides that may be set on a per-route basis

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

(extensions.filters.http.ext_proc.v3.ProcessingMode) Set a different processing mode for this route than the default.

grpc_service

(config.core.v3.GrpcService) Set a different gRPC service for this route than the default.