[−][src]Trait envoy_sdk::extension::filter::network::NetworkFilter
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>
&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
- atrait object
through whichNetwork 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<()>
&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 orEnvoy
itself).
fn on_upstream_data(
&mut self,
_data_size: usize,
_end_of_stream: bool,
_ops: &dyn UpstreamDataOps
) -> Result<FilterStatus>
&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
- atrait object
through whichNetwork 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<()>
&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 orEnvoy
itself).
fn on_connection_complete(
&mut self,
_ops: &dyn ConnectionCompleteOps
) -> Result<()>
&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<()>
&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
- atrait object
through whichNetwork Filter
can manipulate data of the connection it proxies.http_client_ops
- atrait object
through whichNetwork Filter
can access data of the response received byHttpClient
, including headers, body and trailers.