# herolib-virt Architecture Guide

## Overview

`herolib-virt` is a comprehensive virtualization and containerization library providing Rust bindings and Rhai scripting support for container image building, container management, virtual machine operations, and Kubernetes cluster management.

## System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    herolib-virt Library                      │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           User Application (Rust or Rhai)            │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                  │
│           ┌───────────────┴───────────────┐                 │
│           ▼                               ▼                 │
│  ┌─────────────────────┐      ┌───────────────────────┐    │
│  │  Rhai Integration   │      │   Rust API Layer      │    │
│  │  (rhai module)      │      │                       │    │
│  │                     │      │ - Direct types        │    │
│  │ - Functions         │      │ - Trait implementations│    │
│  │ - Type bindings     │      │ - Error handling      │    │
│  │ - Fluent API        │      │                       │    │
│  └─────────────────────┘      └───────────────────────┘    │
│           │                               │                 │
│           └───────────────┬───────────────┘                 │
│                           ▼                                  │
│           ┌──────────────────────────────┐                  │
│           │    Core Module Implementations   │               │
│           └──────────────────────────────┘                  │
│                    │                                         │
│  ┌─────────────────┼────────────────────────────┐           │
│  │                 │                            │            │
│  ▼                 ▼                            ▼            │
│┌──────────┐  ┌──────────────┐  ┌──────────────────────┐    │
││ Buildah  │  │   Nerdctl    │  │  Kubernetes Module   │    │
││          │  │              │  │                      │    │
││- Builder │  │- Container   │  │- KubernetesManager  │    │
││- Images  │  │- Images      │  │- Build Machine      │    │
││- Remote  │  │- Health      │  │- Dev Machine        │    │
││- Content │  │- Logs        │  │- Registry           │    │
│└──────────┘  └──────────────┘  │- Traefik            │    │
│                                │- Fluent API         │    │
│  ┌──────────┐  ┌──────────┐   └──────────────────────┘    │
│  │ Cloud HV │  │  QCOW2   │                               │
│  │          │  │          │   ┌──────────────────────┐    │
│  │- VM Spec │  │- Create  │   │  Kubernetes Submodules  │    │
│  │- VM Ops  │  │- Snapshot│   │                      │    │
│  │- Paths   │  │- Info    │   │- config              │    │
│  │- Utils   │  │- Ubuntu  │   │- error               │    │
│  └──────────┘  └──────────┘   │- fluent              │    │
│                                │- kubebuilder        │    │
│                                │- kubernetes_manager │    │
│                                │- kubessh             │    │
│                                │- kubedevel           │    │
│                                │- registry            │    │
│                                │- traefik             │    │
│                                └──────────────────────┘    │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                           │
            ┌──────────────┼──────────────┐
            ▼              ▼              ▼
      ┌──────────┐  ┌──────────┐  ┌──────────────┐
      │ buildah  │  │ nerdctl  │  │  kubectl /   │
      │          │  │          │  │  containerd  │
      └──────────┘  └──────────┘  └──────────────┘
                           │
            ┌──────────────┴──────────────┐
            ▼                             ▼
      ┌──────────────┐           ┌──────────────────┐
      │   Containerd │           │   Kubernetes API │
      │              │           │                  │
      │- Runtime     │           │- API Server      │
      │- Images      │           │- etcd            │
      │- Containers  │           │- Controllers     │
      └──────────────┘           └──────────────────┘
```

## Module Organization

### 1. Core Container Modules

#### Buildah (`src/buildah/`)
**Purpose**: Build OCI/Docker-compatible container images

**Key Components**:
- `Builder`: Main builder type with fluent API
- `BuildahError`: Error type
- `RemoteExecution`: SSH/kubectl remote build support
- `ContentOperations`: File/content operations in containers

**Key Responsibilities**:
- Container creation from base images
- Command execution in containers
- File/content management (write, read, copy)
- Image metadata configuration (entrypoint, cmd, env, labels)
- Image committing and persistence
- Registry push/pull operations

**Design Pattern**: Fluent builder with method chaining

```rust
builder.run("command")
       .write("content", "/path")
       .set_entrypoint("/bin/app")
       .commit("image:tag")?
