wsforge_macros/

lib.rs

//! # WsForge Macros - Procedural Macros for WebSocket Framework
//!
//! This crate provides procedural macros to enhance the WsForge WebSocket framework,
//! making it easier to create handlers, derive traits, and reduce boilerplate code.
//!
//! ## Overview
//!
//! WsForge Macros offers compile-time code generation for common patterns in WebSocket
//! development. These macros transform simple, declarative code into efficient runtime
//! implementations, improving both developer experience and code maintainability.
//!
//! ## Available Macros
//!
//! | Macro | Type | Purpose |
//! |-------|------|---------|
//! | `#[websocket_handler]` | Attribute | Transform functions into WebSocket handlers |
//! | `#[derive(WebSocketMessage)]` | Derive | Auto-implement message conversion traits |
//! | `#[derive(WebSocketHandler)]` | Derive | Auto-implement handler trait |
//! | `routes!()` | Function-like | Create router with multiple routes |
//!
//! ## Features
//!
//! - 🎯 **Zero Runtime Overhead**: All code generation happens at compile time
//! - 🔧 **Type Safe**: Generated code is fully type-checked by the compiler
//! - 📝 **Less Boilerplate**: Reduce repetitive code patterns
//! - 🚀 **Performance**: Generates optimized code equivalent to hand-written implementations
//! - 🔍 **IDE Support**: Works with rust-analyzer for code completion and errors
//!
//! ## Macro Usage Examples
//!
//! ### `#[websocket_handler]` Attribute Macro
//!
//! Transform regular async functions into WebSocket handlers:
//!
//! ```
//! use wsforge_macros::websocket_handler;
//! use wsforge_core::prelude::*;
//!
//! #[websocket_handler]
//! async fn echo(msg: Message) -> Result<Message> {
//!     Ok(msg)
//! }
//! ```
//!
//! ### `#[derive(WebSocketMessage)]` Derive Macro
//!
//! Automatically implement message conversion methods:
//!
//! ```
//! use wsforge_macros::WebSocketMessage;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(WebSocketMessage, Serialize, Deserialize)]
//! struct ChatMessage {
//!     username: String,
//!     text: String,
//! }
//!
//! // Now you can use:
//! // let msg = chat_message.into_message();
//! // let chat = ChatMessage::from_message(msg)?;
//! ```
//!
//! ### `#[derive(WebSocketHandler)]` Derive Macro
//!
//! Automatically implement the Handler trait for custom types:
//!
//! ```
//! use wsforge_macros::WebSocketHandler;
//! use wsforge_core::prelude::*;
//!
//! #[derive(WebSocketHandler)]
//! struct MyHandler;
//!
//! impl MyHandler {
//!     async fn handle(
//!         &self,
//!         message: Message,
//!         conn: Connection,
//!         state: AppState,
//!         extensions: Extensions,
//!     ) -> Result<Option<Message>> {
//!         Ok(Some(Message::text("Handled!")))
//!     }
//! }
//! ```
//!
//! ### `routes!()` Macro
//!
//! Create a router with multiple routes in a declarative way:
//!
//! ```
//! use wsforge_macros::routes;
//!
//! let router = routes!();
//! // Expands to: Router::new()
//! ```
//!
//! ## Implementation Details
//!
//! ### Code Generation
//!
//! All macros use the `syn`, `quote`, and `proc-macro2` crates for parsing and
//! code generation. The generated code is designed to be:
//!
//! - **Readable**: Generated code looks like hand-written Rust
//! - **Efficient**: No unnecessary allocations or conversions
//! - **Compatible**: Works with all standard Rust tooling
//!
//! ### Error Handling
//!
//! Macros provide clear error messages at compile time when:
//! - Invalid syntax is used
//! - Required traits are not implemented
//! - Type constraints are not satisfied
//!
//! ## Advanced Usage
//!
//! ### Combining Macros
//!
//! You can combine multiple macros for maximum effect:
//!
//! ```
//! use wsforge_macros::{websocket_handler, WebSocketMessage};
//! use wsforge_core::prelude::*;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(WebSocketMessage, Serialize, Deserialize)]
//! struct Request {
//!     action: String,
//! }
//!
//! #[derive(WebSocketMessage, Serialize, Deserialize)]
//! struct Response {
//!     result: String,
//! }
//!
//! #[websocket_handler]
//! async fn process(Json(req): Json<Request>) -> Result<JsonResponse<Response>> {
//!     Ok(JsonResponse(Response {
//!         result: format!("Processed: {}", req.action),
//!     }))
//! }
//! ```
//!
//! ## Performance Characteristics
//!
//! - **Compile Time**: Minimal impact on compilation time
//! - **Runtime**: Zero overhead - generated code is as fast as hand-written
//! - **Binary Size**: No additional bloat from macro expansion
//!
//! ## Compatibility
//!
//! - **Rust Edition**: 2021 and later
//! - **Tooling**: Full support for rust-analyzer, rustfmt, clippy
//! - **Platforms**: All platforms supported by Rust
//!
//! ## Debugging Generated Code
//!
//! To see the code generated by macros, use `cargo-expand`:
//!
//! ```
//! cargo install cargo-expand
//! cargo expand --lib
//! ```
//!
//! ## Future Enhancements
//!
//! Potential future macros:
//! - `#[route]` - Define routes on handler functions directly
//! - `#[middleware]` - Create middleware from functions
//! - `#[state]` - Simplify state extraction patterns

