Trait envoy_sdk::extension::filter::http::HttpFilter[−][src]

pub trait HttpFilter {
    fn on_request_headers(
        &mut self, 
        _num_headers: usize, 
        _end_of_stream: bool, 
        _ops: &dyn RequestHeadersOps
    ) -> Result<FilterHeadersStatus> { ... }

    fn on_request_body(
        &mut self, 
        _data_size: usize, 
        _end_of_stream: bool, 
        _ops: &dyn RequestBodyOps
    ) -> Result<FilterDataStatus> { ... }

    fn on_request_trailers(
        &mut self, 
        _num_trailers: usize, 
        _ops: &dyn RequestTrailersOps
    ) -> Result<FilterTrailersStatus> { ... }

    fn on_response_headers(
        &mut self, 
        _num_headers: usize, 
        _end_of_stream: bool, 
        _ops: &dyn ResponseHeadersOps
    ) -> Result<FilterHeadersStatus> { ... }

    fn on_response_body(
        &mut self, 
        _data_size: usize, 
        _end_of_stream: bool, 
        _ops: &dyn ResponseBodyOps
    ) -> Result<FilterDataStatus> { ... }

    fn on_response_trailers(
        &mut self, 
        _num_trailers: usize, 
        _ops: &dyn ResponseTrailersOps
    ) -> Result<FilterTrailersStatus> { ... }

    fn on_exchange_complete(
        &mut self, 
        _ops: &dyn ExchangeCompleteOps
    ) -> 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 HTTP Filter extension.

HTTP Filter operates on a single HTTP stream, i.e. request/response pair.

A dedicated HTTP Filter instance is created for every HTTP/1.1 request or HTTP/2 stream handled by Envoy.

Consequently, state of a single HTTP stream can be stored inside HTTP Filter itself.

Examples

Basic HttpFilter:

use envoy::extension::{HttpFilter, Result};
use envoy::extension::filter::http::{FilterHeadersStatus, RequestHeadersOps};
use envoy::host::log;

/// My very own `HttpFilter`.
struct MyHttpFilter;

impl HttpFilter for MyHttpFilter {
    fn on_request_headers(&mut self, _num_headers: usize, _end_of_stream: bool, ops: &dyn RequestHeadersOps) -> Result<FilterHeadersStatus> {
        let user_agent = ops.request_header("user-agent")?.unwrap_or_else(|| "<unknown>".into());
        log::info!("user-agent: {}", user_agent);
        Ok(FilterHeadersStatus::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 HTTP request by sending a response with the HTTP Status code 500 (Internal Server Error).

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

Provided methods

fn on_request_headers(
    &mut self,
    _num_headers: usize,
    _end_of_stream: bool,
    _ops: &dyn RequestHeadersOps
) -> Result<FilterHeadersStatus>[src]

Called with decoded request headers.

Arguments

  • num_headers - number of headers in the request.
  • ops - a trait object through which HTTP Filter can manipulate request headers.

Return value

FilterHeadersStatus telling Envoy how to manage further filter iteration.

Examples

Basic usage to sniff request headers:

  fn on_request_headers(&mut self, _num_headers: usize, _end_of_stream: bool, ops: &dyn RequestHeadersOps) -> Result<FilterHeadersStatus> {
      let user_agent = ops.request_header("user-agent")?.unwrap_or_else(|| "<unknown>".into());
      log::info!("user-agent: {}", user_agent);
      Ok(FilterHeadersStatus::Continue)
  }

fn on_request_body(
    &mut self,
    _data_size: usize,
    _end_of_stream: bool,
    _ops: &dyn RequestBodyOps
) -> Result<FilterDataStatus>[src]

Called with a decoded request data frame.

Arguments

  • data_size - size of data accumulated in the read buffer.
  • end_of_stream - supplies whether this is the last data frame.
  • ops - a trait object through which HTTP Filter can manipulate request body.

Return value

FilterDataStatus telling Envoy how to manage further filter iteration.

Examples

Basic usage to sniff request body:

  fn on_request_body(&mut self, _data_size: usize, _end_of_stream: bool, ops: &dyn RequestBodyOps) -> Result<FilterDataStatus> {
      let head = ops.request_data(0, 10)?;
      log::info!("body chunk starts with: {:?}", head);
      Ok(FilterDataStatus::Continue)
  }

fn on_request_trailers(
    &mut self,
    _num_trailers: usize,
    _ops: &dyn RequestTrailersOps
) -> Result<FilterTrailersStatus>[src]

Called with decoded trailers, implicitly ending the stream.

Arguments

  • num_trailers - number of trailers in the request.
  • ops - a trait object through which HTTP Filter can manipulate request trailers.

Return value

FilterTrailersStatus telling Envoy how to manage further filter iteration.

Examples

Basic usage to sniff request trailers:

  fn on_request_trailers(&mut self, _num_headers: usize, ops: &dyn RequestTrailersOps) -> Result<FilterTrailersStatus> {
      let grpc_message = ops.request_trailer("grpc-message")?.unwrap_or_else(|| "<unknown>".into());
      log::info!("grpc-message: {}", grpc_message);
      Ok(FilterTrailersStatus::Continue)
  }

fn on_response_headers(
    &mut self,
    _num_headers: usize,
    _end_of_stream: bool,
    _ops: &dyn ResponseHeadersOps
) -> Result<FilterHeadersStatus>[src]

Called with response headers to be encoded.

fn on_response_body(
    &mut self,
    _data_size: usize,
    _end_of_stream: bool,
    _ops: &dyn ResponseBodyOps
) -> Result<FilterDataStatus>[src]

Called with response body to be encoded.

fn on_response_trailers(
    &mut self,
    _num_trailers: usize,
    _ops: &dyn ResponseTrailersOps
) -> Result<FilterTrailersStatus>[src]

Called with response trailers to be encoded.

fn on_exchange_complete(&mut self, _ops: &dyn ExchangeCompleteOps) -> Result<()>[src]

Called when HTTP stream 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<()>[src]

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 HTTP Filter can access data of the HTTP stream 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...