External processing service (proto)

service.ext_proc.v3.ProtocolConfiguration

[service.ext_proc.v3.ProtocolConfiguration proto]

This message specifies the filter protocol configurations which will be sent to the ext_proc server in a 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.

{
  "request_body_mode": ...,
  "response_body_mode": ...,
  "send_body_without_waiting_for_header_response": ...
}

request_body_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode) Specifies the filter configuration request_body_mode.

response_body_mode

(extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode) Specifies the filter configuration response_body_mode.

send_body_without_waiting_for_header_response

(bool) Specifies the filter configuration send_body_without_waiting_for_header_response. If the client is waiting for a header response from the server, setting to true means the client will send the body to the server as it arrives. Setting to false means the client will buffer the arrived data and not send it to the server immediately.

service.ext_proc.v3.ProcessingRequest

[service.ext_proc.v3.ProcessingRequest proto]

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

{
  "request_headers": {...},
  "response_headers": {...},
  "request_body": {...},
  "response_body": {...},
  "request_trailers": {...},
  "response_trailers": {...},
  "metadata_context": {...},
  "attributes": {...},
  "observability_mode": ...,
  "protocol_config": {...}
}

request_headers

(service.ext_proc.v3.HttpHeaders) 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.

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

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

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.v3.HttpBody) A chunk of the HTTP response body. Unless observability_mode is true, 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.v3.HttpTrailers) 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.

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

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.

metadata_context

(config.core.v3.Metadata) Dynamic metadata associated with the request.

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 in the data plane.

observability_mode

(bool) Specifies whether the filter that sent this request is running in observability_mode.

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

Defaults to false.

protocol_config

(service.ext_proc.v3.ProtocolConfiguration) 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.

service.ext_proc.v3.ProcessingResponse

[service.ext_proc.v3.ProcessingResponse proto]

This represents the different types of messages the server may send back to the data plane when the observability_mode field in the received ProcessingRequest is set to false.

• If the corresponding BodySendMode in the 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.

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

request_headers

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

The response type that is sent by the server.

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

response_headers

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

The response type that is sent by the server.

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

request_body

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

The response type that is sent by the server.

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

response_body

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

The response type that is sent by the server.

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

request_trailers

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

The response type that is sent by the server.

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

response_trailers

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

The response type that is sent by the server.

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

immediate_response