// Enable documentation features for docs.rs
#![cfg_attr(docsrs, feature(doc_cfg))]
// Deny missing docs to ensure comprehensive documentation
#![warn(missing_docs)]
// Enable additional documentation lint rules
#![warn(rustdoc::missing_crate_level_docs)]

use proc_macro::TokenStream;
use quote::quote;
use syn::{DeriveInput, ItemFn, parse_macro_input};

/// Transforms an async function into a WebSocket handler.
///
/// This attribute macro wraps your async function to make it compatible with
/// the WsForge handler system. It preserves all function attributes, visibility,
/// and signature while adding the necessary wrapper code.
///
/// # Behavior
///
/// The macro:
/// - Preserves the original function signature
/// - Maintains async/await semantics
/// - Keeps visibility modifiers (pub, pub(crate), etc.)
/// - Preserves all other attributes
/// - Does not modify the function body
///
/// # Usage
///
/// ```
/// use wsforge_macros::websocket_handler;
/// use wsforge_core::prelude::*;
///
/// #[websocket_handler]
/// async fn my_handler(msg: Message) -> Result<String> {
///     Ok(format!("Received: {:?}", msg))
/// }
/// ```
///
/// # With Multiple Parameters
///
/// ```
/// use wsforge_macros::websocket_handler;
/// use wsforge_core::prelude::*;
/// use std::sync::Arc;
///
/// #[websocket_handler]
/// async fn complex_handler(
///     msg: Message,
///     conn: Connection,
///     State(manager): State<Arc<ConnectionManager>>,
/// ) -> Result<()> {
///     manager.broadcast(msg);
///     Ok(())
/// }
/// ```
///
/// # With Custom Return Types
///
/// ```
/// use wsforge_macros::websocket_handler;
/// use wsforge_core::prelude::*;
/// use serde::Serialize;
///
/// #[derive(Serialize)]
/// struct Response {
///     status: String,
/// }
///
/// #[websocket_handler]
/// async fn json_handler() -> Result<JsonResponse<Response>> {
///     Ok(JsonResponse(Response {
///         status: "ok".to_string(),
///     }))
/// }
/// ```
///
/// # Note
///
/// The function must be async and return a type that implements `IntoResponse`.
#[proc_macro_attribute]
pub fn websocket_handler(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let input = parse_macro_input!(item as ItemFn);

    let fn_name = &input.sig.ident;
    let fn_block = &input.block;
    let fn_inputs = &input.sig.inputs;
    let fn_output = &input.sig.output;
    let fn_asyncness = &input.sig.asyncness;
    let fn_vis = &input.vis;

    let expanded = quote! {
        #fn_vis #fn_asyncness fn #fn_name(#fn_inputs) #fn_output {
            #fn_block
        }
    };

    TokenStream::from(expanded)
}

/// Derives message conversion methods for custom types.
///
/// This derive macro automatically implements `into_message()` and `from_message()`
/// methods for your type, allowing easy conversion between your custom types and
/// WebSocket messages.
///
/// # Requirements
///
/// The type must implement:
/// - `serde::Serialize` (for `into_message()`)
/// - `serde::Deserialize` (for `from_message()`)
///
/// # Generated Methods
///
/// ## `into_message(&self) -> wsforge::Message`
///
/// Converts the type into a WebSocket text message containing JSON.
///
/// ## `from_message(msg: wsforge::Message) -> Result<Self, serde_json::Error>`
///
/// Parses a WebSocket message as JSON into your type.
///
/// # Examples
///
/// ## Basic Usage
///
/// ```
/// use wsforge_macros::WebSocketMessage;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(WebSocketMessage, Serialize, Deserialize)]
/// struct ChatMessage {
///     username: String,
///     text: String,
/// }
///
/// # fn example() {
/// let chat = ChatMessage {
///     username: "Alice".to_string(),
///     text: "Hello!".to_string(),
/// };
///
/// // Convert to message
/// let msg = chat.into_message();
///
/// // Parse from message
/// let parsed = ChatMessage::from_message(msg).unwrap();
/// # }
/// ```
///
/// ## With Nested Types
///
/// ```
/// use wsforge_macros::WebSocketMessage;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(Serialize, Deserialize)]
/// struct User {
///     id: u64,
///     name: String,
/// }
///
/// #[derive(WebSocketMessage, Serialize, Deserialize)]
/// struct UserMessage {
///     user: User,
///     action: String,
/// }
/// ```
///
/// ## Error Handling
///
/// ```
/// use wsforge_macros::WebSocketMessage;
/// use wsforge_core::prelude::*;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(WebSocketMessage, Serialize, Deserialize)]
/// struct Request {
///     command: String,
/// }
///
/// # fn example(msg: Message) {
/// match Request::from_message(msg) {
///     Ok(req) => println!("Command: {}", req.command),
///     Err(e) => eprintln!("Parse error: {}", e),
/// }
/// # }
/// ```
#[proc_macro_derive(WebSocketMessage)]
pub fn derive_websocket_message(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;

    let expanded = quote! {
        impl #name {
            pub fn into_message(&self) -> wsforge::Message {
                wsforge::Message::text(serde_json::to_string(self).unwrap())
            }

            pub fn from_message(msg: wsforge::Message) -> Result<Self, serde_json::Error> {
                msg.json::<Self>()
            }
        }
    };

    TokenStream::from(expanded)
}

