Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RustF Module System User Guide

Complete documentation based on actual framework implementation

Overview

RustF provides a comprehensive module system for organizing business logic, services, and reusable components. The system combines standard Rust module patterns with an optional SharedModule trait and a Total.js-style global MODULE accessor for singleton services. Modules follow clean architecture principles, separating business logic from HTTP request handling.

Key Concepts

  • Standard Rust Modules - Uses regular Rust module system with use statements for direct instantiation
  • Global MODULE System - Total.js-style singleton access by name via MODULE::get("name") for shared services
  • Auto-Discovery - Automatic module scanning with auto_modules!() macro at compile time
  • SharedModule Trait - Optional trait for lifecycle management and type-safe registration
  • Business Logic Separation - Controllers handle HTTP, modules handle business logic
  • Flexible Access Patterns - Choose between direct instantiation or singleton access based on needs

Module Organization

Directory Structure

src/
├── modules/
│   ├── user_service.rs      # User business logic
│   ├── email_service.rs     # Email operations
│   ├── payment_service.rs   # Payment processing
│   └── validation_utils.rs  # Utility functions
├── controllers/             # HTTP handlers
├── models/                  # Data models
└── _modules.rs             # Auto-generated (DO NOT EDIT)

Module Types

The framework recognizes four types of modules:

  1. Services - Stateful business logic with side effects (database operations, external API calls)
  2. Utilities - Stateless pure functions for data transformation and validation
  3. Helpers - Template and view helper functions
  4. Traits - Custom trait definitions and interfaces

Global MODULE System (New)

RustF provides a Total.js-style global MODULE system for singleton access to shared services:

Overview

The MODULE system enables global access to registered modules without passing them through Context or using dependency injection. This is ideal for stateful services that should have a single instance across the entire application.

Basic Usage

Modules are looked up by the name they were registered under (the first argument of MODULE::register), not by type. MODULE::get returns Arc<dyn SharedModule>; to call your own methods, downcast it to the concrete type through SharedModule::as_any():

#![allow(unused)]
fn main() {
// Access modules globally anywhere in your application (by registered name).
// MODULE::get returns Result<Arc<dyn SharedModule>>.
let module = MODULE::get("email-primary")?;

// Downcast to the concrete type to call its methods.
// Keep `module` (the Arc) alive while you use the borrowed `&EmailService`.
let email = module
    .as_any()
    .downcast_ref::<EmailService>()
    .ok_or_else(|| Error::internal("module 'email-primary' is not an EmailService"))?;
email.send_notification("user@example.com").await?;

// Check if a module is registered (by name)
if MODULE::exists("email-primary") {
    // ...
}

// Optional access: get_opt returns Option<Arc<dyn SharedModule>>
if let Some(module) = MODULE::get_opt("email-primary") {
    if let Some(email) = module.as_any().downcast_ref::<EmailService>() {
        email.send_notification("user@example.com").await?;
    }
}

// List all registered modules (useful for debugging)
let modules = MODULE::list();
for (name, module_type) in modules {
    println!("Module: {} ({})", name, module_type);
}
}

When to Use MODULE Registration

Good candidates for MODULE (singleton pattern):

  • Database Connection Pools - Expensive to create, should be shared
  • Cache Services - In-memory caches, Redis connections
  • Email/SMS Services - Configured once, used everywhere
  • WebSocket Managers - Track all active connections
  • Rate Limiters - Shared request counters
  • Background Job Queues - Single task scheduler
  • Metrics Collectors - Application-wide statistics

Use direct instantiation for:

  • Stateless Utilities - Pure functions, no shared state
  • Request-Specific Services - Need new instance per request
  • Simple Validators - Lightweight, no configuration
  • View Helpers - Template formatting functions

Registering Modules for Global Access

To enable MODULE access, register your modules during app initialization:

Modules are not auto-registered. You register each instance explicitly by name using MODULE::register("name", instance) during startup. This is what enables multiple instances of the same type under different names.

// src/main.rs
use rustf::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    use crate::modules::{
        email_service::EmailService,
        cache_service::CacheService,
        database_pool::DatabasePool,
    };

    // MODULE::init() must be called once before any MODULE::register / MODULE::get;
    // the framework does not call it for you.
    MODULE::init()?;

    // Register modules explicitly by unique name. Each becomes a singleton
    // accessible via MODULE::get("name").
    MODULE::register("email-primary", EmailService::new())?;
    MODULE::register("cache", CacheService::new())?;
    MODULE::register("database-pool", DatabasePool::new())?;

    let app = RustF::new()
        .controllers(auto_controllers!())
        .start().await;

    app
}

Note: auto_modules!() only emits module declarations for IDE/auto-discovery support — it does not register modules and evaluates to (), so it cannot be passed to .modules_from(...). If you prefer the closure form, .modules_from takes a closure FnOnce(&mut SharedRegistry) and you call registry.register(...) inside it; modules registered that way get initialize()/shutdown() called by the app but are not reachable through MODULE::get. Explicit MODULE::register("name", instance) (shown above) is the standard approach.

Usage Patterns Comparison

Pattern 1: Direct Instantiation (Simple, Stateless)

#![allow(unused)]
fn main() {
// Best for stateless utilities and simple services
use crate::modules::validation_utils::ValidationUtils;

async fn handler(ctx: &mut Context) -> Result<()> {
    // Create new instance when needed
    let validator = ValidationUtils::new();
    
    if !validator.is_valid_email("user@example.com") {
        return ctx.throw400(Some("Invalid email"));
    }
    
    ctx.json(json!({"status": "valid"}))
}
}

