provisioning-platform/prov-ecosystem/crates/n8n/README.md

# n8n - Comprehensive n8n Project Management Module

A production-ready Rust library for managing n8n workflow automation projects at scale. Supports selfhosted and cloud instances with multi-environment orchestration.

## Features

- **Multi-Instance Management**: Manage dev, staging, prod, and multi-tenant n8n instances
- **Workflow Management**: Export, import, sync, and validate workflows across instances
- **Deployment Generation**: Docker Compose, Kubernetes, systemd configurations
- **Database Support**: SQLite, PostgreSQL, MySQL/MariaDB
- **GitOps Integration**: Version workflows in Git with bidirectional sync
- **Credentials Management**: Secure credential handling with encryption backends
- **Backup & Restore**: Point-in-time restore with retention policies
- **Health & Monitoring**: Instance health checks, workflow metrics, alerts
- **Reverse Proxy Support**: Traefik, Caddy, Nginx configurations

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
n8n = "0.1.0"
```

## Quick Start

### Basic Instance Configuration

```rust
use n8n::instance::{Instance, InstanceConfig, Environment};
use n8n::api::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = InstanceConfig::new(
        "prod".to_string(),
        "https://n8n.example.com".to_string(),
        "your_api_key".to_string(),
    )
    .with_environment(Environment::Prod);

    let instance = Instance::from_config(config)?;
    let client = Client::new(&instance)?;

    // Check instance health
    let health = client.health().await?;
    println!("Instance status: {}", health.status);

    Ok(())
}
```

### Managing Workflows

```rust
use n8n::workflow;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(&instance)?;

    // List all workflows
    let workflows = client.list_workflows().await?;
    println!("Total workflows: {}", workflows.data.len());

    // Export workflows to directory
    let count = workflow::export::export_all_workflows(
        &client,
        std::path::Path::new("./exported_workflows")
    ).await?;
    println!("Exported {} workflows", count);

    Ok(())
}
```

### Docker Compose Generation

```rust
use n8n::deployment::docker::DockerComposeConfig;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = InstanceConfig::new(
        "local".to_string(),
        "http://localhost:5678".to_string(),
        "key".to_string(),
    );

    let compose = DockerComposeConfig::from_instance(&config)?;
    let yaml = compose.generate_yaml()?;

    std::fs::write("docker-compose.yml", yaml)?;
    println!("Generated docker-compose.yml");

    Ok(())
}
```

### Health Checks and Monitoring

```rust
use n8n::health::{MonitoringManager, MonitoringConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = MonitoringConfig::default();
    let manager = MonitoringManager::new(config);

    let health = manager.health_check(&client).await?;
    println!("Instance health: {:?}", health.status);
    println!("Response time: {}ms", health.response_time_ms);

    Ok(())
}
```

## Configuration with KCL

Define your n8n infrastructure using KCL configuration language:

```kcl
schema N8nProject:
    name: str
    instances: [N8nInstance]
    global_backup: BackupConfig?
    global_monitoring: MonitoringConfig?
```

See `examples/` for full YAML configuration examples.

## Module Structure

- **api** - n8n REST API client and models
- **instance** - Instance configuration and management
- **workflow** - Workflow export, import, sync, validation
- **credentials** - Credential management with encryption
- **deployment** - Docker Compose, Kubernetes, systemd generation
- **database** - Multi-database backend support (SQLite, PostgreSQL, MySQL)
- **gitops** - Git-based workflow versioning and sync
- **backup** - Backup and restore functionality
- **health** - Health checks and monitoring
- **error** - Error types and result handling
- **config** - Configuration types and loading

## Integration with prov-ecosystem

The n8n module integrates seamlessly with other prov-ecosystem crates:

- **encrypt**: Secure credential storage
- **runtime**: Container runtime abstraction
- **init-servs**: Systemd service file generation
- **backup**: Multi-backend backup support
- **valida**: Configuration validation

## Examples

See the `examples/` directory for:
- `n8n-simple.yaml` - Single-instance setup
- `n8n-basic.yaml` - Multi-environment with prod HA
- `n8n-gitops.yaml` - GitOps workflow versioning

## Database Support

### SQLite
Best for development and small deployments:
```rust
let config = DatabaseConfig::sqlite("/data/n8n.db");
```

### PostgreSQL
Recommended for production:
```rust
let config = DatabaseConfig::postgres(
    "db.example.com",
    5432,
    "n8n",
    "user",
    "password"
).with_ssl();
```

### MySQL
Alternative for production:
```rust
let config = DatabaseConfig::mysql(
    "db.example.com",
    3306,
    "n8n",
    "user",
    "password"
).with_pool_size(20);
```

## Deployment Options

### Docker Compose
```rust
let compose = DockerComposeConfig::from_instance(&instance)?;
let yaml = compose.generate_yaml()?;
```

### Kubernetes
```rust
let deployment = deployment::kubernetes::generate_deployment(&config)?;
let service = deployment::kubernetes::generate_service(&config)?;
let ingress = deployment::kubernetes::generate_ingress(&config)?;
```

### Systemd
```rust
let unit = deployment::systemd::generate_service_unit(&config, "/opt/n8n")?;
let (timer, service) = deployment::systemd::generate_backup_timer("daily")?;
```

## Testing

Run the test suite:

```bash
cargo test -p n8n
```

All 60+ unit tests pass, covering:
- Configuration and instance management
- API client operations
- Workflow operations
- Deployment generation
- Database configuration
- GitOps integration
- Backup and restore
- Health checks and monitoring

## License

MIT

## Contributing

Contributions are welcome! Please ensure:
- Code follows idiomatic Rust patterns
- All tests pass
- Documentation is updated
- No `unwrap()` calls in library code