/// Derives the Handler trait for custom handler types.
///
/// This macro automatically implements the `Handler` trait for your type,
/// delegating to a `handle` method that you must implement. This is useful
/// for creating stateful handlers or handlers with complex initialization.
///
/// # Requirements
///
/// Your type must implement a method with this signature:
///
/// ```
/// async fn handle(
///     &self,
///     message: wsforge::Message,
///     conn: wsforge::Connection,
///     state: wsforge::AppState,
///     extensions: wsforge::Extensions,
/// ) -> wsforge::Result<Option<wsforge::Message>>
/// ```
///
/// # Examples
///
/// ## Simple Handler
///
/// ```
/// use wsforge_macros::WebSocketHandler;
/// use wsforge_core::prelude::*;
///
/// #[derive(WebSocketHandler)]
/// struct EchoHandler;
///
/// impl EchoHandler {
///     async fn handle(
///         &self,
///         message: Message,
///         _conn: Connection,
///         _state: AppState,
///         _extensions: Extensions,
///     ) -> Result<Option<Message>> {
///         Ok(Some(message))
///     }
/// }
/// ```
///
/// ## Stateful Handler
///
/// ```
/// use wsforge_macros::WebSocketHandler;
/// use wsforge_core::prelude::*;
/// use std::sync::Arc;
/// use tokio::sync::RwLock;
///
/// #[derive(WebSocketHandler)]
/// struct CounterHandler {
///     count: Arc<RwLock<u64>>,
/// }
///
/// impl CounterHandler {
///     async fn handle(
///         &self,
///         _message: Message,
///         _conn: Connection,
///         _state: AppState,
///         _extensions: Extensions,
///     ) -> Result<Option<Message>> {
///         let mut count = self.count.write().await;
///         *count += 1;
///         Ok(Some(Message::text(format!("Count: {}", count))))
///     }
/// }
/// ```
///
/// ## With Configuration
///
/// ```
/// use wsforge_macros::WebSocketHandler;
/// use wsforge_core::prelude::*;
///
/// #[derive(WebSocketHandler)]
/// struct ConfiguredHandler {
///     max_length: usize,
/// }
///
/// impl ConfiguredHandler {
///     fn new(max_length: usize) -> Self {
///         Self { max_length }
///     }
///
///     async fn handle(
///         &self,
///         message: Message,
///         _conn: Connection,
///         _state: AppState,
///         _extensions: Extensions,
///     ) -> Result<Option<Message>> {
///         if message.as_bytes().len() > self.max_length {
///             return Err(Error::custom("Message too long"));
///         }
///         Ok(Some(message))
///     }
/// }
/// ```
#[proc_macro_derive(WebSocketHandler)]
pub fn derive_websocket_handler(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;

    let expanded = quote! {
        #[wsforge::async_trait]
        impl wsforge::Handler for #name {
            async fn call(
                &self,
                message: wsforge::Message,
                conn: wsforge::Connection,
                state: wsforge::AppState,
                extensions: wsforge::Extensions,
            ) -> wsforge::Result<Option<wsforge::Message>> {
                self.handle(message, conn, state, extensions).await
            }
        }
    };

    TokenStream::from(expanded)
}

/// Creates a new Router instance.
///
/// This is a simple convenience macro that expands to `Router::new()`.
/// It's provided for consistency with potential future routing macros
/// that may accept declarative route definitions.
///
/// # Usage
///
/// ```
/// use wsforge_macros::routes;
///
/// let router = routes!();
/// // Equivalent to: Router::new()
/// ```
///
/// # Future Enhancement
///
/// This macro may be extended in the future to support declarative routing:
///
/// ```
/// let router = routes! {
///     "/echo" => echo_handler,
///     "/chat" => chat_handler,
///     "/api/*" => api_handler,
/// };
/// ```
///
/// # Examples
///
/// ## Current Usage
///
/// ```
/// use wsforge_macros::routes;
/// use wsforge_core::prelude::*;
///
/// async fn handler(msg: Message) -> Result<String> {
///     Ok("response".to_string())
/// }
///
/// # async fn example() -> Result<()> {
/// let router = routes!()
///     .route("/echo", handler(handler));
///
/// router.listen("127.0.0.1:8080").await?;
/// # Ok(())
/// # }
/// ```
#[proc_macro]
pub fn routes(_input: TokenStream) -> TokenStream {
    let expanded = quote! {
        wsforge::Router::new()
    };

    TokenStream::from(expanded)
}