Filter Extension Re-organisation (#293)

* Reorganisation filter extensions

* Update src/filters/factory.rs
* Update docs/extensions/filters/writing_custom_filters.md

Co-authored-by: Ifeanyi Ubah <[email protected]>
Co-authored-by: Mark Mandel <[email protected]>

docs/extensions/filters/writing_custom_filters.md

@@ -67,9 +67,10 @@ To extend Quilkin's code with our own custom filter, we need to do the following
    // src/main.rs
    use quilkin::filters::{Filter, ReadContext, ReadResponse, WriteContext, WriteResponse};
 
+   const NAME: &str = "greet.v1";
+
    // This creates adds an associated const named `FILTER_NAME` that points
    // to `"greet.v1"`.
-   #[quilkin::filter("greet.v1")]
    struct Greet;
 
    impl Filter for Greet {
@@ -88,7 +89,7 @@ To extend Quilkin's code with our own custom filter, we need to do the following
 
    ```rust
    // src/main.rs
-   # #[quilkin::filter("greet.v1")]
+   # const NAME: &str = "greet.v1";
    # struct Greet;
    # impl Filter for Greet {}
    # use quilkin::filters::Filter;
@@ -97,8 +98,8 @@ To extend Quilkin's code with our own custom filter, we need to do the following
    struct GreetFilterFactory;
    impl FilterFactory for GreetFilterFactory {
        fn name(&self) -> &'static str {
-           // We provide the name of filter that we defined with `#[quilkin::filter]`
-           Greet::FILTER_NAME
+           // We provide the name of filter that we defined earlier.
+           NAME
        }
        fn create_filter(&self, _: CreateFilterArgs) -> Result<Box<dyn Filter>, Error> {
            Ok(Box::new(Greet))
@@ -207,7 +208,6 @@ The [Serde] crate is used to describe static YAML configuration in code while [P
 
    # use quilkin::filters::{Filter, ReadContext, ReadResponse, WriteContext, WriteResponse};
 
-   #[quilkin::filter("greet.v1")]
    struct Greet(String);
 
    impl Filter for Greet {
@@ -238,7 +238,7 @@ The [Serde] crate is used to describe static YAML configuration in code while [P
    # struct Greet(String);
    # impl Filter for Greet { }
 
-   use quilkin::filters::ConfigType;
+   use quilkin::config::ConfigType;
 
    struct GreetFilterFactory;
    impl FilterFactory for GreetFilterFactory {
@@ -345,7 +345,7 @@ However, it usually contains a Protobuf equivalent of the filter's static config
 
        ```rust
        // src/main.rs
-       # use quilkin::filters::{ConfigType, CreateFilterArgs, Error, Filter, FilterFactory};
+       # use quilkin::{config::ConfigType, filters::{CreateFilterArgs, Error, Filter, FilterFactory}};
        # use serde::{Deserialize, Serialize};
        # #[derive(Serialize, Deserialize, Debug)]
        # struct Config {

examples/quilkin-filter-example/src/main.rs

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-use quilkin::filters::{prelude::*, DynFilterFactory};;
+use quilkin::filters::prelude::*;
 use quilkin::runner::run;
 
 use bytes::Bytes;
@@ -29,7 +29,12 @@ mod greet {
     include!(concat!(env!("OUT_DIR"), "/greet.rs"));
 }
 
-#[quilkin::filter("greet.v1")]
+pub const NAME: &str = "greet.v1";
+
+pub fn factory() -> DynFilterFactory {
+    Box::from(GreetFilterFactory)
+}
+
 struct Greet(String);
 
 impl Filter for Greet {
@@ -48,7 +53,7 @@ impl Filter for Greet {
 struct GreetFilterFactory;
 impl FilterFactory for GreetFilterFactory {
     fn name(&self) -> &'static str {
-        Greet::FILTER_NAME
+        NAME
     }
     fn create_filter(&self, args: CreateFilterArgs) -> Result<Box<dyn Filter>, Error> {
         let greeting = match args.config.unwrap() {
@@ -68,5 +73,5 @@ impl FilterFactory for GreetFilterFactory {
 
 #[tokio::main]
 async fn main() {
-    run(vec![DynFilterFactory::from(GreetFilterFactory)].into_iter()).await.unwrap();
+    run(vec![self::factory()].into_iter()).await.unwrap();
 }

macros/src/lib.rs

@@ -14,13 +14,11 @@
  * limitations under the License.
  */
 
-mod filter;
 mod include;
 
-use quote::{quote, ToTokens};
+use quote::ToTokens;
 use syn::parse_macro_input;
 
-use filter::FilterAttribute;
 use include::IncludeProto;
 
 /// Includes generated Protobuf definitions from `tonic`.
@@ -54,54 +52,3 @@ pub fn include_proto(input: proc_macro::TokenStream) -> proc_macro::TokenStream
         .to_token_stream()
         .into()
 }
-
-/// An attribute procedural macro for defining filters.
-///
-/// The `filter` attribute can be prepended to any struct, to automatically
-/// import the protobuf runtime version that was defined with [`include_proto`],
-/// and it defines an associated constant named `FILTER_NAME` containing
-/// the protobuf identifier.
-///
-/// A string literal representing the gRPC Protobuf name of the struct should
-/// always the first argument, followed by these optional keyword arguments for
-/// additional configuration.
-///
-/// - `root` sets the root of the path to import your Protobuf generated struct.
-///   **default:** `self`.
-///
-/// - `vis` sets the visibility of the associated `PROTOBUF_ID` constant.
-///   **default:** `pub (crate)`.
-///
-/// The macro generates code that looks something like the following;
-///
-/// ### Input
-/// ```
-/// #[quilkin::filter("quilkin.extensions.filters.debug.v1alpha1.Debug")]
-/// pub struct Debug;
-/// ```
-///
-/// ### Output
-/// ```
-/// impl Debug {
-///     pub (crate) const FILTER_NAME: &str = "quilkin.extensions.filters.debug.v1alpha1.Debug";
-/// }
-/// ```
-#[proc_macro_attribute]
-pub fn filter(
-    args: proc_macro::TokenStream,
-    input: proc_macro::TokenStream,
-) -> proc_macro::TokenStream {
-    let constant = parse_macro_input!(args as FilterAttribute);
-    let item = parse_macro_input!(input as syn::ItemStruct);
-    let name = &item.ident;
-    let (impl_generics, ty_generics, where_clause) = item.generics.split_for_impl();
-
-    quote!(
-        #item
-
-        impl #impl_generics #name #ty_generics #where_clause {
-            #constant
-        }
-    )
-    .into()
-}

src/config.rs

@@ -23,17 +23,24 @@ use serde::{Deserialize, Serialize};
 use uuid::Uuid;
 
 mod builder;
+mod config_type;
 mod endpoints;
 mod error;
 mod metadata;
 
-pub use crate::config::endpoints::{
-    EmptyListError, Endpoints, RetainedItems, UpstreamEndpoints, UpstreamEndpointsIter,
+pub(crate) use self::{
+    error::ValueInvalidArgs,
+    metadata::{extract_endpoint_tokens, parse_endpoint_metadata_from_yaml},
+};
+
+pub use self::{
+    builder::Builder,
+    config_type::ConfigType,
+    endpoints::{
+        EmptyListError, Endpoints, RetainedItems, UpstreamEndpoints, UpstreamEndpointsIter,
+    },
+    error::ValidationError,
 };
-pub(crate) use crate::config::error::ValueInvalidArgs;
-pub use builder::Builder;
-pub use error::ValidationError;
-pub(crate) use metadata::{extract_endpoint_tokens, parse_endpoint_metadata_from_yaml};
 
 base64_serde_type!(Base64Standard, base64::STANDARD);
 

src/filters/config.rs → src/config/config_type.rs

@@ -18,7 +18,7 @@ use std::convert::TryFrom;
 
 use bytes::Bytes;
 
-use crate::filters::error::{ConvertProtoConfigError, Error};
+use crate::filters::{ConvertProtoConfigError, Error};
 
 /// The configuration of a [`Filter`][crate::filters::Filter] from either a
 /// static or dynamic source.