```

#### Nerdctl (`src/nerdctl/`)
**Purpose**: Container lifecycle management with containerd

**Key Components**:
- `Container`: Container type with state
- `ContainerBuilder`: Fluent builder for container creation
- `ContainerStatus`: Enum for container states
- `HealthCheck`: Health check configuration
- Image operations (pull, push, list, remove)
- Container operations (create, run, start, stop, remove)

**Key Responsibilities**:
- Container CRUD operations
- Image management
- Port mapping and networking
- Resource limits (CPU, memory)
- Environment variable management
- Volume mounting
- Health check configuration
- Log retrieval and monitoring

**Design Pattern**: 
- Direct functions for simple operations
- Builder pattern for complex configurations
- Stateful Container type for tracking state

### 2. Virtual Machine Modules

#### Cloud Hypervisor (`src/cloudhv/`)
**Purpose**: Virtual machine creation and lifecycle management

**Key Components**:
- `VmSpec`: VM specification (CPU, memory, disk, firmware)
- `VmRuntime`: Runtime state of a VM
- `VmRecord`: Persistent VM record
- Error types and utilities

**Key Responsibilities**:
- VM creation and deletion
- Start/stop/reboot operations
- VM info queries
- VM listing and discovery
- Path management for VM data

**Design Pattern**: Functional API with structured data

```rust
let spec = VmSpec { ... };
vm_create(&spec)?;
vm_start("vm-id")?;
```

#### QCOW2 (`src/qcow2/`)
**Purpose**: QCOW2 disk image management

**Key Components**:
- `create()`: Create new disk images
- `snapshot_*()`: Snapshot operations
- `info()`: Image information
- `build_ubuntu_24_04_base()`: Cloud image builder

**Key Responsibilities**:
- Disk image creation with sparse allocation
- Snapshot creation/deletion/listing
- Image information queries
- Ubuntu cloud image downloading and preparation
- Resize operations

**Design Pattern**: Functional API wrapping qemu-img CLI

### 3. Kubernetes Module (`src/kubernetes/`)

The Kubernetes module is the most complex, with multiple specialized sub-modules:

#### Architecture

```
kubernetes/
├── kubernetes_manager.rs     # Main API entry point
├── fluent.rs                # Builder pattern for resources
├── kubebuilder.rs           # Container image building in K8s
├── kubedevel.rs             # SSH dev environment
├── kubessh.rs               # SSH client for pods
├── registry.rs              # Registry deployment
├── traefik.rs               # Ingress/routing config
├── config.rs                # Configuration types
└── error.rs                 # Error types
```

**Key Components**:

1. **KubernetesManager**
   - Primary entry point
   - Namespace-scoped operations
   - Resource CRUD operations
   - Pattern-based deletion
   - Async/await based

2. **Fluent Builders**
   - `PodBuilder`, `ServiceBuilder`, `DeploymentBuilder`
   - `ConfigMapBuilder`, `SecretBuilder`
   - Chainable configuration
   - Type-safe K8s resource creation

3. **BuildMachine**
   - Runs Buildah in Kubernetes pods
   - Builds container images in-cluster
   - Integrates with registries

4. **DevelopmentMachine**
   - SSH-accessible development environment
   - Interactive pod shells
   - Port forwarding

5. **RegistryDeployer**
   - Deploy Docker/OCI registries in K8s
   - Authentication and secrets
   - Storage configuration

6. **Traefik Integration**
   - Ingress route configuration
   - Load balancing
   - TLS/SSL setup
   - Middleware support

**Design Pattern**: 
- Primary: Async functional API with `KubernetesManager`
- Secondary: Fluent builders for complex resources
- Namespace scoping: Each manager instance = one namespace

### 4. Rhai Integration (`src/rhai/`)

**Purpose**: Expose all functionality to Rhai scripting language

**Key Components**:
- `buildah.rs`: Buildah Rhai bindings
- `nerdctl.rs`: Nerdctl Rhai bindings  
- `cloudhv.rs`: Cloud HV Rhai bindings
- `qcow2.rs`: QCOW2 Rhai bindings
- `kubernetes/`: Kubernetes Rhai bindings

**Integration Patterns**:
- Each module implements `IntoRhai` trait
- Type conversions for compatibility
- Function registration in Rhai engine
- Special fluent APIs for scripting (e.g., `bah()` for Buildah)

**Design**: Mirrored module structure with Rhai-specific adaptations

## Design Patterns

### 1. Async/Await First

All Kubernetes operations are async and require a tokio runtime:

```rust
#[tokio::main]
async fn main() {
    let km = KubernetesManager::new("default").await?;
    let pods = km.pods_list().await?;
}
```

**Why**: 
- Better performance with multiple concurrent operations
- Aligns with Kubernetes API patterns
- Modern Rust best practice

### 2. Builder Pattern

Used for complex configurations:

```rust
ContainerBuilder::new("name", "image")
    .port(80, 8080)
    .env("KEY", "value")
    .memory_limit("512m")
    .build()?
```

**Why**:
- Type-safe configuration
- Readable, fluent API
- Defaults handling
- Chainable method calls

### 3. Error Handling

Each module has its own error type:
- `BuildahError`
- `NerdctlError`
- `CloudHvError`
- `Qcow2Error`
- `KubernetesError`

All implement `std::error::Error` and provide detailed context.

### 4. Namespace Scoping (Kubernetes)

Each `KubernetesManager` is tied to a namespace:

```rust
let prod = KubernetesManager::new("prod").await?;
let dev = KubernetesManager::new("dev").await?;
```

**Rationale**:
- Prevents accidental cross-namespace operations
- Type-safe namespace selection
- Clearer code intent

### 5. Functional and Object-Oriented Mix

Different modules use different paradigms:

- **Functional**: CloudHV, QCOW2 (simple wrapped CLIs)
- **Object-Oriented**: Buildah, Nerdctl (stateful builders)
- **Async Object-Oriented**: Kubernetes (complex state + async)

This allows each module to use the best fit paradigm.

## Data Flow Examples

### Container Image Building (Buildah)

```
User Code
    ↓
