外部处理服务 (proto)

一种可以在过滤器链中访问和修改 HTTP 请求和响应的服务。整个外部处理协议的工作方式如下

Envoy 向服务发送有关 HTTP 请求的信息。
服务发回一个 ProcessingResponse 消息，指示 Envoy 停止处理，继续不处理，或将消息主体下一部分发送给它。
如果请求，Envoy 将消息主体的一部分或整个主体发送给服务器。无论哪种情况，服务器在收到每条消息后都会发回 ProcessingResponse。
如果请求，Envoy 将 HTTP 尾部发送给服务器，服务器发回 ProcessingResponse。
此时，请求处理完成，当 Envoy 从上游服务器收到响应时，我们将在步骤 1 处继续。
在上述任何时候，如果服务器干净地关闭 gRPC 流，则 Envoy 继续处理，而不咨询服务器。
在上述任何时候，如果服务器在错误的情况下关闭 gRPC 流，则 Envoy 向客户端返回 500 错误，除非过滤器配置为忽略错误。

换句话说，该过程是一个请求/响应对话，但使用 gRPC 流使服务器更容易维护状态。

service.ext_proc.v3.ProcessingRequest

[service.ext_proc.v3.ProcessingRequest proto]

这表示 Envoy 可以发送到外部处理服务器的不同类型消息。

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

request_headers

(service.ext_proc.v3.HttpHeaders) 关于 HTTP 请求头的信息，以及对等信息和附加属性。除非 observability_mode 为 true，否则服务器必须发回一个 HeaderResponse 消息、一个 ImmediateResponse 消息，或关闭流。

每条请求消息将包含以下子消息之一。哪些消息针对特定 HTTP 请求/响应设置，取决于处理模式。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers。

response_headers

(service.ext_proc.v3.HttpHeaders) 关于 HTTP 响应头的信息，以及对等信息和附加属性。除非 observability_mode 为 true，否则服务器必须发回一个 HeaderResponse 消息或关闭流。

每条请求消息将包含以下子消息之一。哪些消息针对特定 HTTP 请求/响应设置，取决于处理模式。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers。

request_body

(service.ext_proc.v3.HttpBody) HTTP 请求主体的部分内容。除非 observability_mode 为 true，否则服务器必须发回一个 BodyResponse 消息、一个 ImmediateResponse 消息，或关闭流。

每条请求消息将包含以下子消息之一。哪些消息针对特定 HTTP 请求/响应设置，取决于处理模式。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers。

response_body

(service.ext_proc.v3.HttpBody) HTTP 响应主体的部分内容。除非 observability_mode 为 true，否则服务器必须发回一个 BodyResponse 消息或关闭流。

每条请求消息将包含以下子消息之一。哪些消息针对特定 HTTP 请求/响应设置，取决于处理模式。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers。

request_trailers

(service.ext_proc.v3.HttpTrailers) 请求路径的 HTTP 尾部。除非 observability_mode 为 true，否则服务器必须发回一个 TrailerResponse 消息或关闭流。

仅当尾部处理模式设置为 SEND 并且原始下游请求具有尾部时，才会发送此消息。

每条请求消息将包含以下子消息之一。哪些消息针对特定 HTTP 请求/响应设置，取决于处理模式。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers。

response_trailers

(service.ext_proc.v3.HttpTrailers) 响应路径的 HTTP 尾部。除非 observability_mode 为 true，否则服务器必须发回一个 TrailerResponse 消息或关闭流。

仅当尾部处理模式设置为 SEND 并且原始上游响应具有尾部时，才会发送此消息。

每条请求消息将包含以下子消息之一。哪些消息针对特定 HTTP 请求/响应设置，取决于处理模式。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers。

metadata_context: (config.core.v3.Metadata) 与请求关联的动态元数据。

attributes: (repeated map<string, Struct>) 在配置中由 request_attributes 或 response_attributes 列表选择的属性的值。列表中的每个条目都从 Envoy 中支持的标准属性填充。

observability_mode

(bool) 指定发送此请求的过滤器是否在 observability_mode 中运行，默认为 false。

值为 false 表示服务器必须通过发送匹配的 ProcessingResponse 消息或关闭流来响应此消息。
值为 true 表示服务器不应该响应此消息，因为任何响应都将被忽略。但是，它仍然可以关闭流以指示不再需要更多消息。

service.ext_proc.v3.ProcessingResponse

[service.ext_proc.v3.ProcessingResponse proto]