(service.ext_proc.v3.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.

The response type that is sent by the server.

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

streamed_immediate_response

(service.ext_proc.v3.StreamedImmediateResponse) The server sends back this message to initiate or continue local response streaming. The server must initiate local response streaming with the headers_response in response to a ProcessingRequest with the request_headers only. The server may follow up with multiple messages containing body_response. The server must indicate end of stream by setting end_of_stream to true in the headers_response or body_response message or by sending a trailers_response message. The client may send a request_body or request_trailers to the server depending on configuration. The streaming local response can only be sent when the request_header_mode in the filter processing_mode is set to SEND. The ext_proc server should not send StreamedImmediateResponse if it did not observe request headers, as it will result in a race with the upstream server response and reset of the client request. Presently only the FULL_DUPLEX_STREAMED or NONE body modes are supported.

The response type that is sent by the server.

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

dynamic_metadata

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

mode_override

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

This field is only applicable when servers are responding to the header requests. If it is set in the response to the body or trailer requests, it will be ignored by the data plane. It is also ignored by the data plane when the ext_proc filter config allow_mode_override is set to false, or send_body_without_waiting_for_header_response is set to true.

override_message_timeout

(Duration) When the ext_proc server receives a request message and needs more time to process it, it sends back a ProcessingResponse message with a new timeout value. When the data plane receives this response message, it ignores other fields in the response, stops the original timer (which has the timeout value specified in message_timeout), and starts a new timer with this override_message_timeout value while keeping the data plane ext_proc filter state machine intact.

The value must be >= 1ms and <= max_message_timeout. Such a message can be sent at most once in a particular data plane ext_proc filter processing state. To enable this API, max_message_timeout must be set to a value >= 1ms.

service.ext_proc.v3.HttpHeaders

[service.ext_proc.v3.HttpHeaders proto]

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

{
  "headers": {...},
  "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. The header value is encoded in the raw_value field.

end_of_stream

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

service.ext_proc.v3.HttpBody

[service.ext_proc.v3.HttpBody proto]

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

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

body

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

In GRPC body send mode, a separate HttpBody message will be sent for each message in the gRPC stream.

end_of_stream

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

end_of_stream_without_message

(bool) This field is used in GRPC body send mode when end_of_stream is true and body is empty. Those values would normally indicate an empty message on the stream with the end-of-stream bit set. However, if the half-close happens after the last message on the stream was already sent, then this field will be true to indicate an end-of-stream with no message (as opposed to an empty message).

grpc_message_compressed

(bool) This field is used in GRPC body send mode to indicate whether the message is compressed. This will never be set to true by gRPC but may be set to true by a proxy like Envoy.

service.ext_proc.v3.HttpTrailers

[service.ext_proc.v3.HttpTrailers proto]

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

{
  "trailers": {...}
}

trailers

(config.core.v3.HeaderMap) The header value is encoded in the raw_value field.

service.ext_proc.v3.HeadersResponse

[service.ext_proc.v3.HeadersResponse proto]

This message is sent by the external server to the data plane after HttpHeaders was sent to it.

{
  "response": {...}
}

response

(service.ext_proc.v3.CommonResponse) Details the modifications (if any) to be made by the data plane to the current request/response.

service.ext_proc.v3.BodyResponse

[service.ext_proc.v3.BodyResponse proto]

This message is sent by the external server to the data plane after HttpBody was sent to it.

{
  "response": {...}
}

response

(service.ext_proc.v3.CommonResponse) Details the modifications (if any) to be made by the data plane to the current request/response.

service.ext_proc.v3.TrailersResponse

[service.ext_proc.v3.TrailersResponse proto]

This message is sent by the external server to the data plane after HttpTrailers was sent to it.

{
  "header_mutation": {...}
}

header_mutation

(service.ext_proc.v3.HeaderMutation) Details the modifications (if any) to be made by the data plane to the current request/response trailers.

service.ext_proc.v3.StreamedImmediateResponse

[service.ext_proc.v3.StreamedImmediateResponse proto]

This message is sent by the external server to the data plane after HttpHeaders to initiate local response streaming. The server may follow up with multiple messages containing body_response. The server must indicate end of stream by setting end_of_stream to true in the headers_response or body_response message or by sending a trailers_response message.

{
  "headers_response": {...},
  "body_response": {...},
  "trailers_response": {...}
}

headers_response

(service.ext_proc.v3.HttpHeaders) Response headers to be sent downstream. The :status header must be set.

Only one of headers_response, body_response, trailers_response may be set.

body_response

(service.ext_proc.v3.StreamedBodyResponse) Response body to be sent downstream.

Only one of headers_response, body_response, trailers_response may be set.

trailers_response

(config.core.v3.HeaderMap) Response trailers to be sent downstream.

Only one of headers_response, body_response, trailers_response may be set.

service.ext_proc.v3.CommonResponse

[service.ext_proc.v3.CommonResponse proto]

This message contains common fields between header and body responses.

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

status

(service.ext_proc.v3.CommonResponse.ResponseStatus) If set, provide additional direction on how the data plane should handle the rest of the HTTP filter chain.

header_mutation

(service.ext_proc.v3.HeaderMutation) 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.

body_mutation

(service.ext_proc.v3.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. Body mutations may take effect in response either to header or body messages. When it is in response to header messages, it only takes effect if the status is set to CONTINUE_AND_REPLACE.

clear_route_cache

(bool) 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 data plane ext_proc filter is in the upstream filter chain.

Enum service.ext_proc.v3.CommonResponse.ResponseStatus

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

The status of the response.

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

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

Not supported if the body send mode is GRPC.

service.ext_proc.v3.ImmediateResponse

[service.ext_proc.v3.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.v3.HeaderMutation) Apply changes to the default headers, which will include content-type.

body

(bytes) 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.v3.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 (e.g., this populates the %RESPONSE_CODE_DETAILS% command operator field for use in access logging).

service.ext_proc.v3.GrpcStatus

[service.ext_proc.v3.GrpcStatus proto]

This message specifies a gRPC status for an ImmediateResponse message.

{
  "status": ...
}

status

(uint32) The actual gRPC status.

service.ext_proc.v3.HeaderMutation

[service.ext_proc.v3.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. The header value is encoded in the raw_value field.

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.v3.StreamedBodyResponse

[service.ext_proc.v3.StreamedBodyResponse proto]

The body response message corresponding to FULL_DUPLEX_STREAMED or GRPC body modes.

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

body

(bytes) In FULL_DUPLEX_STREAMED body send mode, contains the body response chunk that will be passed to the upstream/downstream by the data plane. In GRPC body send mode, contains a serialized gRPC message to be passed to the upstream/downstream by the data plane.

end_of_stream

(bool) The server sets this flag to true if it has received a body request with end_of_stream set to true, and this is the last chunk of body responses.

Note that in GRPC body send mode, this allows the ext_proc server to tell the data plane to send a half close after a client message, which will result in discarding any other messages sent by the client application.

end_of_stream_without_message

(bool) This field is used in GRPC body send mode when end_of_stream is true and body is empty. Those values would normally indicate an empty message on the stream with the end-of-stream bit set. However, if the half-close happens after the last message on the stream was already sent, then this field will be true to indicate an end-of-stream with no message (as opposed to an empty message).

grpc_message_compressed

(bool) This field is used in GRPC body send mode to indicate whether the message is compressed. This will never be set to true by gRPC but may be set to true by a proxy like Envoy.

service.ext_proc.v3.BodyMutation

[service.ext_proc.v3.BodyMutation proto]

This message specifies the body mutation the server sends to the data plane.

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

body

(bytes) The entire body to replace. Should only be used when the corresponding BodySendMode in the processing_mode is not set to FULL_DUPLEX_STREAMED or GRPC.

The type of mutation for the body.

Only one of body, clear_body, streamed_response may be set.

clear_body

(bool) Clear the corresponding body chunk. Should only be used when the corresponding BodySendMode in the processing_mode is not set to FULL_DUPLEX_STREAMED or GRPC.

The type of mutation for the body.

Only one of body, clear_body, streamed_response may be set.

streamed_response

(service.ext_proc.v3.StreamedBodyResponse) Must be used when the corresponding BodySendMode in the processing_mode is set to FULL_DUPLEX_STREAMED or GRPC.

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

The type of mutation for the body.

Only one of body, clear_body, streamed_response may be set.