Rustelo/book/features/overview.md

Features Overview

Rustelo is built around a modular feature system that allows you to enable only the functionality you need. This approach keeps your application lean, reduces compile times, and ensures you're not carrying unnecessary dependencies.

Philosophy

The feature system is designed with these principles in mind:

• 🎯 Opt-in by Design: Start minimal and add features as needed
• 🔧 Zero Configuration: Features work out of the box with sensible defaults
• 📦 Minimal Dependencies: Each feature only includes what it absolutely needs
• 🔄 Composable: Features work together seamlessly
• 🛡️ Secure by Default: Security considerations built into every feature

Feature Categories

Core Features (Always Available)

These features are always available regardless of your configuration:

• Static File Serving: Serve static assets (CSS, JS, images)
• Routing: Client-side and server-side routing
• CSRF Protection: Cross-site request forgery protection
• Security Headers: Basic security headers
• Rate Limiting: Basic rate limiting
• Health Checks: System health monitoring endpoints
• Logging: Structured logging with tracing

Optional Features

🔐 Authentication (auth)

Default: Enabled

Complete user authentication and authorization system.

What it provides:

• JWT token-based authentication
• OAuth2 integration (Google, GitHub, etc.)
• Two-factor authentication (2FA/TOTP)
• Password hashing with Argon2
• Session management
• User registration and login
• Password reset functionality
• Role-based access control (RBAC)

Use cases:

• User portals and dashboards
• SaaS applications
• Protected content areas
• Multi-tenant applications

Dependencies:

• jsonwebtoken - JWT handling
• argon2 - Secure password hashing
• oauth2 - OAuth2 client implementation
• totp-rs - Two-factor authentication
• qrcode - QR code generation
• tower-sessions - Session management

📄 Content Management (content-db)

Default: Enabled

Database-driven content management with Markdown support.

What it provides:

• Markdown content rendering
• Syntax highlighting for code blocks
• YAML frontmatter support
• Content caching system
• Dynamic content loading
• Content versioning
• SEO-friendly URLs
• Full-text search capabilities

Use cases:

• Blogs and news sites
• Documentation sites
• Content management systems
• Marketing websites
• Knowledge bases

Dependencies:

• pulldown-cmark - Markdown parsing
• syntect - Syntax highlighting
• serde_yaml - YAML frontmatter
• sqlx - Database access

🔒 TLS Support (tls)

Default: Disabled

HTTPS/TLS encryption for secure connections.

What it provides:

• HTTPS server support
• TLS certificate management
• Automatic HTTP to HTTPS redirects
• SSL/TLS configuration
• Certificate validation
• Support for Let's Encrypt certificates

Use cases:

• Production deployments
• Security-sensitive applications
• Compliance requirements
• E-commerce applications

Dependencies:

• axum-server - TLS-enabled server
• rustls - Pure Rust TLS implementation
• rustls-pemfile - Certificate file handling

📧 Email System (email)

Default: Enabled

Comprehensive email functionality with multiple providers.

What it provides:

• Multiple email providers (SMTP, SendGrid, AWS SES)
• HTML and text email templates
• Contact form handling
• Email verification
• Password reset emails
• Notification system
• Email queue management
• Bounce handling

Use cases:

• Contact forms
• User notifications
• Marketing emails
• Transactional emails
• Newsletter systems

Dependencies:

• lettre - Email sending
• handlebars - Email templating
• urlencoding - URL encoding
• async-trait - Async trait support

Feature Combinations

Common Combinations

Minimal Static Site

cargo build --no-default-features

Perfect for:

• Marketing websites
• Landing pages
• Documentation sites
• Portfolio sites

Features included:

• Static file serving
• Basic routing
• Security headers

Secure Static Site

cargo build --no-default-features --features "tls"

Perfect for:

• Production static sites
• Security-conscious deployments
• Compliance requirements

Features included:

• All minimal features
• HTTPS/TLS support

Authentication-Only App

cargo build --no-default-features --features "auth"

Perfect for:

• User portals
• Dashboard applications
• API services with authentication

Features included:

• User management
• JWT authentication
• OAuth2 providers
• Session management

Content Management System

cargo build --no-default-features --features "content-db"

Perfect for:

• Blogs
• News sites
• Documentation platforms
• Knowledge bases

Features included:

• Markdown rendering
• Database content storage
• Content caching

