Volli Commands

A distributed fleet command execution system for network diagnostics and monitoring.

Overview

The volli-commands crate provides a comprehensive framework for executing network diagnostic commands across a fleet of machines. It supports streaming results, fleet-wide distribution, permission management, and multiple output formats.

Architecture

The system is built around several core components:

Command System

• Command Enum: Type-safe command definitions with built-in implementations
• Streaming Execution: Real-time result streaming with header/stream/footer pattern
• Permission Management: Privilege checking and capability detection
• Type-safe States: Compile-time guarantees for execution flow

Distribution System

• Fleet Distribution: Distribute commands across multiple workers/managers
• Target Selection: Flexible targeting by worker IDs, tags, or groups
• Load Balancing: Worker capability and load-aware distribution
• Result Aggregation: Collect and aggregate results from multiple sources

Output Formatting

• Multiple Formats: Table, JSON, and summary output formats
• Result Aggregation: Statistical analysis and outlier detection
• Geographic Breakdown: Optional geographic result grouping

Built-in Commands

Ping

• ICMP echo requests with RTT measurement
• Packet loss calculation and statistics
• Raw socket and system ping fallback
• Streaming results per packet

Traceroute (Planned)

• Route path discovery
• Hop-by-hop latency measurement
• Path diversity analysis

DNS (Planned)

• DNS query execution
• Multiple server testing
• Record consensus analysis

Port Scan (Planned)

• TCP/UDP port scanning
• Service detection
• Response time measurement

HTTP (Planned)

• HTTP request execution
• Timing breakdown (DNS, connect, first byte)
• TLS information extraction

Usage Example

use volli_commands::{Command, CommandResultSender, CommandTarget, CommandOptions};

// Create a command
let ping_command = Command::Ping;

// Set up result handling
let (sender, mut receiver) = CommandResultSender::new("req_123".to_string());

// Execute the command
let args = vec!["example.com".to_string(), "4".to_string()];
ping_command.execute(&args, sender).await?;

// Handle streaming results
while let Some(header) = receiver.header_receiver.recv().await {
    println!("Command started: {:?}", header);
}

while let Some(stream) = receiver.stream_receiver.recv().await {
    println!("Stream data: {:?}", stream);
}

while let Some(footer) = receiver.footer_receiver.recv().await {
    println!("Command completed: {:?}", footer);
}

Fleet Distribution

use volli_commands::{CommandDistributor, CommandTarget, CommandOptions};

// Create distributor
let distributor = CommandDistributor::new("manager1".to_string());

// Execute across fleet
let mut updates = distributor.execute_command(
    "ping".to_string(),
    vec!["example.com".to_string()],
    CommandTarget::AllWorkers,
    CommandOptions {
        timeout_secs: 30,
        max_concurrent: None,
        tags: HashMap::new(),
        wire_version: Some(volli_commands::wire::COMMAND_WIRE_VERSION),
    },
    "admin".to_string(),
).await?;

// Handle fleet updates
while let Some(update) = updates.recv().await {
    match update {
        FleetCommandUpdate::Started { target_count, .. } => {
            println!("Started on {} targets", target_count);
        }
        FleetCommandUpdate::WorkerCompleted { worker_id, result, .. } => {
            println!("Worker {} completed: {:?}", worker_id, result.status);
        }
        FleetCommandUpdate::Completed { results, .. } => {
            println!("Fleet execution completed: {}/{} successful", 
                results.successful, results.total_targets);
            break;
        }
        _ => {}
    }
}

Permission Management

use volli_commands::{PermissionManager, PrivilegeLevel};

let mut pm = PermissionManager::new();

// Check if ping can be executed (requires network capabilities)
if pm.has_privilege_level(PrivilegeLevel::NetworkCapabilities) {
    println!("Can execute ping with raw sockets");
} else {
    println!("Will fall back to system ping");
}

// Check specific capabilities
let capabilities = pm.check_capabilities(&[
    Capability::RawSockets,
    Capability::NetworkAdmin,
]).await?;

println!("Available capabilities: {:?}", capabilities);

Output Formatting

use volli_commands::{FleetPingResults, OutputFormat, create_formatter};

// Create results (normally from fleet execution)
let results = FleetPingResults {
    target: "example.com".to_string(),
    total_nodes: 10,
    responding_nodes: 9,
    // ... other fields
};

// Format as table
let formatter = create_formatter(OutputFormat::Table);
let output = formatter.format_ping_aggregated(&results)?;
println!("{}", output);

// Format as JSON
let formatter = create_formatter(OutputFormat::Json);
let json_output = formatter.format_ping_aggregated(&results)?;
println!("{}", json_output);

Features

✅ Implemented

• Core command framework with enum-based dispatch
• Ping command with ICMP and system fallback
• Streaming result handling (header/stream/footer)
• Type-safe execution states
• Permission and capability management
• Fleet distribution system
• Multiple output formats (table, JSON, summary)
• Worker registration and management
• Command targeting (all workers, specific workers, by tags)
• Result aggregation and statistics

🚧 Planned

• Complete traceroute implementation
• DNS query implementation
• Port scanning implementation
• HTTP request implementation
• Geographic result grouping
• Advanced result aggregation
• Command scheduling and queuing
• Real-time metrics and monitoring

Testing

Run the test suite:

cargo test -p volli-commands

All tests include:

• Unit tests for individual commands
• Integration tests for fleet distribution
• Permission system validation
• Output formatting verification
• Type-safe execution flow testing

Architecture Principles

1. Type Safety: Extensive use of Rust's type system to prevent runtime errors
2. Streaming: Real-time result streaming for long-running commands
3. Modularity: Clear separation between execution, distribution, and formatting
4. Security: Comprehensive permission checking and privilege management
5. Scalability: Designed for fleet-wide deployment across many machines
6. Extensibility: Easy to add new commands and output formats

Integration

This crate integrates with the broader Volli ecosystem:

• volli-core: Core types and networking primitives
• volli-manager: Manager node implementation
• volli-worker: Worker node implementation
• volli-transport: Network transport and messaging

License

Licensed under the BUSL-1.1 license. See the LICENSE file for details.