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)
```toml
features = ["auth", "content-db", "crypto", "email", "metrics", "tls"]
```
- **Size**: Optimized
- **Performance**: Maximum
- **Security**: Enhanced with TLS
- **Monitoring**: Full metrics

### Development (Default)
```toml
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
```toml
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:

```toml
# 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

```toml
[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:

```toml
[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

```bash
# 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

```bash
# 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

```bash
# 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

```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

```bash
# 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

```yaml
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:

```bash
# 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

```bash
# 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

```yaml
# 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

```yaml
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

```bash
# 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:
   ```bash
   cargo test --features production --no-default-features
   ```

2. **Update deployment scripts** to use production features:
   ```bash
   ./deploy.sh deploy --features production
   ```

3. **Update Docker builds**:
   ```bash
   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`**:
   ```toml
   my_feature = ["dependency1", "dependency2"]
   ```

2. **Add conditional compilation**:
   ```rust
   #[cfg(feature = "my_feature")]
   mod my_module;
   ```

3. **Update documentation** and deployment scripts.

## Examples

### Basic Usage

```rust
// 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

```rust
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.