[−][src]Trait envoy_sdk::extension::filter::network::NetworkFilter

pub trait NetworkFilter {
    fn on_new_connection(&mut self) -> Result<FilterStatus> { ... }

    fn on_downstream_data(
        &mut self, 
        _data_size: usize, 
        _end_of_stream: bool, 
        _ops: &dyn DownstreamDataOps
    ) -> Result<FilterStatus> { ... }

    fn on_downstream_close(
        &mut self, 
        _peer_type: PeerType, 
        _ops: &dyn DownstreamCloseOps
    ) -> Result<()> { ... }

    fn on_upstream_data(
        &mut self, 
        _data_size: usize, 
        _end_of_stream: bool, 
        _ops: &dyn UpstreamDataOps
    ) -> Result<FilterStatus> { ... }

    fn on_upstream_close(
        &mut self, 
        _peer_type: PeerType, 
        _ops: &dyn UpstreamCloseOps
    ) -> Result<()> { ... }

    fn on_connection_complete(
        &mut self, 
        _ops: &dyn ConnectionCompleteOps
    ) -> Result<()> { ... }

    fn on_http_call_response(
        &mut self, 
        _request_id: HttpClientRequestHandle, 
        _num_headers: usize, 
        _body_size: usize, 
        _num_trailers: usize, 
        _filter_ops: &dyn Ops, 
        _http_client_ops: &dyn HttpClientResponseOps
    ) -> Result<()> { ... }
}

An interface of the Envoy Network Filter extension.

Network Filter operates on a single TCP connection.

A dedicated Network Filter instance is created for every connection handled by Envoy.

Consequently, state of a single connection can be stored inside Network Filter itself.

Examples

Basic Network Filter:

use envoy::extension::{NetworkFilter, Result};
use envoy::extension::filter::network::FilterStatus;
use envoy::host::log;

/// My very own `NetworkFilter`.
struct MyNetworkFilter;

impl NetworkFilter for MyNetworkFilter {
    fn on_new_connection(&mut self) -> Result<FilterStatus> {
        log::info!("a new connection has been established");
        Ok(FilterStatus::Continue)
    }
}

NOTE

This trait MUST NOT panic!

If a filter invocation cannot proceed normally, it should return Result::Err(x). In that case, Envoy SDK will be able to terminate only the affected TCP connection by closing it gracefully.

For comparison, if the extension choose to panic, this will, at best, affect all ongoing TCP connections handled by that extension, and, at worst, will crash Envoy entirely (as of July 2020).

Provided methods

fn on_new_connection(&mut self) -> Result<FilterStatus>

Called when a connection is first established.

Filters should do one time long term processing that needs to be done when a connection is established. Filter chain iteration can be stopped if needed.

Return value

FilterStatus telling Envoy how to manage further filter iteration.

fn on_downstream_data(
    &mut self,
    _data_size: usize,
    _end_of_stream: bool,
    _ops: &dyn DownstreamDataOps
) -> Result<FilterStatus>

Called when data is read on the downstream connection.

Arguments

  • data_size - size of data accumulated in the buffer.
  • end_of_stream - supplies whether this is the last byte on the connection. This will only be set if the connection has half-close semantics enabled.
  • ops - a trait object through which Network Filter can manipulate data in the read buffer.

Return value

FilterStatus telling Envoy how to manage further filter iteration.

fn on_downstream_close(
    &mut self,
    _peer_type: PeerType,
    _ops: &dyn DownstreamCloseOps
) -> Result<()>

Called when downstream connection is closed.

Arguments

  • peer_type - supplies who closed the connection (either the remote party or Envoy itself).

fn on_upstream_data(
    &mut self,
    _data_size: usize,
    _end_of_stream: bool,
    _ops: &dyn UpstreamDataOps
) -> Result<FilterStatus>

Called when data is to be written on the connection.

Arguments

  • data_size - size of data accumulated in the write buffer.
  • end_of_stream - supplies whether this is the last byte to write on the connection.
  • ops - a trait object through which Network Filter can manipulate data in the write buffer.

Return value

FilterStatus telling Envoy how to manage further filter iteration.

fn on_upstream_close(
    &mut self,
    _peer_type: PeerType,
    _ops: &dyn UpstreamCloseOps
) -> Result<()>

Called when upstream connection is closed.

Arguments

  • peer_type - supplies who closed the connection (either the remote party or Envoy itself).

fn on_connection_complete(
    &mut self,
    _ops: &dyn ConnectionCompleteOps
) -> Result<()>

Called when TCP connection is complete.

This moment happens before Access Loggers get called.

fn on_http_call_response(
    &mut self,
    _request_id: HttpClientRequestHandle,
    _num_headers: usize,
    _body_size: usize,
    _num_trailers: usize,
    _filter_ops: &dyn Ops,
    _http_client_ops: &dyn HttpClientResponseOps
) -> Result<()>

Called when the async HTTP request made through Envoy HTTP Client API is complete.

Arguments

  • request_id - opaque identifier of the request that is now complete.
  • num_headers - number of headers in the response.
  • body_size - size of the response body.
  • num_trailers - number of tarilers in the response.
  • filter_ops - a trait object through which Network Filter can manipulate data of the connection it proxies.
  • http_client_ops - a trait object through which Network Filter can access data of the response received by HttpClient, including headers, body and trailers.
Loading content...

Implementors

Loading content...