External Processing Service

Warning

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

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.

service.ext_proc.v3alpha.ProcessingRequest

[service.ext_proc.v3alpha.ProcessingRequest proto]

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

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

(bool) Specify whether the filter that sent this request is running in synchronous or asynchronous mode. If false, then the server must either respond with exactly one ProcessingResponse message or close the stream. If true, however, then the server must not respond with an additional message, although it may still close the stream. The choice of synchronous or asynchronous mode can be chosen in the filter configuration.

request_headers

(service.ext_proc.v3alpha.HttpHeaders) Information about the HTTP request headers, as well as peer info and additional properties. If “response_required” is set, 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 request_headers, response_headers, request_body, response_body, request_trailers, response_trailers must be set.

response_headers

(service.ext_proc.v3alpha.HttpHeaders) Information about the HTTP response headers, as well as peer info and additional properties. If “response_required” is set, 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 request_headers, response_headers, request_body, response_body, request_trailers, response_trailers must be set.

request_body

(service.ext_proc.v3alpha.HttpBody) A chunk of the HTTP request body. If “response_required” is set, 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 request_headers, response_headers, request_body, response_body, request_trailers, response_trailers must be set.

response_body

(service.ext_proc.v3alpha.HttpBody) A chunk of the HTTP request body. If “response_required” is set, 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 request_headers, response_headers, request_body, response_body, request_trailers, response_trailers must be set.

request_trailers

(service.ext_proc.v3alpha.HttpTrailers) The HTTP trailers for the request path. If “response_required” is set, the server must send back a TrailerResponse 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 request_headers, response_headers, request_body, response_body, request_trailers, response_trailers must be set.

response_trailers

(service.ext_proc.v3alpha.HttpTrailers) The HTTP trailers for the response path. If “response_required” is set, the server must send back a TrailerResponse 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 request_headers, response_headers, request_body, response_body, request_trailers, response_trailers must be set.

service.ext_proc.v3alpha.ProcessingResponse

[service.ext_proc.v3alpha.ProcessingResponse proto]

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

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

(service.ext_proc.v3alpha.HeadersResponse) The server must send back this message in response to a message with the “request_headers” field set.

Precisely one of request_headers, response_headers, request_body, response_body, request_trailers, response_trailers, immediate_response must be set.

response_headers

(service.ext_proc.v3alpha.HeadersResponse) The server must send back this message in response to a message with the “response_headers” field set.

Precisely one of request_headers, response_headers, request_body, response_body, request_trailers, response_trailers, immediate_response must be set.

request_body

(service.ext_proc.v3alpha.BodyResponse) The server must send back this message in response to a message with the “request_body” field set.

Precisely one of request_headers, response_headers, request_body, response_body, request_trailers, response_trailers, immediate_response must be set.

response_body

(service.ext_proc.v3alpha.BodyResponse) The server must send back this message in response to a message with the “response_body” field set.

Precisely one of request_headers, response_headers, request_body, response_body, request_trailers, response_trailers, immediate_response must be set.

request_trailers

(service.ext_proc.v3alpha.TrailersResponse) The server must send back this message in response to a message with the “request_trailers” field set.

Precisely one of request_headers, response_headers, request_body, response_body, request_trailers, response_trailers, immediate_response must be set.

response_trailers

(service.ext_proc.v3alpha.TrailersResponse) The server must send back this message in response to a message with the “response_trailers” field set.

Precisely one of request_headers, response_headers, request_body, response_body, request_trailers, response_trailers, immediate_response must be set.

immediate_response

