The Telemetry Matrix

An isolated security engine must never crash. A crash is a vulnerability. In Chapter 2, we returned raw error strings when our parsing failed. But in true systems engineering, relying on "stringly-typed" errors is dangerous—you can't write programmatic logic to handle a string effectively.

In this final foundational chapter, we will build a dedicated, iron-clad Error Enum to categorize failures exactly as we categorized threats. Then, we will deploy a Vector—a dynamic, heap-allocated matrix—to store an ongoing, historical log of every attack our sandbox intercepts.

1. Formalizing System Errors

Rust does not have traditional "Exceptions" (like Python's ValueError). Instead, we define our own precise error states. By creating a custom SentinelError Enum, we force our engine to understand the difference between an empty payload and a malformed integer port.

2. Building the Vector Matrix

A Vec<T> is a dynamic, resizable array. Because we don't know if our server will intercept 1 attack or 10,000 attacks today, we initialize an empty Vector and Move our completed ThreatProfiles into it as they are parsed.

3. The Final Volume 1 Architecture

Open your local src/main.rs file one last time. We are tying everything together: Primitives, Structs, Enums, References, Vectors, and Custom Error Handling. Replace your code with this finalized engine:

use std::io::{self, Write};
use std::num::ParseIntError;

// --- DOMAIN MODELS ---

#[derive(Debug)]
enum AttackVector { NetworkTraffic, FileSystem, Unknown }

#[derive(Debug)]
struct ThreatProfile {
    vector: AttackVector,
    target_port: u16,
    requires_admin: bool,
    signature: String,
}

// 1. OUR CUSTOM ERROR SYSTEM
// This replaces lazy string errors with programmatic, exact failure states.
#[derive(Debug)]
enum SentinelError {
    EmptyPayload,
    MalformedStructure,
    InvalidPort(ParseIntError), // Wraps Rust's native integer parsing error
}

// --- CORE LOGIC ---

// 2. Notice the return signature now uses our strict SentinelError
fn analyze_payload(payload: &str) -> Result {
    let clean = payload.trim();
    if clean.is_empty() { return Err(SentinelError::EmptyPayload); }

    let mut parts = clean.split_whitespace();
    let command = parts.next().ok_or(SentinelError::MalformedStructure)?;

    // 3. Using Tuple Destructuring for a cleaner, more compact assignment
    let (vector, req_admin, default_port, expects_port) = match command {
        "nc" | "ssh" => (AttackVector::NetworkTraffic, false, 22, true),
        "rm" | "chmod" => (AttackVector::FileSystem, true, 0, false),
        _ => (AttackVector::Unknown, false, 0, false),
    };

    let target_port: u16 = if expects_port {
        match parts.next() {
            // Because target_port is strictly defined as u16, Rust infers the parse type automatically!
            Some(port_str) => port_str.parse().map_err(SentinelError::InvalidPort)?,
            None => default_port,
        }
    } else {
        default_port
    };

    Ok(ThreatProfile {
        vector,
        target_port,
        requires_admin: req_admin,
        signature: clean.to_string(),
    })
}

// --- EXECUTION ENGINE ---

fn main() -> Result<(), io::Error> {
    println!("=== PROJECT SENTINEL TELEMETRY MATRIX ===");
    
    // 4. Initialize our dynamic, heap-allocated Vector matrix
    let mut threat_ledger: Vec = Vec::new();

    loop {
        print!("sentinel_engine > ");
        io::stdout().flush()?;

        let mut buffer = String::new();
        io::stdin().read_line(&mut buffer)?;
        let query = buffer.trim();

        // Graceful shutdown sequence
        if query == "exit" || query == "quit" {
            println!("Shutting down Sentinel Telemetry Matrix...");
            break;
        }

        if query == "history" {
            println!("\n--- ACTIVE SECURITY LEDGER ---");
            for (index, profile) in threat_ledger.iter().enumerate() {
                println!("[{}] Vector: {:?} | Port: {} | Admin: {} | CMD: {}", 
                    index, profile.vector, profile.target_port, profile.requires_admin, profile.signature);
            }
            println!("------------------------------\n");
            continue;
        }

        match analyze_payload(query) {
            Ok(profile) => {
                println!("Alert: Threat Profile Generated. Appending to ledger.");
                // 5. Move ownership of the profile into our vector memory matrix
                threat_ledger.push(profile); 
            }
            Err(e) => {
                // 6. Catch exact failure states gracefully without panicking
                match e {
                    SentinelError::EmptyPayload => println!("Notice: Blank input ignored."),
                    SentinelError::MalformedStructure => println!("Error: Command unreadable."),
                    SentinelError::InvalidPort(err) => println!("Error: Network port invalid. ({})", err),
                }
            }
        }
    }
    
    Ok(())
}

4. Deconstructing the Architecture

Let's unpack the functional syntax we used to build our bulletproof engine:

• Tuple Destructuring: In Chapter 2, we used a traditional if/else block to categorize commands. Here, we upgraded to a more compact pattern. A match arm can return a tuple — a lightweight, comma-separated grouping of multiple values — and we can unpack all four values simultaneously into separate variables on the left side of the equals sign.
• use std::num::ParseIntError; — We import this from the standard library to catch native integer parsing failures and store them directly inside our custom SentinelError::InvalidPort variant. This ensures our sandbox never loses the original forensic data of exactly why a system conversion failed.
• .ok_or(SentinelError::MalformedStructure)? — The .ok_or() method acts as a bridge, instantly converting an empty Option (meaning the user pressed enter without typing a command) into a formal Result error. This allows us to use the ? operator at the end of the line to immediately eject the error back to the main loop without crashing.
• .map_err(SentinelError::InvalidPort)? — Because the system's native integer error doesn't match our custom SentinelError type, .map_err() transforms it on the fly. It uses our InvalidPort variant exactly like a wrapper function, packaging the raw system error neatly inside our own security taxonomy so the compiler accepts it.

5. Testing the Bulletproof Architecture

Compile and start your completed Volume 1 security tool:

cargo run

Test out your error handling by typing garbage data, letters instead of port numbers, and empty lines. Watch how the custom SentinelError catches every fault without ever crashing the loop.

Type nc 8080 and rm -rf files to generate valid profiles. Then, type history. You will see your Vector iterating flawlessly over borrowed references of your saved structs!

Congratulations! You have successfully completed Volume 1. You have graduated from high-level scripting into actual systems architecture. You understand the stack, the heap, move semantics, references, custom error routing, and strict memory safety.