Builder::new() ─→ Create container from base image
    ↓
builder.run() ─→ Execute command in container
    ↓
builder.write() ─→ Write files/content to container
    ↓
builder.config() ─→ Set metadata (env, labels, etc.)
    ↓
builder.commit() ─→ Commit to image in local storage
    ↓
Result: Image ID/Name
```

### Container Lifecycle (Nerdctl)

```
User Code
    ↓
ContainerBuilder ─→ Configure container
    ↓
builder.build() ─→ Create container
    ↓
container_start() ─→ Start container
    ↓
container_info() ─→ Get status/info
    ↓
container_stop() ─→ Stop gracefully
    ↓
container_remove() ─→ Delete container
```

### Kubernetes Deployment

```
User Code
    ↓
KubernetesManager::new("ns") ─→ Connect to cluster/namespace
    ↓
DeploymentBuilder ─→ Configure deployment
    ↓
builder.apply() ─→ Create deployment in K8s
    ↓
km.deployment_get() ─→ Wait for readiness
    ↓
Result: Running pods
```

### VM Lifecycle (Cloud HV + QCOW2)

```
User Code
    ↓
qcow2::create() ─→ Create disk image
    ↓
VmSpec ─→ Define VM configuration
    ↓
vm_create() ─→ Create VM
    ↓
vm_start() ─→ Boot VM
    ↓
vm_info() ─→ Check status
    ↓
vm_stop() ─→ Shutdown
    ↓
vm_delete() ─→ Remove VM
```

## Dependency Management

### External Dependencies

**Container/Image Building**:
- `buildah` CLI
- Podman/Docker runtime (for image operations)

**Container Management**:
- `nerdctl` CLI
- Containerd runtime

**VM Management**:
- `cloud-hypervisor` binary
- `qemu-img` tool (for QCOW2)

**Kubernetes Management**:
- Kubernetes cluster (1.20+)
- kubeconfig file
- `kubectl` (optional, for debugging)

### Internal Dependencies

```
herolib-virt
├── herolib-os          # OS utilities (process, filesystem)
├── herolib-core        # Core types and traits
└── External crates
    ├── tokio           # Async runtime
    ├── serde/serde_json # Serialization
    ├── rhai            # Scripting language
    ├── kube            # Kubernetes client (optional)
    └── ... others ...
```

## Feature Flags

```rust
// Cargo.toml
herolib-virt = { version = "...", features = ["rhai", "kubernetes"] }
```

- **rhai** (default): Enable Rhai scripting support
- **kubernetes**: Enable Kubernetes management
- **full**: Enable all features

## Performance Characteristics

### Memory Usage
- Base library: ~50 MB (without features)
- With Kubernetes: +100 MB (for kube client)
- With Rhai: +30 MB (for script engine)

### Network I/O
- Kubernetes operations: Minimal (API calls)
- Container operations: Depends on image size
- Registry operations: Can be large (image pulls)

### Execution Time
- Container creation: 100ms - 1s
- Image build: 1s - 10m (depends on layers)
- VM creation: 2 - 5 seconds
- Disk image creation: ~100ms

## Testing Strategy

Each module includes:
- Unit tests for individual functions
- Integration tests for workflows
- Example scripts (Rhai and Rust)
- Error path testing

**Run tests**:
```bash
cargo test
cargo test --features kubernetes
```

## Extension Points

To extend herolib-virt:

1. **Add new container runtime**: Create `new_runtime/` module
2. **Add new VM hypervisor**: Create `new_hypervisor/` module
3. **Add Rhai bindings**: Implement `IntoRhai` traits
4. **Add error types**: Implement `std::error::Error`

## Best Practices

1. **Always use builders for complex configs**
2. **Handle errors explicitly** - don't unwrap
3. **Use async/await for Kubernetes** - don't block
4. **Namespace your Kubernetes operations** - don't use default
5. **Clean up resources** - remove containers, stop VMs
6. **Use snapshots** - create before major changes
7. **Log operations** - enable debug for troubleshooting
8. **Test in dev first** - before production

## Security Considerations

1. **Credentials**: Use RBAC, service accounts, kubeconfig
2. **Network**: Use TLS for registry access
3. **Permissions**: Minimum required for operations
4. **Secrets**: Don't log sensitive values
5. **Images**: Use signed/verified images when possible
6. **Isolation**: Separate namespaces for different concerns

## See Also

- README.md - Feature overview
- src/buildah/README.md - Buildah details
- src/kubernetes/README.md - Kubernetes details
- src/qcow2/README.md - QCOW2 details
- Examples in examples/ and rhaiexamples/