Communication Site

cargo build --no-default-features --features "email"

Perfect for:

• Contact pages
• Feedback forms
• Newsletter signups
• Notification systems

Features included:

• Email sending
• Form handling
• Template system

Full-Featured Application

cargo build --features "auth,content-db,email"
# or simply: cargo build (uses defaults)

Perfect for:

• Complete web applications
• SaaS platforms
• User-generated content sites
• E-commerce applications

Features included:

• Complete user management
• Content management
• Email system
• All security features

Production-Ready

cargo build --release --features "tls,auth,content-db,email"

Perfect for:

• Production deployments
• Enterprise applications
• High-security requirements

Features included:

• All features enabled
• HTTPS/TLS security
• Optimized for performance

Configuration Matrix

Feature	Database Required	Email Required	TLS Recommended
Static Site	❌	❌	✅ (Production)
Auth	✅	✅ (Password Reset)	✅
Content-DB	✅	❌	✅ (Production)
Email	❌	✅	✅ (Production)
TLS	❌	❌	N/A

Performance Impact

Build Times

• Minimal: ~30 seconds
• Auth Only: ~45 seconds
• Content-DB Only: ~40 seconds
• Full Featured: ~60 seconds

Binary Size

• Minimal: ~2MB
• Auth Only: ~5MB
• Content-DB Only: ~4MB
• Full Featured: ~8MB

Memory Usage

• Minimal: ~10MB RAM
• Auth Only: ~25MB RAM
• Content-DB Only: ~20MB RAM
• Full Featured: ~40MB RAM

Cold Start Time

• Minimal: ~50ms
• Auth Only: ~200ms
• Content-DB Only: ~150ms
• Full Featured: ~300ms

Feature Dependencies

Database Features

Features that require database access:

• auth - User accounts, sessions, OAuth tokens
• content-db - Content storage, caching, search

Email Features

Features that benefit from email:

• auth - Password reset, email verification
• email - Contact forms, notifications

Security Features

Features that enhance security:

• tls - HTTPS encryption
• auth - User authentication
• All features include basic security (CSRF, rate limiting, headers)

Development vs Production

Development Recommendations

# Fast development cycle
cargo build --features "auth,content-db,email"

# With hot reloading
cargo leptos serve --features "auth,content-db,email"

Production Recommendations

# Secure production build
cargo build --release --features "tls,auth,content-db,email"

# Minimal production (static sites)
cargo build --release --no-default-features --features "tls"

Migration Between Features

Adding Features

1. Update feature flags in build command
2. Add required environment variables
3. Run database migrations (if applicable)
4. Update frontend components
5. Test thoroughly

Removing Features

1. Export/backup relevant data
2. Update feature flags
3. Remove unused environment variables
4. Clean up unused code
5. Test reduced functionality

Feature Roadmap

Planned Features

• WebSocket Support: Real-time communication
• File Upload: File management system
• Admin Dashboard: Administrative interface
• API Documentation: Automatic API docs
• Metrics & Monitoring: Application metrics
• Search Engine: Full-text search
• Caching Layer: Redis integration
• Message Queue: Background job processing

Experimental Features

• GraphQL API: Alternative to REST
• Server-Side Events: Real-time updates
• Multi-tenancy: Tenant isolation
• Audit Logging: Comprehensive audit trails

Best Practices

Feature Selection

1. Start Minimal: Begin with only essential features
2. Add Gradually: Introduce features as requirements evolve
3. Consider Dependencies: Understand feature interactions
4. Test Combinations: Verify feature combinations work together
5. Document Choices: Record why features were selected

Configuration

1. Environment-Specific: Use different features per environment
2. Feature Flags: Use runtime feature flags for A/B testing
3. Graceful Degradation: Handle missing features gracefully
4. Monitoring: Monitor feature usage and performance

Development

1. Feature Branches: Develop features in isolation
2. Integration Testing: Test feature combinations
3. Documentation: Document feature usage
4. Performance Testing: Measure feature impact

Next Steps

Ready to dive deeper into specific features? Check out:

• Authentication System - Complete user management
• Content Management - Database-driven content
• TLS Support - HTTPS configuration
• Email System - Communication features
• Feature Combinations - Detailed combination guide

Or explore the technical details:

• Database Overview - Database configuration
• Security Overview - Security features
• Performance Overview - Performance considerations