Rustelo/info/feature_system.md

Feature System Documentation

The Rustelo framework implements a comprehensive feature system that allows for modular compilation and deployment. This system enables you to build optimized binaries for different environments while maintaining development flexibility.

Overview

The feature system allows you to:

• Optimize production builds by excluding development-only code
• Reduce binary size by including only necessary components
• Customize functionality for specific deployment scenarios
• Maintain development convenience with full feature sets

Available Features

Core Features

Feature	Description	Binary Size Impact	Production Ready
crypto	Configuration encryption system	Low	✅ Required

Optional Features

Feature	Description	Binary Size Impact	Production Ready
auth	Authentication and authorization system	Medium	✅ Recommended
content-db	Database-backed content management	Medium	✅ Recommended
email	Email sending system with templates	Low	✅ Recommended
metrics	Prometheus metrics collection	Low	✅ Recommended
tls	HTTPS/TLS support	Medium	✅ Production only
examples	Example code and demonstrations	High	❌ Development only

Feature Sets

Production (Recommended)

features = ["auth", "content-db", "crypto", "email", "metrics", "tls"]

• Size: Optimized
• Performance: Maximum
• Security: Enhanced with TLS
• Monitoring: Full metrics

Development (Default)

features = ["auth", "content-db", "crypto", "email", "metrics", "examples"]

• Size: Larger (includes examples)
• Performance: Good
• Security: HTTP only
• Monitoring: Full metrics
• Examples: Included for learning

Minimal

features = ["crypto"]

• Size: Smallest
• Performance: Maximum
• Security: Basic
• Monitoring: None
• Use case: Embedded or constrained environments

Custom Sets

You can create custom feature combinations for specific needs:

# API-only server (no web UI)
features = ["auth", "crypto", "metrics"]

# Content management focus
features = ["auth", "content-db", "crypto", "email"]

# Monitoring and metrics focus  
features = ["auth", "crypto", "metrics"]

Configuration

Cargo.toml Features

[features]
default = ["auth", "content-db", "crypto", "email", "metrics", "examples"]
production = ["auth", "content-db", "crypto", "email", "metrics", "tls"]

# Core features
crypto = ["aes-gcm", "chrono"]

# Authentication system
auth = [
    "jsonwebtoken", "argon2", "uuid", "chrono", "oauth2", 
    "tower-sessions", "sqlx", "totp-rs", "qrcode", "base32", 
    "sha2", "base64", "tower-cookies", "time"
]

# Content management
content-db = [
    "sqlx", "pulldown-cmark", "syntect", "serde_yaml", 
    "tempfile", "uuid", "chrono", "tera"
]

# Email system
email = ["lettre", "handlebars", "urlencoding"]

# Metrics collection
metrics = ["prometheus", "chrono"]

# TLS support
tls = ["axum-server/tls-rustls", "rustls", "rustls-pemfile"]

# Examples (development only)
examples = []

Application Configuration

In config.toml, you can configure which features are enabled at runtime:

[features]
auth = true
tls = false  # Set to true in production with certificates
content_db = true
two_factor_auth = false

[app]
enable_metrics = true
enable_health_check = true
enable_compression = true

[build]
production_features = ["auth", "content-db", "crypto", "email", "metrics", "tls"]
development_features = ["auth", "content-db", "crypto", "email", "metrics", "examples"]
minimal_features = ["crypto"]

Build Commands

Development Builds

# Full development build (default features)
cargo build

# Development with specific features
cargo build --features "auth,content-db,metrics,examples"

# Hot reload development
cargo leptos watch

Production Builds

# Optimized production build
cargo build --release --features "auth,content-db,crypto,email,metrics,tls" --no-default-features

# Using the production feature set
cargo build --release --features production --no-default-features

# Leptos production build
cargo leptos build --release --features production --no-default-features

Minimal Builds

# Minimal binary (crypto only)
cargo build --release --features crypto --no-default-features

# Custom minimal set
cargo build --release --features "crypto,metrics" --no-default-features

Docker Integration

Production Dockerfile

# Build arguments for feature selection
ARG CARGO_FEATURES="production"
ARG NO_DEFAULT_FEATURES="true"

# Build with specified features
RUN if [ "$NO_DEFAULT_FEATURES" = "true" ]; then \
        cargo leptos build --release --features "$CARGO_FEATURES" --no-default-features; \
    else \
        cargo leptos build --release --features "$CARGO_FEATURES"; \
    fi

Docker Build Commands

# Production build
docker build --build-arg CARGO_FEATURES="production" --build-arg NO_DEFAULT_FEATURES="true" .

# Development build
docker build --build-arg CARGO_FEATURES="auth,content-db,crypto,email,metrics,examples" --build-arg NO_DEFAULT_FEATURES="false" .

# Custom build
docker build --build-arg CARGO_FEATURES="auth,metrics" --build-arg NO_DEFAULT_FEATURES="true" .

Docker Compose