Pattern 2: Global MODULE Access (Singleton, Stateful)

#![allow(unused)]
fn main() {
// Best for shared resources and configured services
async fn handler(ctx: &mut Context) -> Result<()> {
    // Access singleton instances by name, then downcast to the concrete type
    let email_module = MODULE::get("email-primary")?;
    let email_service = email_module
        .as_any()
        .downcast_ref::<EmailService>()
        .ok_or_else(|| Error::internal("module 'email-primary' is not an EmailService"))?;
    let cache_module = MODULE::get("cache")?;
    let cache = cache_module
        .as_any()
        .downcast_ref::<CacheService>()
        .ok_or_else(|| Error::internal("module 'cache' is not a CacheService"))?;
    
    // Check cache first
    if let Some(cached) = cache.get("user:123").await {
        return ctx.json(cached);
    }
    
    // Send email using shared service
    email_service.send_welcome("user@example.com").await?;
    
    ctx.json(json!({"status": "sent"}))
}
}

Pattern 3: Hybrid Approach (Best of Both)

#![allow(unused)]
fn main() {
use crate::modules::{user_service, validation_utils};

async fn handler(ctx: &mut Context) -> Result<()> {
    // Stateless utility - direct instantiation
    let validator = validation_utils::ValidationUtils::new();
    
    // Stateful service - use the MODULE singleton if registered
    let fallback;
    let module = MODULE::get_opt("email-primary");
    let email = match module.as_ref().and_then(|m| m.as_any().downcast_ref::<EmailService>()) {
        // Use singleton if available
        Some(email) => email,
        // Fall back to direct instantiation
        None => {
            fallback = email_service::EmailService::new();
            &fallback
        }
    };
    
    // Business logic...
    email.send_notification("user@example.com").await?;
    
    ctx.json(json!({"status": "processed"}))
}
}

Creating Modules

Basic Module Structure

Every module is a standard Rust module. A new() constructor is the convention. (An install() function is optional and convenient, but note that modules are not auto-registered — you register instances yourself with MODULE::register("name", instance); see Registering Modules for Global Access.)

#![allow(unused)]
fn main() {
// src/modules/user_service.rs
use rustf::prelude::*;

#[derive(Debug)]
pub struct UserService {
    name: String,
}

impl UserService {
    pub fn new() -> Self {
        Self {
            name: "UserService".to_string(),
        }
    }
    
    /// Register a new user with business logic validation
    pub async fn register_user(&self, email: &str, password: &str, profile: Value) -> Result<Value> {
        // Input validation
        if email.is_empty() || !email.contains('@') {
            return Err(Error::validation("Invalid email format"));
        }
        
        if password.len() < 8 {
            return Err(Error::validation("Password must be at least 8 characters"));
        }
        
        // Business logic implementation
        let user = json!({
            "user_id": 1,
            "email": email,
            "created_at": chrono::Utc::now(),
            "is_verified": false
        });
        
        Ok(user)
    }
}

// Optional convenience constructor (modules are NOT auto-registered;
// register explicitly with MODULE::register("user-service", UserService::new())).
pub fn install() -> UserService {
    UserService::new()
}
}

SharedModule Implementation (Optional)

For advanced lifecycle management, implement the SharedModule trait:

#![allow(unused)]
fn main() {
use rustf::prelude::*;
use async_trait::async_trait;

#[derive(Debug)]
pub struct EmailService {
    templates: HashMap<String, String>,
}

impl EmailService {
    pub fn new() -> Self {
        let mut templates = HashMap::new();
        templates.insert("welcome".to_string(), 
            "Welcome {{name}}! Please verify: {{link}}".to_string());
        
        Self { templates }
    }
    
    pub async fn send_verification_email(&self, email: &str, name: &str, token: &str) -> Result<Value> {
        let template = self.templates.get("welcome").unwrap();
        let rendered = template
            .replace("{{name}}", name)
            .replace("{{link}}", &format!("https://app.com/verify?token={}", token));
            
        // In production: integrate with email provider
        log::info!("Sending verification email to {}: {}", email, rendered);
        
        Ok(json!({
            "email": email,
            "status": "sent",
            "message_id": uuid::Uuid::new_v4()
        }))
    }
}

#[async_trait]
impl SharedModule for EmailService {
    fn name(&self) -> &'static str {
        "EmailService"
    }
    
    fn module_type(&self) -> SharedModuleType {
        SharedModuleType::Service
    }
    
    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
    
    async fn initialize(&self) -> Result<()> {
        log::info!("EmailService initialized with {} templates", self.templates.len());
        Ok(())
    }
}

pub fn install() -> EmailService {
    EmailService::new()
}
}

Utility Modules

For stateless utilities, use the convenience macro:

#![allow(unused)]
fn main() {
// src/modules/validation_utils.rs
use rustf::prelude::*;

pub struct ValidationUtils;

impl ValidationUtils {
    /// Validate email format
    pub fn is_valid_email(email: &str) -> bool {
        email.contains('@') && email.len() > 5
    }
    
    /// Validate password strength
    pub fn is_strong_password(password: &str) -> bool {
        password.len() >= 8 
            && password.chars().any(|c| c.is_uppercase())
            && password.chars().any(|c| c.is_lowercase())
            && password.chars().any(|c| c.is_numeric())
    }
    
    /// Sanitize user input
    pub fn sanitize_input(input: &str) -> String {
        input.trim()
            .replace("<", "&lt;")
            .replace(">", "&gt;")
            .replace("&", "&amp;")
    }
}

// Use convenience macro for simple implementation
impl_shared_util!(ValidationUtils);

pub fn install() -> ValidationUtils {
    ValidationUtils
}
}

