rtc_interceptor_derive/

lib.rs

#![warn(missing_docs)]
//! Derive macros for RTC Interceptor trait.
//!
//! This crate provides two macros that work together:
//!
//! - `#[derive(Interceptor)]` - Marks a struct as an interceptor and identifies the next field
//! - `#[interceptor]` - Attribute macro for impl blocks to generate trait implementations
//!
//! # Design Pattern
//!
//! The examples below are illustrative rather than compiled: the macros only expand to something
//! meaningful in the presence of the `Interceptor` trait from
//! [`rtc-interceptor`](https://docs.rs/rtc-interceptor), which depends on *this* crate — so a
//! doctest here cannot import it. They are exercised for real by `rtc-interceptor`'s own
//! documentation and tests.
//!
//! The design follows Rust's derive pattern (similar to `#[derive(Default)]` with `#[default]`):
//!
//! ```ignore
//! use rtc_interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
//! use rtc_shared::error::Error;
//! use sansio::Protocol;
//! use std::collections::VecDeque;
//!
//! #[derive(Interceptor)]
//! pub struct MyInterceptor<P: Interceptor> {
//!     #[next]
//!     next: P,  // The next interceptor in the chain (can use any field name)
//!     buffer: VecDeque<TaggedPacket>,
//! }
//!
//! #[interceptor]
//! impl<P: Interceptor> MyInterceptor<P> {
//!     #[overrides]
//!     fn handle_read(&mut self, msg: TaggedPacket) -> Result<(), Self::Error> {
//!         // Custom logic here
//!         self.next.handle_read(msg)
//!     }
//! }
//! ```
//!
//! # Pure Delegation (No Custom Logic)
//!
//! For interceptors that just pass through without modification:
//!
//! ```ignore
//! # use rtc_interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
//! # use rtc_shared::error::Error;
//! # use sansio::Protocol;
//! # use std::collections::VecDeque;
//! #[derive(Interceptor)]
//! pub struct PassthroughInterceptor<P: Interceptor> {
//!     #[next]
//!     next: P,
//! }
//!
//! #[interceptor]
//! impl<P: Interceptor> PassthroughInterceptor<P> {}
//! // Empty impl block - all methods are auto-generated
//! ```
//!
//! # Required Imports
//!
//! The macros require certain types to be in scope:
//!
//! The generated code names `sansio::Protocol`, `Error`, `StreamInfo` and
//! `TaggedPacket`, so all four must be in scope at the use site — not only the macros
//! themselves:
//!
//! ```ignore
//! use rtc_interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
//! use rtc_shared::error::Error;
//! use sansio::Protocol;
//! ```
//!
//! Through the `rtc` umbrella crate the same imports are:
//!
//! ```ignore
//! use rtc::interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
//! use rtc::sansio::Protocol;
//! use rtc::shared::error::Error;
//! ```

use proc_macro::TokenStream;
use quote::quote;
use syn::{Data, DeriveInput, Fields, Ident, ImplItem, ItemImpl, Type, parse_macro_input};

/// Derive macro that marks a struct as an interceptor.
///
/// This macro validates the struct has a `#[next]` field and generates
/// a hidden accessor method. It does NOT generate Protocol/Interceptor implementations -
/// those are generated by the `#[interceptor]` attribute on the impl block.
///
/// # Attributes
///
/// - `#[next]` - Mark the field that contains the next interceptor in the chain (required)
///
/// # Examples
///
/// Pure delegation (no custom logic):
/// ```ignore
/// # use rtc_interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
/// # use rtc_shared::error::Error;
/// # use sansio::Protocol;
/// # use std::collections::VecDeque;
/// #[derive(Interceptor)]
/// pub struct PassthroughInterceptor<P: Interceptor> {
///     #[next]
///     next: P,
/// }
///
/// #[interceptor]
/// impl<P: Interceptor> PassthroughInterceptor<P> {}
/// ```
///
/// With custom logic:
/// ```ignore
/// # use rtc_interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
/// # use rtc_shared::error::Error;
/// # use sansio::Protocol;
/// # use std::collections::VecDeque;
/// #[derive(Interceptor)]
/// pub struct MyInterceptor<P: Interceptor> {
///     #[next]
///     next: P,
///     buffer: VecDeque<TaggedPacket>,
/// }
///
/// #[interceptor]
/// impl<P: Interceptor> MyInterceptor<P> {
///     #[overrides]
///     fn handle_read(&mut self, msg: TaggedPacket) -> Result<(), Self::Error> {
///         // Custom logic
///         self.next.handle_read(msg)
///     }
/// }
/// ```
#[proc_macro_derive(Interceptor, attributes(next))]
pub fn derive_interceptor(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);

    // Find the next field marked with #[next] - validates it exists and gets its type
    let (next_name, next_type) = match find_next_field(&input) {
        Ok(field) => field,
        Err(err) => return err.into_compile_error().into(),
    };

    let name = &input.ident;
    let generics = &input.generics;
    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

    // Generate hidden accessor method that #[interceptor] will use
    // This allows #[interceptor] to work without knowing the field name
    let expanded = quote! {
        impl #impl_generics #name #ty_generics #where_clause {
            /// Hidden accessor for the next interceptor (used by #[interceptor] macro)
            #[doc(hidden)]
            #[inline(always)]
            fn __interceptor_inner_mut(&mut self) -> &mut #next_type {
                &mut self.#next_name
            }
        }
    };

    TokenStream::from(expanded)
}

