Trait envoy_sdk::extension::factory::ExtensionFactory

pub trait ExtensionFactory {
    type Extension;
    fn name() -> &'static str
    where
        Self: Sized;
    fn new_extension(
        &mut self, 
        _instance_id: InstanceId
    ) -> Result<Self::Extension>;

    fn on_configure(
        &mut self, 
        _config: ByteString, 
        _ops: &dyn ConfigureOps
    ) -> Result<ConfigStatus> { ... }
    fn on_drain(&mut self) -> Result<DrainStatus> { ... }
}

An interface of the Envoy Extension Factory.

ExtensionFactory is responsible for

• handling extension configuration,
• owning state shared by all extension instances,
• creating new instances of extension, injecting their dependencies and shared state.

At the moment, ExtensionFactory can be used for HttpFilter and NetworkFilter extensions.

AccessLogger extension has a different lifecycle and therefore manages its configuration differently.

Examples

Basic ExtensionFactory:

use envoy::extension::{ExtensionFactory, InstanceId, Result};

/// `ExtensionFactory` for `MyHttpFilter`.
struct MyHttpFilterFactory;

impl ExtensionFactory for MyHttpFilterFactory {
    type Extension = MyHttpFilter;

    fn name() -> &'static str { "my_http_filter" }

    fn new_extension(&mut self, _instance_id: InstanceId) -> Result<Self::Extension> {
        Ok(MyHttpFilter)
    }
}

Handling extension configuration:

use std::rc::Rc;
use envoy::extension::{factory, ConfigStatus, ExtensionFactory, InstanceId, Result};
use envoy::host::ByteString;

/// `ExtensionFactory` for `MyHttpFilter`.
struct MyHttpFilterFactory {
    // This example shows how multiple filter instances could share
    // the same configuration.
    config: Rc<String>,
}

impl ExtensionFactory for MyHttpFilterFactory {
    type Extension = MyHttpFilter;

    fn name() -> &'static str { "my_http_filter" }

    /// Called when extension is being (re-)configured on `Envoy Listener` update.
    fn on_configure(&mut self, config: ByteString, ops: &dyn factory::ConfigureOps) -> Result<ConfigStatus> {
        let config = if config.is_empty() { String::default() } else {
            String::from_utf8(config.into_bytes())?
        };
        self.config = Rc::new(config);
        Ok(ConfigStatus::Accepted)
    }

    fn new_extension(&mut self, _instance_id: InstanceId) -> Result<Self::Extension> {
        Ok(MyHttpFilter::new(Rc::clone(&self.config)))
    }
}

Sharing Stats between filter instances:

use std::rc::Rc;
use envoy::extension::{factory, ConfigStatus, ExtensionFactory, InstanceId, Result};
use envoy::host::stats::{Counter, Stats};

/// Stats shared between multiple filter instances.
pub struct MyStats {
    requests_total: Box<dyn Counter>,
}

/// `ExtensionFactory` for `MyHttpFilter`.
struct MyHttpFilterFactory {
    // This example shows how multiple filter instances could share stats.
    stats: Rc<MyStats>,
}

impl ExtensionFactory for MyHttpFilterFactory {
    type Extension = MyHttpFilter;

    fn name() -> &'static str { "my_http_filter" }

    fn new_extension(&mut self, _instance_id: InstanceId) -> Result<Self::Extension> {
        Ok(MyHttpFilter::new(Rc::clone(&self.stats)))
    }
}

impl MyHttpFilterFactory {
    /// Creates a new factory.
    pub fn new(stats: &dyn Stats) -> Result<Self> {
        let my_stats = MyStats{
            requests_total: stats.counter("examples.http_filter.requests_total")?,
        };
        Ok(MyHttpFilterFactory {
            stats: Rc::new(my_stats),
        })
    }

    /// Creates a new factory bound to the actual `Envoy` `ABI`.
    pub fn default() -> Result<Self> {
        Self::new(Stats::default())
    }
}

Associated Types

type Extension

Loading content...

Required methods

fn name() -> &'static str where
    Self: Sized, 

Returns a name the extension should be referred to in Envoy configuration.

fn new_extension(&mut self, _instance_id: InstanceId) -> Result<Self::Extension>

Called to create a new instance of the extension, e.g. HttpFilter or NetworkFilter.

Arguments

• instance_id - opaque identifier of the extension instance.

Return value

a new instance of the extension.

Loading content...

Provided methods

fn on_configure(
    &mut self,
    _config: ByteString,
    _ops: &dyn ConfigureOps
) -> Result<ConfigStatus>

Called when extension is being (re-)configured on Envoy Listener update.

Arguments

• _config - configuration.
• _ops - a trait object with operations available in this context.

Return value

ConfigStatus telling Envoy whether configuration has been successfully applied.

fn on_drain(&mut self) -> Result<DrainStatus>

Called when ExtensionFactory is about to be destroyed.

Return value

DrainStatus telling Envoy whether ExtensionFactory has already been drained and can be now removed safely.

Loading content...

Implementors

Loading content...