外部處理服務 (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: (重複 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) 可選的中繼資料，將會作為動態中繼資料發出，以供後續篩選器使用。此中繼資料將放置在 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 過濾器狀態機的完整。必須 >= 1 毫秒且 <= max_message_timeout。此訊息在特定的 Envoy ext_proc 過濾器處理狀態中最多可以傳送一次。要啟用此 API，必須將 max_message_timeout 設定為 >= 1 毫秒的數字。

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: (預設) 將此訊息中的變更指示套用至請求或回應，然後繼續正常處理過濾器串流。這是預設值。

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, 必要) 要傳回的回應代碼

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 其中之一。