Chiebot-Mirror
/
data-plane-api
mirror of https://github.com/envoyproxy/data-plane-api.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

External processing filter protos (#13893)

Browse Source 
This introduces a new filter called the "external processing filter." It is intended to allow an external service to be able to operate as if it were part of the filter chain using a gRPC stream. It is intended to support a variety of use cases in which processing of HTTP requests and responses by an external service is desired.

A document that describes the filter can be found here:

https://docs.google.com/document/d/1IZqm5IUnG9gc2VqwGaN5C2TZAD9_QbsY9Vvy5vr9Zmw/edit#heading=h.3zlthggr9vvv

Signed-off-by: Gregory Brail <gregbrail@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 98d2f3b553b87c3e935f57ba15b4faf68b45d7f0
pull/623/head
data-plane-api(Azure Pipelines) 4 years ago
parent ffdd5ee6fe
commit eab2d5c7dd
7 changed files with 564 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 2
      BUILD
  2. 12
      envoy/extensions/filters/http/ext_proc/v3alpha/BUILD
  3. 150
      envoy/extensions/filters/http/ext_proc/v3alpha/ext_proc.proto
  4. 74
      envoy/extensions/filters/http/ext_proc/v3alpha/processing_mode.proto
  5. 15
      envoy/service/ext_proc/v3alpha/BUILD
  6. 309
      envoy/service/ext_proc/v3alpha/external_processor.proto
  7. 2
      versioning/BUILD

2
BUILD
Unescape View File

@ -179,6 +179,7 @@ proto_library(
"//envoy/extensions/filters/http/dynamic_forward_proxy/v3:pkg",
"//envoy/extensions/filters/http/dynamo/v3:pkg",
"//envoy/extensions/filters/http/ext_authz/v3:pkg",
"//envoy/extensions/filters/http/ext_proc/v3alpha:pkg",
"//envoy/extensions/filters/http/fault/v3:pkg",
"//envoy/extensions/filters/http/grpc_http1_bridge/v3:pkg",
"//envoy/extensions/filters/http/grpc_http1_reverse_bridge/v3:pkg",
@ -258,6 +259,7 @@ proto_library(
"//envoy/service/discovery/v3:pkg",
"//envoy/service/endpoint/v3:pkg",
"//envoy/service/event_reporting/v3:pkg",
"//envoy/service/ext_proc/v3alpha:pkg",
"//envoy/service/extension/v3:pkg",
"//envoy/service/health/v3:pkg",
"//envoy/service/listener/v3:pkg",

12
envoy/extensions/filters/http/ext_proc/v3alpha/BUILD
Unescape View File

@ -0,0 +1,12 @@
# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
licenses(["notice"]) # Apache 2
api_proto_package(
deps = [
"//envoy/config/core/v3:pkg",
"@com_github_cncf_udpa//udpa/annotations:pkg",
],
)

150
envoy/extensions/filters/http/ext_proc/v3alpha/ext_proc.proto
Unescape View File

@ -0,0 +1,150 @@
syntax = "proto3";
package envoy.extensions.filters.http.ext_proc.v3alpha;
import "envoy/config/core/v3/grpc_service.proto";
import "envoy/extensions/filters/http/ext_proc/v3alpha/processing_mode.proto";
import "google/protobuf/duration.proto";
import "udpa/annotations/status.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.extensions.filters.http.ext_proc.v3alpha";
option java_outer_classname = "ExtProcProto";
option java_multiple_files = true;
option (udpa.annotations.file_status).work_in_progress = true;
option (udpa.annotations.file_status).package_version_status = ACTIVE;
// [#protodoc-title: External Processing Filter]
// External Processing Filter
// [#extension: envoy.filters.http.ext_proc]
// The External Processing filter allows an external service to act on HTTP traffic in a flexible way.
// It 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
// :ref:`ProcessingRequest <envoy_v3_api_msg_service.ext_proc.v3alpha.ProcessingRequest>`
// messages, and the server must reply with
// :ref:`ProcessingResponse <envoy_v3_api_msg_service.ext_proc.v3alpha.ProcessingResponse>`.
// [#next-free-field: 9]
message ExternalProcessor {
// Configuration for the gRPC service that the filter will communicate with.
// The filter supports both the "Envoy" and "Google" gRPC clients.
config.core.v3.GrpcService grpc_service = 1;
// [#not-implemented-hide:]
// 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.
bool failure_mode_allow = 2;
// [#not-implemented-hide:]
// Specifies default options for how HTTP headers, trailers, and bodies are
// sent. See ProcessingMode for details.
ProcessingMode processing_mode = 3;
// [#not-implemented-hide:]
// If true, send each part of the HTTP request or response specified by ProcessingMode
// asynchronously -- in other words, send the message on the gRPC stream and then continue
// filter processing. If false, which is the default, suspend filter execution after
// each message is sent to the remote service and wait up to "message_timeout"
// for a reply.
bool async_mode = 4;
// [#not-implemented-hide:]
// Envoy provides a number of :ref:`attributes <arch_overview_attributes>`
// for expressive policies. Each attribute name provided in this field will be
// matched against that list and populated in the request_headers message.
// See the :ref:`attribute documentation <arch_overview_request_attributes>`
// for the list of supported attributes and their types.
repeated string request_attributes = 5;
// [#not-implemented-hide:]
// Envoy provides a number of :ref:`attributes <arch_overview_attributes>`
// for expressive policies. Each attribute name provided in this field will be
// matched against that list and populated in the response_headers message.
// See the :ref:`attribute documentation <arch_overview_attributes>`
// for the list of supported attributes and their types.
repeated string response_attributes = 6;
// [#not-implemented-hide:]
// 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. There is no timeout when
// the filter is running in asynchronous mode. Default is 200 ms.
google.protobuf.Duration message_timeout = 7;
// [#not-implemented-hide:]
// Optional additional prefix to use when emitting statistics. This allows to distinguish
// emitted statistics between configured *ext_proc* filters in an HTTP filter chain.
string stat_prefix = 8;
}
// [#not-implemented-hide:]
// Extra settings that may be added to per-route configuration for a
// virtual host or cluster.
message ExtProcPerRoute {
oneof override {
option (validate.required) = true;
// 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.
bool disabled = 1 [(validate.rules).bool = {const: true}];
// Override aspects of the configuration for this route
ExtProcOverrides overrides = 2;
}
}
// [#not-implemented-hide:]
// Overrides that may be set on a per-route basis
message ExtProcOverrides {
// Set a different processing mode for this route than the default.
ProcessingMode processing_mode = 1;
// Set a different asynchronous processing option than the default.
bool async_mode = 2;
// Set different optional properties than the default.
repeated string request_properties = 3;
// Set different optional properties than the default.
repeated string response_properties = 4;
}

74
envoy/extensions/filters/http/ext_proc/v3alpha/processing_mode.proto
Unescape View File

@ -0,0 +1,74 @@
syntax = "proto3";
package envoy.extensions.filters.http.ext_proc.v3alpha;
import "udpa/annotations/status.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.extensions.filters.http.ext_proc.v3alpha";
option java_outer_classname = "ProcessingModeProto";
option java_multiple_files = true;
option (udpa.annotations.file_status).work_in_progress = true;
option (udpa.annotations.file_status).package_version_status = ACTIVE;
// [#protodoc-title: External Processing Filter]
// External Processing Filter Processing Mode
// [#extension: envoy.filters.http.ext_proc]
// This configuration describes which parts of an HTTP request and
// response are sent to a remote server and how they are delivered.
// [#next-free-field: 7]
message ProcessingMode {
// Control how headers and trailers are handled
enum HeaderSendMode {
// 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.
DEFAULT = 0;
// Send the header or trailer.
SEND = 1;
// Do not send the header or trailer.
SKIP = 2;
}
// Control how the request and response bodies are handled
enum BodySendMode {
// Do not send the body at all. This is the default.
NONE = 0;
// Stream the body to the server in pieces as they arrive at the
// proxy.
STREAMED = 1;
// 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 = 2;
// 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.
BUFFERED_PARTIAL = 3;
}
// How to handle the request header. Default is "SEND".
HeaderSendMode request_header_mode = 1 [(validate.rules).enum = {defined_only: true}];
// How to handle the response header. Default is "SEND".
HeaderSendMode response_header_mode = 2 [(validate.rules).enum = {defined_only: true}];
// How to handle the request body. Default is "NONE".
BodySendMode request_body_mode = 3 [(validate.rules).enum = {defined_only: true}];
// How do handle the response body. Default is "NONE".
BodySendMode response_body_mode = 4 [(validate.rules).enum = {defined_only: true}];
// How to handle the request trailers. Default is "SKIP".
HeaderSendMode request_trailer_mode = 5 [(validate.rules).enum = {defined_only: true}];
// How to handle the response trailers. Default is "SKIP".
HeaderSendMode response_trailer_mode = 6 [(validate.rules).enum = {defined_only: true}];
}

15
envoy/service/ext_proc/v3alpha/BUILD
Unescape View File

@ -0,0 +1,15 @@
# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
licenses(["notice"]) # Apache 2
api_proto_package(
has_services = True,
deps = [
"//envoy/config/core/v3:pkg",
"//envoy/extensions/filters/http/ext_proc/v3alpha:pkg",
"//envoy/type/v3:pkg",
"@com_github_cncf_udpa//udpa/annotations:pkg",
],
)

309
envoy/service/ext_proc/v3alpha/external_processor.proto
Unescape View File

@ -0,0 +1,309 @@
syntax = "proto3";
package envoy.service.ext_proc.v3alpha;
import "envoy/config/core/v3/base.proto";
import "envoy/extensions/filters/http/ext_proc/v3alpha/processing_mode.proto";
import "envoy/type/v3/http_status.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "udpa/annotations/status.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.service.ext_proc.v3alpha";
option java_outer_classname = "ExternalProcessorProto";
option java_multiple_files = true;
option java_generic_services = true;
option (udpa.annotations.file_status).work_in_progress = true;
option (udpa.annotations.file_status).package_version_status = ACTIVE;
// [#protodoc-title: External Processing Service]
// 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 ExternalProcessor {
// This begins the bidirectional stream that Envoy will use to
// give the server control over what the filter does. The actual
// protocol is described by the ProcessingRequest and ProcessingResponse
// messages below.
rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
}
}
// This represents the different types of messages that Envoy can send
// to an external processing server.
// [#next-free-field: 8]
message ProcessingRequest {
// 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.
bool async_mode = 1;
// 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.
oneof request {
option (validate.required) = true;
// 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.
HttpHeaders request_headers = 2;
// 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.
HttpHeaders response_headers = 3;
// 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.
HttpBody request_body = 4;
// A chunk of the HTTP request body. If "response_required" is set, the server must send back
// a BodyResponse message or close the stream.
HttpBody response_body = 5;
// The HTTP trailers for the request path. If "response_required" is set, the server
// must send back a TrailerResponse message or close the stream.
HttpTrailers request_trailers = 6;
// The HTTP trailers for the response path. If "response_required" is set, the server
// must send back a TrailerResponse message or close the stream.
HttpTrailers response_trailers = 7;
}
}
// For every ProcessingRequest received by the server with the "async_mode" field
// set to false, the server must send back exactly one ProcessingResponse message.
// [#next-free-field: 10]
message ProcessingResponse {
oneof response {
option (validate.required) = true;
// The server must send back this message in response to a message with the
// "request_headers" field set.
HeadersResponse request_headers = 1;
// The server must send back this message in response to a message with the
// "response_headers" field set.
HeadersResponse response_headers = 2;
// The server must send back this message in response to a message with
// the "request_body" field set.
BodyResponse request_body = 3;
// The server must send back this message in response to a message with
// the "response_body" field set.
BodyResponse response_body = 4;
// The server must send back this message in response to a message with
// the "request_trailers" field set.
TrailersResponse request_trailers = 5;
// The server must send back this message in response to a message with
// the "response_trailers" field set.
TrailersResponse response_trailers = 6;
// 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.
ImmediateResponse immediate_response = 7;
}
// 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".
google.protobuf.Struct dynamic_metadata = 8;
// 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.
envoy.extensions.filters.http.ext_proc.v3alpha.ProcessingMode mode_override = 9;
}
// The following are messages that are sent to the server.
// This message is sent to the external server when the HTTP request and responses
// are first received.
message HttpHeaders {
// The HTTP request headers. All header keys will be
// lower-cased, because HTTP header keys are case-insensitive.
config.core.v3.HeaderMap headers = 1;
// 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 :ref:`attributes <arch_overview_attributes>`
// supported across Envoy.
map<string, google.protobuf.Struct> attributes = 2;
// If true, then there is no message body associated with this
// request or response.
bool end_of_stream = 3;
}
// This message contains the message body that Envoy sends to the external server.
message HttpBody {
bytes body = 1;
bool end_of_stream = 2;
}
// This message contains the trailers.
message HttpTrailers {
config.core.v3.HeaderMap trailers = 1;
}
// The following are messages that may be sent back by the server.
// This message must be sent in response to an HttpHeaders message.
message HeadersResponse {
CommonResponse response = 1;
}
// This message must be sent in response to an HttpTrailers message.
message TrailersResponse {
// Instructions on how to manipulate the trailers
HeaderMutation header_mutation = 1;
}
// This message must be sent in response to an HttpBody message.
message BodyResponse {
CommonResponse response = 1;
}
// This message contains common fields between header and body responses.
// [#next-free-field: 6]
message CommonResponse {
enum ResponseStatus {
// 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 = 0;
// 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.
CONTINUE_AND_REPLACE = 1;
}
// If set, provide additional direction on how the Envoy proxy should
// handle the rest of the HTTP filter chain.
ResponseStatus status = 1 [(validate.rules).enum = {defined_only: true}];
// 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.
HeaderMutation header_mutation = 2;
// 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.
BodyMutation body_mutation = 3;
// 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.
config.core.v3.HeaderMap trailers = 4;
// Clear the route cache for the current request.
// This is necessary if the remote server
// modified headers that are used to calculate the route.
bool clear_route_cache = 5;
}
// 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.
// [#next-free-field: 6]
message ImmediateResponse {
// The response code to return
type.v3.HttpStatus status = 1 [(validate.rules).message = {required: true}];
// Apply changes to the default headers, which will include content-type.
HeaderMutation headers = 2;
// The message body to return with the response which is sent using the
// text/plain content type, or encoded in the grpc-message header.
string body = 3;
// If set, then include a gRPC status trailer.
GrpcStatus grpc_status = 4;
// A string detailing why this local reply was sent, which may be included
// in log and debug output.
string details = 5;
}
// This message specifies a gRPC status for an ImmediateResponse message.
message GrpcStatus {
// The actual gRPC status
uint32 status = 1;
}
// Change HTTP headers or trailers by appending, replacing, or removing
// headers.
message HeaderMutation {
// Add or replace HTTP headers.
repeated config.core.v3.HeaderValueOption set_headers = 1;
// Remove these HTTP headers.
repeated string remove_headers = 2;
}
// Replace the entire message body chunk received in the corresponding
// HttpBody message with this new body, or clear the body.
message BodyMutation {
oneof mutation {
// The entire body to replace
bytes body = 1;
// Clear the corresponding body chunk
bool clear_body = 2;
}
}

2
versioning/BUILD
Unescape View File

@ -62,6 +62,7 @@ proto_library(
"//envoy/extensions/filters/http/dynamic_forward_proxy/v3:pkg",
"//envoy/extensions/filters/http/dynamo/v3:pkg",
"//envoy/extensions/filters/http/ext_authz/v3:pkg",
"//envoy/extensions/filters/http/ext_proc/v3alpha:pkg",
"//envoy/extensions/filters/http/fault/v3:pkg",
"//envoy/extensions/filters/http/grpc_http1_bridge/v3:pkg",
"//envoy/extensions/filters/http/grpc_http1_reverse_bridge/v3:pkg",
@ -141,6 +142,7 @@ proto_library(
"//envoy/service/discovery/v3:pkg",
"//envoy/service/endpoint/v3:pkg",
"//envoy/service/event_reporting/v3:pkg",
"//envoy/service/ext_proc/v3alpha:pkg",
"//envoy/service/extension/v3:pkg",
"//envoy/service/health/v3:pkg",
"//envoy/service/listener/v3:pkg",

Write Preview
Loading…
Cancel
Save