/// Attribute macro for impl blocks to generate Protocol and Interceptor implementations.
///
/// This macro generates the trait implementations, delegating non-overridden
/// methods to the next interceptor field (identified by `#[next]` in the struct).
///
/// **Important:** The struct must have `#[derive(Interceptor)]` with a `#[next]` field.
///
/// # Attributes
///
/// - `#[overrides]` - Mark methods that provide custom implementations
///
/// # Examples
///
/// With custom logic:
/// ```ignore
/// # use rtc_interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
/// # use rtc_shared::error::Error;
/// # use sansio::Protocol;
/// # use std::collections::VecDeque;
/// #[derive(Interceptor)]
/// pub struct MyInterceptor<P: Interceptor> {
///     #[next]
///     next: P,  // Can use any field name
///     buffer: VecDeque<TaggedPacket>,
/// }
///
/// #[interceptor]
/// impl<P: Interceptor> MyInterceptor<P> {
///     #[overrides]
///     fn handle_read(&mut self, msg: TaggedPacket) -> Result<(), Self::Error> {
///         // Custom logic
///         self.next.handle_read(msg)
///     }
/// }
/// ```
///
/// Pure delegation (no custom logic):
/// ```ignore
/// # use rtc_interceptor::{Interceptor, StreamInfo, TaggedPacket, interceptor};
/// # use rtc_shared::error::Error;
/// # use sansio::Protocol;
/// # use std::collections::VecDeque;
/// #[derive(Interceptor)]
/// pub struct PassthroughInterceptor<P: Interceptor> {
///     #[next]
///     wrapped: P,  // Can use any field name
/// }
///
/// #[interceptor]
/// impl<P: Interceptor> PassthroughInterceptor<P> {}
/// // Empty impl - all methods delegate to wrapped field
/// ```
#[proc_macro_attribute]
pub fn interceptor(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut input = parse_macro_input!(item as ItemImpl);

    // Note: Field name is no longer needed here - we use __interceptor_inner_mut() accessor
    // which is generated by #[derive(Interceptor)]

    // Collect method names marked with #[overrides]
    let mut override_methods: Vec<Ident> = Vec::new();

    for item in &mut input.items {
        if let ImplItem::Fn(method) = item {
            // Check if method has #[overrides] attribute
            let has_override = method
                .attrs
                .iter()
                .any(|attr| attr.path().is_ident("overrides"));

            if has_override {
                override_methods.push(method.sig.ident.clone());
                // Remove the #[overrides] attribute
                method
                    .attrs
                    .retain(|attr| !attr.path().is_ident("overrides"));
            }
        }
    }

    // Get type name and generics from the impl
    let self_ty = &input.self_ty;
    let generics = &input.generics;
    let where_clause = &generics.where_clause;
    let (impl_generics, _, _) = generics.split_for_impl();

    // Generate Protocol methods that are NOT overridden (using accessor method)
    let protocol_methods = generate_protocol_methods(&override_methods);
    let interceptor_methods = generate_interceptor_methods(&override_methods);

    // Protocol method names
    let protocol_method_names = [
        "handle_read",
        "poll_read",
        "handle_write",
        "poll_write",
        "handle_event",
        "poll_event",
        "handle_timeout",
        "poll_timeout",
        "close",
    ];

    // Interceptor method names
    let interceptor_method_names = [
        "bind_local_stream",
        "unbind_local_stream",
        "bind_remote_stream",
        "unbind_remote_stream",
    ];

    // Extract Protocol overridden methods
    let protocol_override_items: Vec<_> = input
        .items
        .iter()
        .filter(|item| {
            if let ImplItem::Fn(method) = item {
                let name = method.sig.ident.to_string();
                override_methods.contains(&method.sig.ident)
                    && protocol_method_names.contains(&name.as_str())
            } else {
                false
            }
        })
        .collect();

    // Extract Interceptor overridden methods
    let interceptor_override_items: Vec<_> = input
        .items
        .iter()
        .filter(|item| {
            if let ImplItem::Fn(method) = item {
                let name = method.sig.ident.to_string();
                override_methods.contains(&method.sig.ident)
                    && interceptor_method_names.contains(&name.as_str())
            } else {
                false
            }
        })
        .collect();

    let expanded = quote! {
        impl #impl_generics sansio::Protocol<
            TaggedPacket,
            TaggedPacket,
            ()
        > for #self_ty #where_clause {
            type Rout = TaggedPacket;
            type Wout = TaggedPacket;
            type Eout = ();
            type Error = Error;
            type Time = std::time::Instant;

            #protocol_methods
            #(#protocol_override_items)*
        }

        impl #impl_generics Interceptor for #self_ty #where_clause {
            #interceptor_methods
            #(#interceptor_override_items)*
        }
    };

    TokenStream::from(expanded)
}