(service.ext_proc.v3alpha.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 request_headers, response_headers, request_body, response_body, request_trailers, response_trailers, immediate_response must be set.

dynamic_metadata

(Struct) Optional metadata that will be emitted as dynamic metadata to be consumed by the next filter. This metadata will be placed in the namespace “envoy.filters.http.ext_proc”.

mode_override

(extensions.filters.http.ext_proc.v3alpha.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.

service.ext_proc.v3alpha.HttpHeaders

[service.ext_proc.v3alpha.HttpHeaders proto]

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

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

(config.core.v3.HeaderMap) The HTTP request headers. All header keys will be lower-cased, because HTTP header keys are case-insensitive.

attributes

(repeated map<string, Struct>) 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 attributes supported across Envoy.

end_of_stream

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

service.ext_proc.v3alpha.HttpBody

[service.ext_proc.v3alpha.HttpBody proto]

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

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

(bytes)

end_of_stream

(bool)

service.ext_proc.v3alpha.HttpTrailers

[service.ext_proc.v3alpha.HttpTrailers proto]

This message contains the trailers.

{
  "trailers": "{...}"
}
trailers

(config.core.v3.HeaderMap)

service.ext_proc.v3alpha.HeadersResponse

[service.ext_proc.v3alpha.HeadersResponse proto]

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

{
  "response": "{...}"
}
response

(service.ext_proc.v3alpha.CommonResponse)

service.ext_proc.v3alpha.TrailersResponse

[service.ext_proc.v3alpha.TrailersResponse proto]

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

{
  "header_mutation": "{...}"
}
header_mutation

(service.ext_proc.v3alpha.HeaderMutation) Instructions on how to manipulate the trailers

service.ext_proc.v3alpha.BodyResponse

[service.ext_proc.v3alpha.BodyResponse proto]

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

{
  "response": "{...}"
}
response

(service.ext_proc.v3alpha.CommonResponse)

service.ext_proc.v3alpha.CommonResponse

[service.ext_proc.v3alpha.CommonResponse proto]

This message contains common fields between header and body responses.

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

(service.ext_proc.v3alpha.CommonResponse.ResponseStatus) If set, provide additional direction on how the Envoy proxy should handle the rest of the HTTP filter chain.

header_mutation

(service.ext_proc.v3alpha.HeaderMutation) Instructions on how to manipulate the headers. When responding to an HttpBody request, header mutations will only take effect if the headers were not already sent further on the filter chain, which happens only if the current processing mode for the body is BUFFERED or BUFFERED_PARTIAL.

body_mutation

(service.ext_proc.v3alpha.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. If responding to an HttpHeaders request, then a new body may be added to the request if this message is returned along with the CONTINUE_AND_REPLACE status.

trailers

(config.core.v3.HeaderMap) 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.

clear_route_cache

(bool) Clear the route cache for the current request. This is necessary if the remote server modified headers that are used to calculate the route.

Enum service.ext_proc.v3alpha.CommonResponse.ResponseStatus

[service.ext_proc.v3alpha.CommonResponse.ResponseStatus proto]

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.

CONTINUE_AND_REPLACE

⁣Replace the request or response with the contents of this message. If header_mutation is set, apply it to the headers. If body_mutation is set and contains a body, then add that body to the request or response, even if one does not already exist – otherwise, clear the body. Any additional body and trailers received from downstream or upstream will be ignored. This can be used to add a body to a request or response that does not have one already.

service.ext_proc.v3alpha.ImmediateResponse

[service.ext_proc.v3alpha.ImmediateResponse proto]

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.

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

(type.v3.HttpStatus, REQUIRED) The response code to return

headers

(service.ext_proc.v3alpha.HeaderMutation) Apply changes to the default headers, which will include content-type.

body

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

grpc_status

(service.ext_proc.v3alpha.GrpcStatus) If set, then include a gRPC status trailer.

details

(string) A string detailing why this local reply was sent, which may be included in log and debug output.

service.ext_proc.v3alpha.GrpcStatus

[service.ext_proc.v3alpha.GrpcStatus proto]

This message specifies a gRPC status for an ImmediateResponse message.

{
  "status": "..."
}
status

(uint32) The actual gRPC status

service.ext_proc.v3alpha.HeaderMutation

[service.ext_proc.v3alpha.HeaderMutation proto]

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

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

(repeated 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.

remove_headers

(repeated string) Remove these HTTP headers. Attempts to remove system headers – any header starting with “:”, plus “host” – will be ignored.

service.ext_proc.v3alpha.BodyMutation

[service.ext_proc.v3alpha.BodyMutation proto]

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

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

(bytes) The entire body to replace

Only one of body, clear_body may be set.

clear_body

(bool) Clear the corresponding body chunk

Only one of body, clear_body may be set.