# SAL Virt Package

The `sal-virt` package provides comprehensive virtualization and containerization tools for building, managing, and deploying containers and filesystem layers.

## Features

- **Buildah**: OCI/Docker image building with builder pattern API
- **Nerdctl**: Container lifecycle management with containerd
- **RFS**: Remote filesystem mounting and layer management
- **Cross-Platform**: Works across Windows, macOS, and Linux
- **Rhai Integration**: Full support for Rhai scripting language
- **Error Handling**: Comprehensive error types and handling

## Modules

### Buildah
Container image building with Buildah, providing:
- Builder pattern for container configuration
- Image management and operations
- Content operations (copy, add, run commands)
- Debug mode support

### Nerdctl
Container management with Nerdctl, providing:
- Container lifecycle management (create, start, stop, remove)
- Image operations (pull, push, build, tag)
- Network and volume management
- Health checks and resource limits
- Builder pattern for container configuration

### RFS
Remote filesystem operations, providing:
- Mount/unmount operations for various filesystem types
- Pack/unpack operations for filesystem layers
- Support for Local, SSH, S3, WebDAV, and custom filesystems
- Store specifications for different backends

## Usage

### Basic Buildah Example

```rust
use sal_virt::buildah::Builder;

// Create a new builder
let mut builder = Builder::new("my-container", "alpine:latest")?;

// Configure the builder
builder.set_debug(true);

// Add content and run commands
builder.copy("./app", "/usr/local/bin/app")?;
builder.run(&["chmod", "+x", "/usr/local/bin/app"])?;

// Commit the image
let image_id = builder.commit("my-app:latest")?;
```

### Basic Nerdctl Example

```rust
use sal_virt::nerdctl::Container;

// Create a container from an image
let container = Container::from_image("web-app", "nginx:alpine")?
    .with_port("8080:80")
    .with_volume("/host/data:/app/data")
    .with_env("ENV_VAR", "production")
    .with_restart_policy("always");

// Run the container
let result = container.run()?;
```

### Basic RFS Example

```rust
use sal_virt::rfs::{RfsBuilder, MountType, StoreSpec};

// Mount a remote filesystem
let mount = RfsBuilder::new("user@host:/remote/path", "/local/mount", MountType::SSH)
    .with_option("read_only", "true")
    .mount()?;

// Pack a directory
let specs = vec![StoreSpec::new("file").with_option("path", "/tmp/store")];
let pack_result = pack_directory("/source/dir", "/output/pack.rfs", &specs)?;
```

## Rhai Integration

All functionality is available in Rhai scripts:

```javascript
// Buildah in Rhai
let builder = bah_new("my-container", "alpine:latest");
builder.copy("./app", "/usr/local/bin/app");
builder.run(["chmod", "+x", "/usr/local/bin/app"]);

// Nerdctl in Rhai
let container = nerdctl_container_from_image("web-app", "nginx:alpine")
    .with_port("8080:80")
    .with_env("ENV", "production");
container.run();

// RFS in Rhai
let mount_options = #{ "read_only": "true" };
rfs_mount("user@host:/remote", "/local/mount", "ssh", mount_options);
```

## Dependencies

- `sal-process`: For command execution
- `sal-os`: For filesystem operations
- `anyhow`: For error handling
- `serde`: For serialization
- `rhai`: For scripting integration

## Testing

The package includes comprehensive tests:

```bash
# Run all tests
cargo test

# Run specific test suites
cargo test buildah_tests
cargo test nerdctl_tests
cargo test rfs_tests

# Run Rhai integration tests
cargo test --test rhai_integration
```

## Error Handling

Each module provides its own error types:
- `BuildahError`: For Buildah operations
- `NerdctlError`: For Nerdctl operations  
- `RfsError`: For RFS operations

All errors implement `std::error::Error` and provide detailed error messages.

## Platform Support

- **Linux**: Full support for all features
- **macOS**: Full support (requires Docker Desktop or similar)
- **Windows**: Full support (requires Docker Desktop or WSL2)

## Security

- Credentials are handled securely and never logged
- URLs with passwords are masked in logs
- All operations respect filesystem permissions
- Network operations use secure defaults

## Configuration

Most operations can be configured through environment variables:
- `BUILDAH_DEBUG`: Enable debug mode for Buildah
- `NERDCTL_DEBUG`: Enable debug mode for Nerdctl
- `RFS_DEBUG`: Enable debug mode for RFS

## License

Apache-2.0