package envoy.service.network_ext_proc.v3

Get desktop application:
View/edit binary Protocol Buffers messages

NetworkExternalProcessor service defines the contract between Envoy and external processing servers for L4 network traffic.

• rpc Process (stream ProcessingRequest, stream ProcessingResponse)

  network_external_processor.proto:55

  Process establishes a bidirectional stream between Envoy and the external processing server. Envoy sends ProcessingRequests containing network data and the server responds with ProcessingResponses containing processing decisions and potentially modified data. The server should handle processing timeout properly to avoid blocking network traffic for extended periods. Any uncaught exceptions will be treated as errors and will terminate the stream. Implementation note: The server should process requests in the order they are received to maintain proper sequencing of network traffic.

  message ProcessingRequest

  network_external_processor.proto:73

  ProcessingRequest contains data sent from Envoy to the external processing server. Each request contains either read data (from client) or write data (to client) along with optional metadata.

  • optional Data read_data = 1

    ReadData contains the network data intercepted in the request path (client to server). This is sent to the external processor when data arrives from the downstream client. If this is set, write_data should not be set.

  • optional Data write_data = 2

    WriteData contains the network data intercepted in the response path (server to client). This is sent to the external processor when data arrives from the upstream server. If this is set, read_data should not be set.

  • optional config.core.v3.Metadata metadata = 3

    Optional metadata associated with the request. This can include connection properties, filter configuration, and any other contextual information that might be useful for processing decisions. The metadata is not automatically propagated from request to response. The external processor must include any needed metadata in its response.

  message ProcessingResponse

  network_external_processor.proto:97

  ProcessingResponse contains the response from the external processing server to Envoy. Each response corresponds to a ProcessingRequest and indicates how the network traffic should be handled. [#next-free-field: 6]

  • optional Data read_data = 1

    The processed ReadData containing potentially modified data for the request path. This should be sent in response to a ProcessingRequest with read_data, and the previous data in ProcessingRequest will be replaced by the new data in Envoy's data plane. If this is set, write_data should not be set.

  • optional Data write_data = 2

    The processed WriteData containing potentially modified data for the response path. This should be sent in response to a ProcessingRequest with write_data, and the previous data in ProcessingRequest will be replaced by the new data in Envoy's data plane. If this is set, read_data should not be set.

  • ProcessingResponse.DataProcessedStatus data_processing_status = 3

    Indicates whether the data was modified or not. This is mandatory and tells Envoy whether to use the original or modified data.

  • ProcessingResponse.ConnectionStatus connection_status = 4

    Optional: Determines the connection behavior after processing. If not specified, CONTINUE is assumed, and the connection proceeds normally. Use CLOSE or CLOSE_RST to terminate the connection based on processing results.

  • optional google.protobuf.Struct dynamic_metadata = 5

    Optional metadata associated with the request. This can include connection properties, filter configuration, and any other contextual information that might be useful for processing decisions. The metadata is not automatically propagated from request to response. The external processor must include any needed metadata in its response.

The payload data from network layer

Used in: ProcessingRequest, ProcessingResponse

• bytes data = 1

  The raw payload data

• bool end_of_stream = 2

  Indicates whether this is the last data frame in the current direction. The external processor should still respond to this message even if there is no more data expected in this direction.

ConnectionStatus determines what happens to the connection after processing.

Used in: ProcessingResponse

• CONTINUE = 0

  Continue normal processing of the connection. This is the default behavior and allows traffic to flow normally.

• CLOSE = 1

  Close the connection with normal TCP FIN. This allows for clean connection termination with a normal close sequence. Any buffered data will be sent before closing.

• CLOSE_RST = 2

  Immediately reset the connection with TCP RST. This forcibly terminates the connection without a clean shutdown, discarding any buffered data. Use this for security-critical situations or when immediate termination is required.

DataProcessedStatus indicates whether the data was modified by the external processor.

Used in: ProcessingResponse

• UNKNOWN = 0

  The data processed status is unknown.

• UNMODIFIED = 1

  The data remains unchanged. Envoy will use the original data. This is useful when the processor only wants to inspect but not modify the traffic.

• MODIFIED = 2

  The data has been modified. Envoy will use the modified data provided in the response. This allows the processor to transform the network traffic as needed.