对于服务器接收到的每个 observability_mode 字段设置为 false 的 ProcessingRequest，服务器必须发回恰好一条 ProcessingResponse 消息。

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

request_headers

(service.ext_proc.v3.HeadersResponse) 服务器必须发回此消息以响应 request_headers 字段设置的消息。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers、immediate_response。

response_headers

(service.ext_proc.v3.HeadersResponse) 服务器必须发回此消息以响应 response_headers 字段设置的消息。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers、immediate_response。

request_body

(service.ext_proc.v3.BodyResponse) 服务器必须发回此消息以响应 request_body 字段设置的消息。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers、immediate_response。

response_body

(service.ext_proc.v3.BodyResponse) 服务器必须发回此消息以响应 response_body 字段设置的消息。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers、immediate_response。

request_trailers

(service.ext_proc.v3.TrailersResponse) 服务器必须发回此消息以响应 request_trailers 字段设置的消息。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers、immediate_response。

response_trailers

(service.ext_proc.v3.TrailersResponse) 服务器必须发回此消息以响应 response_trailers 字段设置的消息。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers、immediate_response。

immediate_response

(service.ext_proc.v3.ImmediateResponse) 如果指定，则尝试创建本地生成的响应，将其发送到下游，并停止处理其他过滤器，并忽略从远程服务器接收到的针对此请求或响应的任何其他消息。如果响应已经开始（例如，如果此消息是响应 response_body 消息发送的），那么这将直接将回复发送到下游编解码器，或重置流。

必须精确设置一个 request_headers、response_headers、request_body、response_body、request_trailers、response_trailers、immediate_response。

dynamic_metadata: (Struct) 可选的元数据，将作为动态元数据发出，供后续过滤器使用。此元数据将放置在结构的顶级字段名称指定的命名空间中。

mode_override: (extensions.filters.http.ext_proc.v3.ProcessingMode) 仅在特定请求/响应期间，覆盖如何处理 HTTP 请求和响应的各个部分。服务器可以使用此功能根据它们看到的标头和其他元数据智能地控制请求的处理方式。此字段仅适用于响应标头请求的服务器。如果在对正文或尾部请求的响应中设置了该字段，Envoy 将忽略它。当 ext_proc 过滤器配置 allow_mode_override 设置为 false 或 send_body_without_waiting_for_header_response 设置为 true 时，Envoy 也将忽略它。

override_message_timeout: (Duration) 当 ext_proc 服务器收到请求消息时，如果它需要更多时间来处理消息，它将返回一个带有新超时值的 ProcessingResponse 消息。当 Envoy 收到此响应消息时，它会忽略响应中的其他字段，只停止原始计时器（其超时值在 message_timeout 中指定），并使用此 override_message_timeout 值启动一个新的计时器，并保持 Envoy ext_proc 过滤器状态机完整。必须 >= 1ms 且 <= max_message_timeout 此类消息最多可以在特定的 Envoy ext_proc 过滤器处理状态中发送一次。要启用此 API，必须将 max_message_timeout 设置为 >= 1ms 的数字。

service.ext_proc.v3.HttpHeaders

[service.ext_proc.v3.HttpHeaders proto]

此消息在首次收到 HTTP 请求和响应时发送到外部服务器。

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

headers: (config.core.v3.HeaderMap) HTTP 请求标头。所有标头键都将小写，因为 HTTP 标头键不区分大小写。标头值在 raw_value 字段中编码。

end_of_stream: (bool) 如果为 true，则此请求或响应没有关联的正文消息。

service.ext_proc.v3.HttpBody

[service.ext_proc.v3.HttpBody proto]

此消息包含 Envoy 发送到外部服务器的消息正文。

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

body: (bytes)

end_of_stream: (bool)

service.ext_proc.v3.HttpTrailers

[service.ext_proc.v3.HttpTrailers proto]

此消息包含尾部。

{
  "trailers": {...}
}

trailers: (config.core.v3.HeaderMap) 标头值在 raw_value 字段中编码。

service.ext_proc.v3.HeadersResponse

[service.ext_proc.v3.HeadersResponse proto]

此消息必须作为对 HttpHeaders 消息的响应发送。

{
  "response": {...}
}

response: (service.ext_proc.v3.CommonResponse)

service.ext_proc.v3.TrailersResponse

[service.ext_proc.v3.TrailersResponse proto]

此消息必须作为对 HttpTrailers 消息的响应发送。

{
  "header_mutation": {...}
}

header_mutation: (service.ext_proc.v3.HeaderMutation) 如何操作尾部的说明

