More example comments

Signed-off-by: Takeshi Yoneda <[email protected]>

Author: mathetake

rust/src/lib.rs

@@ -7,7 +7,12 @@ declare_init_functions!(init, new_http_filter_config_fn);
 
 /// This implements the [`envoy_proxy_dynamic_modules_rust_sdk::ProgramInitFunction`].
 ///
-/// This is called exactly once when the module is loaded.
+/// This is called exactly once when the module is loaded. It can be used to
+/// initialize global state as well as check the runtime environment to ensure that
+/// the module is running in a supported environment.
+///
+/// Returning `false` will cause Envoy to reject the config hence the
+/// filter will not be loaded.
 fn init() -> bool {
     true
 }
@@ -21,10 +26,10 @@ fn init() -> bool {
 fn new_http_filter_config_fn<EC: EnvoyHttpFilterConfig, EHF: EnvoyHttpFilter>(
     _envoy_filter_config: &mut EC,
     filter_name: &str,
-    _filter_config: &str,
+    filter_config: &str,
 ) -> Option<Box<dyn HttpFilterConfig<EC, EHF>>> {
     match filter_name {
-        "passthrough" => Some(Box::new(PassthroughHttpFilterConfig {})),
+        "passthrough" => Some(Box::new(PassthroughHttpFilterConfig::new(filter_config))),
         _ => panic!("Unknown filter name: {}", filter_name),
     }
 }

rust/src/passthrough.rs

@@ -1,11 +1,28 @@
 use envoy_proxy_dynamic_modules_rust_sdk::*;
 
 /// This implements the [`envoy_proxy_dynamic_modules_rust_sdk::HttpFilterConfig`] trait.
-pub struct PassthroughHttpFilterConfig {}
+///
+/// The trait corresponds to a Envoy filter chain configuration.
+pub struct PassthroughHttpFilterConfig {
+    _filter_config: String,
+}
+
+impl PassthroughHttpFilterConfig {
+    /// This is the constructor for the [`PassthroughHttpFilterConfig`].
+    ///
+    /// filter_config is the filter config from the Envoy config here:
+    /// https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/dynamic_modules/v3/dynamic_modules.proto#envoy-v3-api-msg-extensions-dynamic-modules-v3-dynamicmoduleconfig
+    pub fn new(filter_config: &str) -> Self {
+        Self {
+            _filter_config: filter_config.to_string(),
+        }
+    }
+}
 
 impl<EC: EnvoyHttpFilterConfig, EHF: EnvoyHttpFilter> HttpFilterConfig<EC, EHF>
     for PassthroughHttpFilterConfig
 {
+    /// This is called for each new HTTP filter.
     fn new_http_filter(&self, _envoy: &mut EC) -> Box<dyn HttpFilter<EHF>> {
         Box::new(PassthroughHttpFilter {})
     }
@@ -16,4 +33,43 @@ impl<EC: EnvoyHttpFilterConfig, EHF: EnvoyHttpFilter> HttpFilterConfig<EC, EHF>
 /// This is a passthrough filter that does nothing.
 pub struct PassthroughHttpFilter {}
 
+/// This implements the [`envoy_proxy_dynamic_modules_rust_sdk::HttpFilter`] trait.
+///
+/// Default implementation of all methods is to return `Continue`.
 impl<EHF: EnvoyHttpFilter> HttpFilter<EHF> for PassthroughHttpFilter {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    /// This demonstrates how to write a test without Envoy using a mock provided by the SDK.
+    fn test_passthrough_http_filter() {
+        let mut envoy_filter = envoy_proxy_dynamic_modules_rust_sdk::MockEnvoyHttpFilter::new();
+        let mut passthrough_filter = PassthroughHttpFilter {};
+        assert_eq!(
+            passthrough_filter.on_request_headers(&mut envoy_filter, false),
+            abi::envoy_dynamic_module_type_on_http_filter_request_headers_status::Continue
+        );
+        assert_eq!(
+            passthrough_filter.on_request_body(&mut envoy_filter, false),
+            abi::envoy_dynamic_module_type_on_http_filter_request_body_status::Continue
+        );
+        assert_eq!(
+            passthrough_filter.on_request_trailers(&mut envoy_filter),
+            abi::envoy_dynamic_module_type_on_http_filter_request_trailers_status::Continue
+        );
+        assert_eq!(
+            passthrough_filter.on_response_headers(&mut envoy_filter, false),
+            abi::envoy_dynamic_module_type_on_http_filter_response_headers_status::Continue
+        );
+        assert_eq!(
+            passthrough_filter.on_response_body(&mut envoy_filter, false),
+            abi::envoy_dynamic_module_type_on_http_filter_response_body_status::Continue
+        );
+        assert_eq!(
+            passthrough_filter.on_response_trailers(&mut envoy_filter),
+            abi::envoy_dynamic_module_type_on_http_filter_response_trailers_status::Continue
+        );
+    }
+}