/// Find the field marked with #[next] attribute, returning both name and type
fn find_next_field(input: &DeriveInput) -> syn::Result<(Ident, Type)> {
    let fields = match &input.data {
        Data::Struct(data) => &data.fields,
        _ => {
            return Err(syn::Error::new_spanned(
                input,
                "Interceptor can only be derived for structs",
            ));
        }
    };

    let named_fields = match fields {
        Fields::Named(fields) => &fields.named,
        _ => {
            return Err(syn::Error::new_spanned(
                input,
                "Interceptor can only be derived for structs with named fields",
            ));
        }
    };

    for field in named_fields {
        let has_next_attr = field.attrs.iter().any(|attr| attr.path().is_ident("next"));
        if has_next_attr {
            let ident = field
                .ident
                .clone()
                .ok_or_else(|| syn::Error::new_spanned(field, "Field must have a name"))?;
            let ty = field.ty.clone();
            return Ok((ident, ty));
        }
    }

    Err(syn::Error::new_spanned(
        input,
        "No field marked with #[next] attribute. Mark the next interceptor field with #[next].",
    ))
}

/// Generate Protocol methods that delegate to inner, excluding overridden ones
fn generate_protocol_methods(override_methods: &[Ident]) -> proc_macro2::TokenStream {
    let mut methods = proc_macro2::TokenStream::new();

    if !override_methods.iter().any(|m| m == "handle_read") {
        methods.extend(quote! {
            fn handle_read(&mut self, msg: TaggedPacket) -> Result<(), Self::Error> {
                self.__interceptor_inner_mut().handle_read(msg)
            }
        });
    }

    if !override_methods.iter().any(|m| m == "poll_read") {
        methods.extend(quote! {
            fn poll_read(&mut self) -> Option<Self::Rout> {
                self.__interceptor_inner_mut().poll_read()
            }
        });
    }

    if !override_methods.iter().any(|m| m == "handle_write") {
        methods.extend(quote! {
            fn handle_write(&mut self, msg: TaggedPacket) -> Result<(), Self::Error> {
                self.__interceptor_inner_mut().handle_write(msg)
            }
        });
    }

    if !override_methods.iter().any(|m| m == "poll_write") {
        methods.extend(quote! {
            fn poll_write(&mut self) -> Option<Self::Wout> {
                self.__interceptor_inner_mut().poll_write()
            }
        });
    }

    if !override_methods.iter().any(|m| m == "handle_event") {
        methods.extend(quote! {
            fn handle_event(&mut self, evt: ()) -> Result<(), Self::Error> {
                self.__interceptor_inner_mut().handle_event(evt)
            }
        });
    }

    if !override_methods.iter().any(|m| m == "poll_event") {
        methods.extend(quote! {
            fn poll_event(&mut self) -> Option<Self::Eout> {
                self.__interceptor_inner_mut().poll_event()
            }
        });
    }

    if !override_methods.iter().any(|m| m == "handle_timeout") {
        methods.extend(quote! {
            fn handle_timeout(&mut self, now: Self::Time) -> Result<(), Self::Error> {
                self.__interceptor_inner_mut().handle_timeout(now)
            }
        });
    }

    if !override_methods.iter().any(|m| m == "poll_timeout") {
        methods.extend(quote! {
            fn poll_timeout(&mut self) -> Option<Self::Time> {
                self.__interceptor_inner_mut().poll_timeout()
            }
        });
    }

    if !override_methods.iter().any(|m| m == "close") {
        methods.extend(quote! {
            fn close(&mut self) -> Result<(), Self::Error> {
                self.__interceptor_inner_mut().close()
            }
        });
    }

    methods
}

/// Generate Interceptor methods that delegate to inner, excluding overridden ones
fn generate_interceptor_methods(override_methods: &[Ident]) -> proc_macro2::TokenStream {
    let mut methods = proc_macro2::TokenStream::new();

    if !override_methods.iter().any(|m| m == "bind_local_stream") {
        methods.extend(quote! {
            fn bind_local_stream(&mut self, info: &StreamInfo) {
                self.__interceptor_inner_mut().bind_local_stream(info);
            }
        });
    }

    if !override_methods.iter().any(|m| m == "unbind_local_stream") {
        methods.extend(quote! {
            fn unbind_local_stream(&mut self, info: &StreamInfo) {
                self.__interceptor_inner_mut().unbind_local_stream(info);
            }
        });
    }

    if !override_methods.iter().any(|m| m == "bind_remote_stream") {
        methods.extend(quote! {
            fn bind_remote_stream(&mut self, info: &StreamInfo) {
                self.__interceptor_inner_mut().bind_remote_stream(info);
            }
        });
    }

    if !override_methods.iter().any(|m| m == "unbind_remote_stream") {
        methods.extend(quote! {
            fn unbind_remote_stream(&mut self, info: &StreamInfo) {
                self.__interceptor_inner_mut().unbind_remote_stream(info);
            }
        });
    }

    methods
}