service.ext_proc.v3.BodyResponse

[service.ext_proc.v3.BodyResponse proto]

此消息必须作为对 HttpBody 消息的响应发送。

{
  "response": {...}
}

response: (service.ext_proc.v3.CommonResponse)

service.ext_proc.v3.CommonResponse

[service.ext_proc.v3.CommonResponse proto]

此消息包含标头和正文响应之间的公共字段。

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

status: (service.ext_proc.v3.CommonResponse.ResponseStatus) 如果设置，则提供有关 Envoy 代理应如何处理 HTTP 过滤器链其余部分的附加说明。

header_mutation: (service.ext_proc.v3.HeaderMutation) 如何操作标头的说明。在响应 HttpBody 请求时，标头变动仅在正文的当前处理模式为 BUFFERED 时才会生效。

body_mutation: (service.ext_proc.v3.BodyMutation) 替换发送到此流上的远程服务器的最后一条消息的正文。如果响应 HttpBody 请求，只需替换或清除发送到该请求的正文块。正文变动可能会对 header 或 body 消息的响应生效。当它是对 header 消息的响应时，只有当 status 设置为 CONTINUE_AND_REPLACE 时，它才会生效。

clear_route_cache: (bool) 清除当前客户端请求的路由缓存。如果远程服务器修改了用于计算路由的标头，则这将是必需的。此字段在响应方向中被忽略。如果 Envoy ext_proc 过滤器位于上游过滤器链中，则此字段也会被忽略。

Enum service.ext_proc.v3.CommonResponse.ResponseStatus

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

CONTINUE: (DEFAULT) ⁣将此消息中的变动说明应用于请求或响应，然后继续按正常方式处理过滤器流。这是默认设置。

CONTINUE_AND_REPLACE

⁣应用指定的标头变动，使用正文变动（如果存在）中指定的正文替换正文，并且即使处理模式配置为这样做，也不要为此请求或响应发送任何其他消息。

当用作对 request_headers 或 response_headers 消息的响应时，此状态使得可以完全替换正文同时丢弃原始正文，或者可以向以前没有正文的消息添加正文。

换句话说，此响应使得可以将 HTTP GET 转换为 POST、PUT 或 PATCH。

service.ext_proc.v3.ImmediateResponse

[service.ext_proc.v3.ImmediateResponse proto]

此消息会导致过滤器尝试创建本地生成的响应，将其发送到下游，停止处理其他过滤器，并忽略从此请求或响应的远程服务器接收的任何其他消息。如果响应已经开始，则这将直接将回复发送到下游编解码器，或者重置流。

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

status: (type.v3.HttpStatus, REQUIRED) 要返回的响应代码

headers: (service.ext_proc.v3.HeaderMutation) 对默认标头应用更改，其中将包含 content-type。

body: (bytes) 要与响应一起返回的消息正文，使用 text/plain 内容类型发送，或在 grpc-message 标头中编码。

grpc_status: (service.ext_proc.v3.GrpcStatus) 如果设置，则包含 gRPC 状态尾部。

details: (string) 一个字符串，详细说明为什么发送了此本地回复，它可能包含在日志和调试输出中（例如，这将填充 %RESPONSE_CODE_DETAILS% 命令操作符字段，供访问日志使用）。

service.ext_proc.v3.GrpcStatus

[service.ext_proc.v3.GrpcStatus proto]

此消息为 ImmediateResponse 消息指定 gRPC 状态。

{
  "status": ...
}

status: (uint32) 实际的 gRPC 状态

service.ext_proc.v3.HeaderMutation

[service.ext_proc.v3.HeaderMutation proto]

通过追加、替换或删除标头来更改 HTTP 标头或尾部。

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

set_headers: (repeated config.core.v3.HeaderValueOption) 添加或替换 HTTP 标头。尝试设置任何 x-envoy 标头的值，以及尝试设置 :method、:authority、:scheme 或 host 标头将被忽略。标头值在 raw_value 字段中编码。

remove_headers: (repeated string) 删除这些 HTTP 标头。尝试删除系统标头（任何以 : 开头的标头，以及 host）将被忽略。

service.ext_proc.v3.BodyMutation

[service.ext_proc.v3.BodyMutation proto]

用此新正文替换在相应的 HttpBody 消息中收到的整个消息正文块，或清除正文。

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

body

(bytes) 要替换的整个正文

只能设置 body、clear_body 中的一个。

clear_body

(bool) 清除相应的正文块

只能设置 body、clear_body 中的一个。