Module Discovery and Registration

Module Discovery with auto_modules!()

auto_modules!() discovers modules at compile time for IDE support only. It emits the src/modules/* module declarations but does not register anything — it evaluates to (), so it cannot be passed to .modules_from(...). Registration is always explicit via MODULE::register(...):

// src/main.rs
use rustf::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    MODULE::init()?;
    // Register stateful modules explicitly by name (singletons via MODULE::get).
    MODULE::register("user-service", crate::modules::user_service::UserService::new())?;

    let app = RustF::new()
        .controllers(auto_controllers!())
        .models(auto_models!())
        .start().await;

    app
}

What actually happens:

  1. auto_modules!() scans src/modules/ at compile time and emits module declarations for IDE/auto-discovery support only (no registration).
  2. You call MODULE::register("name", instance) for each module you want globally accessible. This is required — there is no automatic registration.
  3. MODULE::init() must be called by your app before registering; the framework does not call it.
  4. Registered modules become singletons accessible by name via MODULE::get("name") (downcast with as_any().downcast_ref::<T>() for the concrete type).

Manual Module Access

Recommended Pattern: Use standard Rust module system for accessing business logic:

#![allow(unused)]
fn main() {
// src/controllers/auth.rs
use rustf::prelude::*;
use crate::modules::{user_service, email_service};

pub fn install() -> Vec<Route> {
    routes![
        POST "/register" => register_user,
        POST "/login" => login_user,
    ]
}

async fn register_user(ctx: &mut Context) -> rustf::Result<()> {
    let form_data = ctx.body_form()?;
    let email = form_data.get("email").unwrap_or("");
    let password = form_data.get("password").unwrap_or("");
    
    // Access modules using standard Rust module system
    let user_svc = user_service::UserService::new();
    let email_svc = email_service::EmailService::new();
    
    // Business logic handled by modules
    match user_svc.register_user(email, password, json!({})).await {
        Ok(user) => {
            // Send verification email
            let _ = email_svc.send_verification_email(
                email, 
                "New User", 
                "verification_token_123"
            ).await;
            
            ctx.flash_success("Registration successful! Check your email.")?;
            ctx.redirect("/login")
        }
        Err(e) => {
            ctx.flash_error(format!("Registration failed: {}", e))?;
            ctx.redirect("/register")
        }
    }
}
}

Explicit Registration Pattern

The global MODULE system has its own registry (separate from the app’s SharedRegistry). Registration is explicit:

// src/main.rs
use rustf::prelude::*;

#[rustf::auto_discover]
#[tokio::main]
async fn main() -> Result<()> {
    // Explicit registration by name (no automatic registration).
    MODULE::init()?;
    MODULE::register("email-primary", crate::modules::email_service::EmailService::new())?;

    let app = RustF::new()
        .controllers(auto_controllers!())
        .models(auto_models!())
        .start().await;

    app
}

What happens:

  1. auto_modules!() only emits module declarations for IDE support — it does not register modules and cannot be passed to .modules_from(...).
  2. You register modules explicitly with MODULE::register("name", instance).
  3. app.start() does not call initialize() on MODULE-registered modules (it only does so for modules added to the app’s SharedRegistry via .modules_from(...)).
  4. Modules are available throughout the application lifecycle via MODULE::get("name").

Using Modules in Controllers

Pattern 1: Direct Instantiation (Simple)

Controllers create module instances directly for clear, simple code:

#![allow(unused)]
fn main() {
// src/controllers/users.rs
use rustf::prelude::*;
use crate::modules::{user_service, validation_utils};

async fn create_user(ctx: &mut Context) -> rustf::Result<()> {
    let form_data = ctx.body_form()?;
    let email = form_data.get("email").unwrap_or("");
    let password = form_data.get("password").unwrap_or("");
    
    // Use validation utilities
    if !validation_utils::ValidationUtils::is_valid_email(email) {
        ctx.flash_error("Invalid email format")?;
        return ctx.redirect("/users/new");
    }
    
    if !validation_utils::ValidationUtils::is_strong_password(password) {
        ctx.flash_error("Password must be at least 8 characters with mixed case and numbers")?;
        return ctx.redirect("/users/new");
    }
    
    // Use business service
    let user_svc = user_service::UserService::new();
    match user_svc.register_user(email, password, json!({})).await {
        Ok(user) => {
            ctx.flash_success("User created successfully!")?;
            ctx.redirect("/users")
        }
        Err(e) => {
            ctx.flash_error(format!("Failed to create user: {}", e))?;
            ctx.redirect("/users/new")
        }
    }
}
}

Pattern 2: Global MODULE Access (Singleton)

Use MODULE for shared services that should have one instance:

#![allow(unused)]
fn main() {
// src/controllers/api.rs
use rustf::prelude::*;

async fn process_order(ctx: &mut Context) -> Result<()> {
    // Access singleton services via MODULE (by registered name), downcast to concrete types
    let cache_module = MODULE::get("cache")?;
    let cache = cache_module.as_any().downcast_ref::<CacheService>()
        .ok_or_else(|| Error::internal("module 'cache' is not a CacheService"))?;
    let email_module = MODULE::get("email-primary")?;
    let email = email_module.as_any().downcast_ref::<EmailService>()
        .ok_or_else(|| Error::internal("module 'email-primary' is not an EmailService"))?;
    let payment_module = MODULE::get("payment")?;
    let payment = payment_module.as_any().downcast_ref::<PaymentService>()
        .ok_or_else(|| Error::internal("module 'payment' is not a PaymentService"))?;
    
    let order_data: Value = ctx.body_json()?;
    let order_id = order_data["id"].as_str().unwrap_or("");
    
    // Check cache for duplicate order
    if cache.exists(&format!("order:{}", order_id)).await {
        return ctx.throw400(Some("Duplicate order"));
    }
    
    // Process payment using singleton service
    let payment_result = payment.process(
        order_data["amount"].as_u64().unwrap_or(0),
        order_data["token"].as_str().unwrap_or("")
    ).await?;
    
    // Send confirmation email
    email.send_order_confirmation(
        order_data["email"].as_str().unwrap_or(""),
        order_id
    ).await?;
    
    // Cache the order
    cache.set(&format!("order:{}", order_id), &order_data, 3600).await?;
    
    ctx.json(json!({
        "status": "processed",
        "payment_id": payment_result.id
    }))
}
}

Pattern 3: Dependency Injection Pattern

For applications requiring shared state, pass dependencies explicitly:

#![allow(unused)]
fn main() {
// src/controllers/api.rs
use rustf::prelude::*;
use crate::modules::user_service::UserService;

// Service container approach
pub struct ApiServices {
    user_service: UserService,
    // other services...
}

impl ApiServices {
    pub fn new() -> Self {
        Self {
            user_service: UserService::new(),
        }
    }
}

async fn api_create_user(ctx: &mut Context) -> rustf::Result<()> {
    let services = ApiServices::new();
    let request_data: Value = ctx.body_json()?;
    
    let email = request_data["email"].as_str().unwrap_or("");
    let password = request_data["password"].as_str().unwrap_or("");
    
    match services.user_service.register_user(email, password, json!({})).await {
        Ok(user) => ctx.json(json!({
            "success": true,
            "user": user
        })),
        Err(e) => ctx.json(json!({
            "success": false,
            "error": e.to_string()
        }))
    }
}
}

Module Patterns and Best Practices

1. Service Pattern (Stateful Business Logic)

#![allow(unused)]
fn main() {
// src/modules/order_service.rs
use rustf::prelude::*;

#[derive(Debug)]
pub struct OrderService {
    config: OrderConfig,
}

#[derive(Debug)]
pub struct OrderConfig {
    pub max_items: usize,
    pub tax_rate: f64,
}

impl OrderService {
    pub fn new() -> Self {
        Self {
            config: OrderConfig {
                max_items: 100,
                tax_rate: 0.08,
            },
        }
    }
    
    pub async fn create_order(&self, user_id: i64, items: Vec<OrderItem>) -> Result<Order> {
        // Business validation
        if items.len() > self.config.max_items {
            return Err(Error::validation("Too many items in order"));
        }
        
        // Calculate totals
        let subtotal: f64 = items.iter().map(|item| item.price * item.quantity as f64).sum();
        let tax = subtotal * self.config.tax_rate;
        let total = subtotal + tax;
        
        // Create order (in real app: save to database)
        let order = Order {
            id: 1,
            user_id,
            items,
            subtotal,
            tax,
            total,
            status: OrderStatus::Pending,
            created_at: chrono::Utc::now(),
        };
        
        log::info!("Created order {} for user {} (total: ${:.2})", order.id, user_id, total);
        Ok(order)
    }
    
    pub async fn calculate_shipping(&self, order: &Order, address: &Address) -> Result<f64> {
        // Shipping calculation logic
        let base_rate = 5.99;
        let weight_factor = order.items.len() as f64 * 0.5;
        Ok(base_rate + weight_factor)
    }
}

#[derive(Debug, Serialize)]
pub struct Order {
    pub id: i64,
    pub user_id: i64,
    pub items: Vec<OrderItem>,
    pub subtotal: f64,
    pub tax: f64,
    pub total: f64,
    pub status: OrderStatus,
    pub created_at: chrono::DateTime<chrono::Utc>,
}

pub fn install() -> OrderService {
    OrderService::new()
}
}

2. Utility Pattern (Stateless Functions)

#![allow(unused)]
fn main() {
// src/modules/text_utils.rs
use rustf::prelude::*;

pub struct TextUtils;

impl TextUtils {
    /// Convert text to URL-friendly slug
    pub fn slugify(text: &str) -> String {
        text.to_lowercase()
            .chars()
            .map(|c| if c.is_alphanumeric() { c } else { '-' })
            .collect::<String>()
            .split('-')
            .filter(|s| !s.is_empty())
            .collect::<Vec<&str>>()
            .join("-")
    }
    
    /// Truncate text with ellipsis
    pub fn truncate(text: &str, max_length: usize) -> String {
        if text.len() <= max_length {
            text.to_string()
        } else {
            format!("{}...", &text[..max_length - 3])
        }
    }
    
    /// Extract mentions from text (@username)
    pub fn extract_mentions(text: &str) -> Vec<String> {
        let re = regex::Regex::new(r"@(\w+)").unwrap();
        re.captures_iter(text)
            .map(|cap| cap[1].to_string())
            .collect()
    }
    
    /// Generate random string
    pub fn random_string(length: usize) -> String {
        use rand::Rng;
        const CHARSET: &[u8] = b"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
        let mut rng = rand::thread_rng();
        (0..length)
            .map(|_| {
                let idx = rng.gen_range(0..CHARSET.len());
                CHARSET[idx] as char
            })
            .collect()
    }
}

impl_shared_util!(TextUtils);

pub fn install() -> TextUtils {
    TextUtils
}
}

3. Helper Pattern (View Helpers)

#![allow(unused)]
fn main() {
// src/modules/view_helpers.rs
use rustf::prelude::*;

pub struct ViewHelpers;

impl ViewHelpers {
    /// Format currency for display
    pub fn format_currency(amount: f64, currency: &str) -> String {
        match currency {
            "USD" => format!("${:.2}", amount),
            "EUR" => format!("€{:.2}", amount),
            "GBP" => format!("£{:.2}", amount),
            _ => format!("{:.2} {}", amount, currency),
        }
    }
    
    /// Format relative time (e.g., "2 hours ago")
    pub fn time_ago(datetime: &chrono::DateTime<chrono::Utc>) -> String {
        let now = chrono::Utc::now();
        let duration = now.signed_duration_since(*datetime);
        
        if duration.num_days() > 7 {
            datetime.format("%Y-%m-%d").to_string()
        } else if duration.num_days() > 0 {
            format!("{} days ago", duration.num_days())
        } else if duration.num_hours() > 0 {
            format!("{} hours ago", duration.num_hours())
        } else if duration.num_minutes() > 0 {
            format!("{} minutes ago", duration.num_minutes())
        } else {
            "Just now".to_string()
        }
    }
    
    /// Generate avatar URL from email
    pub fn gravatar_url(email: &str, size: u32) -> String {
        let hash = md5::compute(email.trim().to_lowercase().as_bytes());
        format!("https://www.gravatar.com/avatar/{:x}?s={}&d=identicon", hash, size)
    }
    
    /// Pluralize words based on count
    pub fn pluralize(word: &str, count: usize) -> String {
        if count == 1 {
            word.to_string()
        } else if word.ends_with('y') {
            format!("{}ies", &word[..word.len()-1])
        } else if word.ends_with(&['s', 'x', 'z']) || word.ends_with("ch") || word.ends_with("sh") {
            format!("{}es", word)
        } else {
            format!("{}s", word)
        }
    }
}

impl_shared_helper!(ViewHelpers);

pub fn install() -> ViewHelpers {
    ViewHelpers
}
}

Advanced Features

Module Lifecycle Management

For modules requiring initialization and cleanup:

#![allow(unused)]
fn main() {
// src/modules/cache_service.rs
use rustf::prelude::*;

#[derive(Debug)]
pub struct CacheService {
    redis_client: Option<redis::Client>,
    memory_cache: HashMap<String, CacheEntry>,
}

#[derive(Debug, Clone)]
struct CacheEntry {
    value: String,
    expires_at: chrono::DateTime<chrono::Utc>,
}

impl CacheService {
    pub fn new() -> Self {
        Self {
            redis_client: None,
            memory_cache: HashMap::new(),
        }
    }
    
    pub async fn get(&self, key: &str) -> Option<String> {
        // Try memory cache first
        if let Some(entry) = self.memory_cache.get(key) {
            if entry.expires_at > chrono::Utc::now() {
                return Some(entry.value.clone());
            }
        }
        
        // Fall back to Redis if available
        None // Simplified for example
    }
    
    pub async fn set(&mut self, key: &str, value: &str, ttl_seconds: u64) -> Result<()> {
        let expires_at = chrono::Utc::now() + chrono::Duration::seconds(ttl_seconds as i64);
        self.memory_cache.insert(key.to_string(), CacheEntry {
            value: value.to_string(),
            expires_at,
        });
        Ok(())
    }
}

#[async_trait]
impl SharedModule for CacheService {
    fn name(&self) -> &'static str {
        "CacheService"
    }
    
    fn module_type(&self) -> SharedModuleType {
        SharedModuleType::Service
    }
    
    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
    
    async fn initialize(&self) -> Result<()> {
        log::info!("CacheService initializing...");
        
        // Initialize Redis connection
        if let Ok(redis_url) = std::env::var("REDIS_URL") {
            match redis::Client::open(redis_url) {
                Ok(_client) => log::info!("Redis cache client initialized"),
                Err(e) => log::warn!("Failed to initialize Redis: {}", e),
            }
        }
        
        log::info!("CacheService initialized successfully");
        Ok(())
    }
    
    async fn shutdown(&self) -> Result<()> {
        log::info!("CacheService shutting down...");
        // Cleanup operations would go here
        Ok(())
    }
}

pub fn install() -> CacheService {
    CacheService::new()
}
}

Cross-Module Dependencies

Modules can depend on each other using standard Rust patterns:

#![allow(unused)]
fn main() {
// src/modules/notification_service.rs
use rustf::prelude::*;
use super::email_service::EmailService;

#[derive(Debug)]
pub struct NotificationService {
    email_service: EmailService,
}

impl NotificationService {
    pub fn new() -> Self {
        Self {
            email_service: EmailService::new(),
        }
    }
    
    pub async fn send_welcome_notification(&self, user_email: &str, user_name: &str) -> Result<()> {
        // Send email notification
        self.email_service.send_verification_email(user_email, user_name, "welcome_token").await?;
        
        // Could also send push notification, SMS, etc.
        log::info!("Welcome notification sent to {}", user_email);
        Ok(())
    }
    
    pub async fn send_order_confirmation(&self, user_email: &str, order_id: i64) -> Result<()> {
        // Complex notification logic using email service
        let subject = format!("Order #{} confirmed", order_id);
        // Implementation details...
        Ok(())
    }
}

pub fn install() -> NotificationService {
    NotificationService::new()
}
}

Testing Modules

Unit Testing Services

#![allow(unused)]
fn main() {
// src/modules/user_service.rs
#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_register_user_valid() {
        let service = UserService::new();
        let result = service.register_user(
            "test@example.com", 
            "password123", 
            json!({})
        ).await;
        
        assert!(result.is_ok());
        let user = result.unwrap();
        assert_eq!(user["email"], "test@example.com");
        assert_eq!(user["is_verified"], false);
    }
    
    #[tokio::test]
    async fn test_register_user_invalid_email() {
        let service = UserService::new();
        let result = service.register_user(
            "invalid-email", 
            "password123", 
            json!({})
        ).await;
        
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("Invalid email format"));
    }
    
    #[tokio::test]
    async fn test_register_user_weak_password() {
        let service = UserService::new();
        let result = service.register_user(
            "test@example.com", 
            "123", 
            json!({})
        ).await;
        
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("at least 8 characters"));
    }
}
}

Integration Testing

#![allow(unused)]
fn main() {
// tests/module_tests.rs
use rustf::prelude::*;
use your_app::modules::{user_service, email_service};

#[tokio::test]
async fn test_user_registration_flow() {
    // Setup
    let user_svc = user_service::UserService::new();
    let email_svc = email_service::EmailService::new();
    
    // Test user registration
    let user_result = user_svc.register_user(
        "integration@test.com",
        "TestPassword123",
        json!({"first_name": "Test", "last_name": "User"})
    ).await;
    
    assert!(user_result.is_ok());
    let user = user_result.unwrap();
    
    // Test email notification
    let email_result = email_svc.send_verification_email(
        "integration@test.com",
        "Test",
        "test_token_123"
    ).await;
    
    assert!(email_result.is_ok());
    let email_response = email_result.unwrap();
    assert_eq!(email_response["email"]["status"], "sent");
}
}

Configuration

Environment-Based Module Configuration

#![allow(unused)]
fn main() {
// src/modules/payment_service.rs
use rustf::prelude::*;

#[derive(Debug)]
pub struct PaymentService {
    stripe_key: Option<String>,
    sandbox_mode: bool,
}

impl PaymentService {
    pub fn new() -> Self {
        let stripe_key = std::env::var("STRIPE_SECRET_KEY").ok();
        let sandbox_mode = std::env::var("PAYMENT_SANDBOX")
            .unwrap_or_else(|_| "false".to_string())
            .parse()
            .unwrap_or(false);
            
        Self {
            stripe_key,
            sandbox_mode,
        }
    }
    
    pub async fn process_payment(&self, amount: u64, token: &str) -> Result<PaymentResult> {
        if self.sandbox_mode {
            log::info!("SANDBOX: Processing payment of ${} with token {}", amount, token);
            return Ok(PaymentResult {
                id: "sandbox_payment_123".to_string(),
                status: PaymentStatus::Succeeded,
                amount,
            });
        }
        
        // Real payment processing logic
        match &self.stripe_key {
            Some(key) => {
                // Use Stripe API
                log::info!("Processing real payment with Stripe");
                // Implementation...
                Ok(PaymentResult {
                    id: "real_payment_456".to_string(),
                    status: PaymentStatus::Succeeded,
                    amount,
                })
            }
            None => {
                Err(Error::configuration("STRIPE_SECRET_KEY not configured"))
            }
        }
    }
}

pub fn install() -> PaymentService {
    PaymentService::new()
}
}

Module Documentation Patterns

Self-Documenting Modules

#![allow(unused)]
fn main() {
// src/modules/analytics_service.rs
//! Analytics Service Module
//! 
//! Provides comprehensive analytics tracking and reporting functionality.
//! 
//! ## Features
//! - Event tracking with custom properties
//! - User behavior analytics
//! - Performance metrics collection
//! - A/B testing support
//! 
//! ## Usage
//! ```rust
//! use crate::modules::analytics_service::AnalyticsService;
//! 
//! let analytics = AnalyticsService::new();
//! analytics.track_event("user_signup", json!({"source": "web"})).await?;
//! ```

use rustf::prelude::*;

/// Analytics service for tracking user events and system metrics
/// 
/// The AnalyticsService provides methods for tracking various types of events:
/// - User actions (clicks, page views, form submissions)
/// - System events (errors, performance metrics)  
/// - Custom business events (purchases, subscriptions)
#[derive(Debug)]
pub struct AnalyticsService {
    /// Whether analytics is enabled (can be disabled for testing)
    enabled: bool,
    /// Buffer for batching events before sending
    event_buffer: Vec<AnalyticsEvent>,
}

#[derive(Debug, Serialize)]
pub struct AnalyticsEvent {
    pub event_name: String,
    pub properties: Value,
    pub user_id: Option<String>,
    pub session_id: Option<String>,
    pub timestamp: chrono::DateTime<chrono::Utc>,
}

impl AnalyticsService {
    /// Create new analytics service
    /// 
    /// # Example
    /// ```rust
    /// let analytics = AnalyticsService::new();
    /// ```
    pub fn new() -> Self {
        let enabled = std::env::var("ANALYTICS_ENABLED")
            .unwrap_or_else(|_| "true".to_string())
            .parse()
            .unwrap_or(true);
            
        Self {
            enabled,
            event_buffer: Vec::new(),
        }
    }
    
    /// Track a user event with optional properties
    /// 
    /// # Arguments
    /// * `event_name` - Name of the event (e.g., "page_view", "button_click")
    /// * `properties` - Additional event data as JSON
    /// 
    /// # Example
    /// ```rust
    /// analytics.track_event("user_signup", json!({
    ///     "source": "web",
    ///     "plan": "premium"
    /// })).await?;
    /// ```
    pub async fn track_event(&mut self, event_name: &str, properties: Value) -> Result<()> {
        if !self.enabled {
            return Ok(());
        }
        
        let event = AnalyticsEvent {
            event_name: event_name.to_string(),
            properties,
            user_id: None, // Would be set from context in real implementation
            session_id: None,
            timestamp: chrono::Utc::now(),
        };
        
        self.event_buffer.push(event);
        
        // Flush buffer if it gets too large
        if self.event_buffer.len() >= 100 {
            self.flush_events().await?;
        }
        
        Ok(())
    }
    
    /// Flush buffered events to analytics provider
    async fn flush_events(&mut self) -> Result<()> {
        if self.event_buffer.is_empty() {
            return Ok(());
        }
        
        log::info!("Flushing {} analytics events", self.event_buffer.len());
        
        // In real implementation: send to analytics provider
        // Google Analytics, Mixpanel, Segment, etc.
        
        self.event_buffer.clear();
        Ok(())
    }
}

pub fn install() -> AnalyticsService {
    AnalyticsService::new()
}
}

Error Handling in Modules

Consistent Error Patterns

#![allow(unused)]
fn main() {
// src/modules/file_service.rs
use rustf::prelude::*;
use std::path::PathBuf;

#[derive(Debug)]
pub struct FileService {
    upload_path: PathBuf,
    max_file_size: usize,
}

impl FileService {
    pub fn new() -> Self {
        let upload_path = std::env::var("UPLOAD_PATH")
            .unwrap_or_else(|_| "uploads".to_string())
            .into();
            
        let max_file_size = std::env::var("MAX_FILE_SIZE")
            .unwrap_or_else(|_| "10485760".to_string()) // 10MB default
            .parse()
            .unwrap_or(10485760);
            
        Self {
            upload_path,
            max_file_size,
        }
    }
    
    pub async fn save_upload(&self, file_data: &[u8], filename: &str) -> Result<FileUploadResult> {
        // Validation
        if file_data.is_empty() {
            return Err(Error::validation("File cannot be empty"));
        }
        
        if file_data.len() > self.max_file_size {
            return Err(Error::validation(&format!(
                "File size {} exceeds maximum allowed size {}", 
                file_data.len(), 
                self.max_file_size
            )));
        }
        
        // Security: validate filename
        if filename.contains("..") || filename.contains("/") || filename.contains("\\") {
            return Err(Error::security("Invalid filename"));
        }
        
        // Generate unique filename
        let unique_filename = format!("{}_{}", 
            uuid::Uuid::new_v4(), 
            filename
        );
        
        let file_path = self.upload_path.join(&unique_filename);
        
        // Ensure upload directory exists
        if let Some(parent) = file_path.parent() {
            std::fs::create_dir_all(parent)
                .map_err(|e| Error::filesystem(&format!("Failed to create upload directory: {}", e)))?;
        }
        
        // Save file
        std::fs::write(&file_path, file_data)
            .map_err(|e| Error::filesystem(&format!("Failed to save file: {}", e)))?;
        
        log::info!("File saved: {} ({} bytes)", unique_filename, file_data.len());
        
        Ok(FileUploadResult {
            filename: unique_filename,
            path: file_path.to_string_lossy().to_string(),
            size: file_data.len(),
            mime_type: self.detect_mime_type(filename),
        })
    }
    
    fn detect_mime_type(&self, filename: &str) -> String {
        match filename.split('.').last() {
            Some("jpg") | Some("jpeg") => "image/jpeg".to_string(),
            Some("png") => "image/png".to_string(),
            Some("gif") => "image/gif".to_string(),
            Some("pdf") => "application/pdf".to_string(),
            Some("txt") => "text/plain".to_string(),
            _ => "application/octet-stream".to_string(),
        }
    }
}

#[derive(Debug, Serialize)]
pub struct FileUploadResult {
    pub filename: String,
    pub path: String,
    pub size: usize,
    pub mime_type: String,
}

pub fn install() -> FileService {
    FileService::new()
}
}

Best Practices Summary

1. Module Design Principles

  • Single Responsibility - Each module handles one domain of business logic
  • Clear Interfaces - Public methods are well-documented and consistent
  • Error Handling - Use Result<T> for operations that can fail
  • Configuration - Use environment variables for runtime configuration
  • Logging - Include appropriate logging for debugging and monitoring

2. Code Organization

#![allow(unused)]
fn main() {
// ✅ Good: Clear module structure
// src/modules/
//   ├── user_service.rs        # User domain logic
//   ├── order_service.rs       # Order processing
//   ├── payment_service.rs     # Payment handling
//   ├── email_service.rs       # Email operations
//   └── validation_utils.rs    # Shared utilities

// ❌ Bad: Mixed concerns
// src/modules/
//   └── everything_service.rs  # Handles users, orders, payments, etc.
}

3. Dependencies and Coupling

#![allow(unused)]
fn main() {
// ✅ Good: Explicit dependencies
use crate::modules::email_service::EmailService;

pub struct UserService {
    email_service: EmailService,
}

// ❌ Bad: Hidden global state
pub struct UserService;

impl UserService {
    pub async fn register_user(&self, email: &str) -> Result<User> {
        // Hidden dependency on global email service
        GLOBAL_EMAIL_SERVICE.send_welcome(email).await?;
    }
}
}

4. Testing Strategy

#![allow(unused)]
fn main() {
// ✅ Good: Testable design
impl PaymentService {
    pub fn new_for_testing() -> Self {
        Self {
            stripe_key: None,
            sandbox_mode: true, // Always sandbox for tests
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_payment_processing() {
        let service = PaymentService::new_for_testing();
        // Test implementation
    }
}
}

Migration and Compatibility

From Older Module Systems

If migrating from other Rust web frameworks:

#![allow(unused)]
fn main() {
// Actix Web style -> RustF style
// Old:
// web::Data<EmailService>

// New:
use crate::modules::email_service::EmailService;
let email_service = EmailService::new();
}

Framework Agnostic Modules

Keep business logic independent of RustF specifics:

#![allow(unused)]
fn main() {
// ✅ Good: Framework-independent core logic
impl UserService {
    pub async fn validate_and_create_user(&self, email: &str, password: &str) -> Result<User> {
        // Core business logic - no RustF dependencies
        // Can be used in CLI tools, tests, other frameworks
    }
}

// ✅ Good: the controller handler owns the HTTP side and builds the response
async fn create_user(ctx: &mut Context) -> Result<()> {
    let form = ctx.body_form()?;
    let email = form.get("email").unwrap_or("").to_string();
    let password = form.get("password").unwrap_or("").to_string();

    let user = UserService::new().validate_and_create_user(&email, &password).await?;
    ctx.json(json!({ "id": user.id }))
}

// ❌ Bad: Tightly coupled to RustF
impl UserService {
    pub async fn create_user(&self, ctx: &mut Context) -> Result<()> {
        // Mixing business logic with HTTP concerns (reads the request,
        // writes the response) - belongs in the controller, not the module
    }
}
}

Framework Integration Status

Based on the current RustF implementation:

✅ SharedModule Trait - Complete implementation in src/shared.rs
✅ SharedRegistry - Full registry with lifecycle management
✅ Module Types - Service, Util, Helper, Trait categorization
✅ Auto-discovery macro - auto_modules!() in rustf-macros
✅ Standard Rust modules - Normal use statement access
✅ Lifecycle management - Initialize/shutdown methods
✅ App Integration - SharedRegistry integrated with RustF app builder pattern
✅ CLI Support - rustf-cli new creates src/modules/ directory with README
✅ Global MODULE System - Total.js-style singleton access by name via MODULE::get("name")
✅ Name-Based Access - MODULE::get / MODULE::get_opt return Arc<dyn SharedModule>; downcast via as_any().downcast_ref::<T>()
✅ MODULE Initialization - Explicit MODULE::init() call in your app startup
✅ Dynamic Module Discovery - MODULE::list() and MODULE::exists("name") methods

Usage Recommendations

For most applications:

  1. Register stateful modules explicitly with MODULE::register("name", instance) at startup (auto_modules!() only provides IDE discovery; it does not register modules)
  2. Create services as structs with new() constructors
  3. For stateless utilities: Use direct instantiation with use statements
  4. For stateful services: Register and access by name via MODULE::get("name") + as_any().downcast_ref::<T>()

Choosing between direct instantiation and MODULE:

  1. Use MODULE for:

    • Database connection pools
    • Cache services (Redis, in-memory)
    • Configured services (email, SMS, payment)
    • Services with expensive initialization
    • Resources that should be shared application-wide
  2. Use direct instantiation for:

    • Stateless utility functions
    • Request-specific services
    • Simple validators and formatters
    • Services that don’t need configuration

For simple modules that don’t need lifecycle management:

  1. Create basic structs with static methods
  2. Use impl_shared_util!() macro for utilities
  3. Access directly via standard Rust module imports

For complex services requiring singleton behavior:

  1. Implement SharedModule trait with initialize() and shutdown() methods
  2. Register with MODULE::register("name", instance) (after MODULE::init()) to enable MODULE access
  3. Access by name via MODULE::get("name") + as_any().downcast_ref::<T>() throughout the application
  4. initialize() / shutdown() are called automatically only for modules registered through .modules_from()

The module system now provides full integration with the framework while maintaining flexibility for both simple and complex use cases, with clean separation of concerns between HTTP handling (controllers) and business logic (modules).

Summary

RustF’s module system provides:

✅ Clean Architecture - Separation of business logic from HTTP concerns
✅ Standard Rust Patterns - Uses familiar module system and traits
✅ Auto-Discovery - Compile-time scanning of module directories
✅ Type Safety - Compile-time validation of module interfaces
✅ Lifecycle Management - Optional initialize/shutdown methods
✅ Global MODULE System - Total.js-style singleton access for shared services
✅ Flexible Access Patterns - Support for both direct instantiation and singleton access
✅ Testing Support - Easy to unit test individual modules
✅ Resource Efficiency - Singleton pattern for expensive resources

The system strikes a balance between simplicity and power, offering multiple patterns:

  • Direct instantiation for simple, stateless utilities
  • Global MODULE access for shared, stateful services
  • Hybrid approaches for maximum flexibility

This allows developers to organize business logic effectively while maintaining clean architecture principles that make applications maintainable, testable, and resource-efficient.