Crate wsforge_macros 

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

Macros

routes

Creates a new Router instance.

Attribute Macros

websocket_handler

Transforms an async function into a WebSocket handler.

Derive Macros

WebSocketHandler

Derives the Handler trait for custom handler types.

WebSocketMessage

Derives message conversion methods for custom types.