services:
  app-prod:
    build:
      context: .
      args:
        CARGO_FEATURES: "production"
        NO_DEFAULT_FEATURES: "true"
    profiles: ["production"]
    
  app-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
      args:
        CARGO_FEATURES: "auth,content-db,crypto,email,metrics,examples"
        NO_DEFAULT_FEATURES: "false"
    profiles: ["dev"]

Deployment Scripts

Feature Selection

The deploy.sh script supports feature selection:

# Production deployment
./deploy.sh deploy --features production --no-default-features

# Custom features
./deploy.sh deploy --features "auth,metrics,content-db"

# Development deployment
./deploy.sh deploy --default-features

Environment-Specific Features

# Development environment
ENVIRONMENT=development ./deploy.sh deploy --default-features

# Staging environment  
ENVIRONMENT=staging ./deploy.sh deploy --features "auth,content-db,crypto,email,metrics"

# Production environment
ENVIRONMENT=production ./deploy.sh deploy --features production --no-default-features

CI/CD Integration

GitHub Actions

# Test with full features
- name: Run tests
  run: cargo test --features "auth,content-db,crypto,email,metrics,examples"

# Build production
- name: Build production
  run: cargo leptos build --release --features production --no-default-features

# Security audit
- name: Security audit
  run: cargo audit

Feature Matrix Testing

strategy:
  matrix:
    features:
      - "crypto"
      - "auth,crypto"
      - "auth,content-db,crypto"
      - "production"
steps:
  - name: Test features
    run: cargo test --features ${{ matrix.features }} --no-default-features

Performance Impact

Binary Size Comparison

Feature Set	Binary Size	Compile Time	Runtime Memory
Minimal (crypto)	~8 MB	~2 min	~20 MB
Basic (auth,crypto,metrics)	~12 MB	~3 min	~35 MB
Standard (production)	~18 MB	~5 min	~50 MB
Full (default)	~22 MB	~6 min	~60 MB

Feature Dependencies

crypto (required)
├── auth (optional)
│   ├── content-db (optional)
│   └── email (optional)
├── metrics (optional)
├── tls (optional)
└── examples (development only)

Best Practices

Production Deployments

1. Always use the production feature set for production deployments
2. Enable TLS in production environments
3. Exclude examples to reduce binary size and attack surface
4. Enable metrics for monitoring and observability
5. Use --no-default-features for explicit control

Development

1. Use default features for full development experience
2. Include examples for learning and testing
3. Enable hot reload with cargo leptos watch
4. Test feature combinations before production deployment

Security Considerations

1. Examples feature should never be enabled in production
2. TLS feature should be enabled for all production deployments
3. Crypto feature is required and cannot be disabled
4. Authentication should be enabled unless building a public API

Troubleshooting

Common Issues

Feature Not Found

error: feature `xyz` not found

Solution: Check available features in Cargo.toml and ensure correct spelling.

Missing Dependencies

error: cannot find crate `prometheus`

Solution: Enable the corresponding feature (e.g., metrics for Prometheus).

Compilation Errors

error: conditional compilation flags don't match

Solution: Ensure all workspace members use compatible feature sets.

Debug Commands

# Check available features
cargo metadata --format-version 1 | jq '.packages[] | select(.name == "server") | .features'

# Verify feature resolution
cargo tree --features production --no-default-features

# Test specific feature combination
cargo check --features "auth,metrics" --no-default-features

Migration Guide

From Default to Production

1. Test your application with production features:

   cargo test --features production --no-default-features
   

2. Update deployment scripts to use production features:

   ./deploy.sh deploy --features production
   

3. Update Docker builds:

   docker build --build-arg CARGO_FEATURES="production" .
   

4. Update CI/CD pipelines to use production features for releases.

Adding Custom Features

1. Define feature in Cargo.toml:

   my_feature = ["dependency1", "dependency2"]
   

2. Add conditional compilation:

   #[cfg(feature = "my_feature")]
   mod my_module;
   

3. Update documentation and deployment scripts.

Examples

Basic Usage

// Conditional compilation based on features
#[cfg(feature = "auth")]
use crate::auth::AuthService;

#[cfg(feature = "metrics")]
use crate::metrics::MetricsRegistry;

// Feature-dependent initialization
pub fn create_app_state() -> AppState {
    AppState {
        #[cfg(feature = "auth")]
        auth_service: Some(Arc::new(AuthService::new())),
        #[cfg(not(feature = "auth"))]
        auth_service: None,
        
        #[cfg(feature = "metrics")]
        metrics_registry: Some(Arc::new(MetricsRegistry::new()?)),
        #[cfg(not(feature = "metrics"))]
        metrics_registry: None,
    }
}

Feature-Dependent Routes

pub fn create_routes() -> Router<AppState> {
    let mut router = Router::new();
    
    #[cfg(feature = "auth")]
    {
        router = router.nest("/auth", create_auth_routes());
    }
    
    #[cfg(feature = "content-db")]
    {
        router = router.nest("/content", create_content_routes());
    }
    
    #[cfg(feature = "examples")]
    {
        router = router.nest("/examples", create_example_routes());
    }
    
    router
}

This feature system provides maximum flexibility while maintaining production optimization and development convenience.