Learning Rust by Building nginx-discovery: A Beginner's Journey with AI

Ever wondered what it's like to build a real-world Rust project as a beginner? This tutorial documents the actual journey of building nginx-discovery - a professional NGINX configuration parser and CLI tool - using AI as a learning companion.

Unlike typical tutorials that show you the "perfect" final code, this guide shows you:

• ✅ The actual errors we encountered


• ✅ Why each crate was chosen


• ✅ How design decisions were made


• ✅ What those cryptic compiler errors mean


• ✅ How to learn Rust effectively with AI assistance

Perfect for beginners who want to understand not just what to code, but why and how to think through problems.

Table of Contents

1. The Project Overview


2. Understanding the Crate Ecosystem


3. Common Rust Errors and How to Fix Them


4. Design Decisions Explained


5. The Build Process


6. Learning Resources


7. Tips for Learning Rust with AI

The Project Overview

What We're Building

nginx-discovery is a CLI tool and library that:

• Parses NGINX configuration files


• Extracts servers, locations, logs


• Analyzes SSL/TLS configuration


• Performs security audits


• Provides an interactive exploration mode

Tech Stack

Language: Rust (edition 2021)

Binary Size: ~8MB (release build)

Dependencies: 15+ crates

Lines of Code: ~5000+

Time to Build: 4-6 weeks (part-time)

Why This Project is Great for Learning

1. 
   Real-world problem - Actual DevOps use case


2. 
   Multiple concepts - Parsing, CLI, data structures


3. 
   Error handling - Learn Result properly


4. 
   Type system - See Rust's types in action


5. 
   Ecosystem - Use popular crates


6. 
   Testing - Write real tests

Understanding the Crate Ecosystem

Let's break down every crate we used and WHY we chose it.

Core Dependencies

1. thiserror (Error Handling)

What it does: Simplifies creating custom error types

Why we chose it:

• Reduces boilerplate for error types


• Works well with Result<T, E>
  


• Industry standard (used by thousands of crates)

Example:

use thiserror::Error;



#[derive(Error, Debug)]

pub enum ParseError {

    #[error("unexpected EOF at line {line}")]

    UnexpectedEof { line: usize },



    #[error("syntax error: {0}")]

    Syntax(String),

}

Learning Resources:

• thiserror docs


• Rust Book Chapter on Error Handling

When to use: Any time you need custom error types. Much better than writing manual Display/Error implementations.

2. serde + serde_json + serde_yaml (Serialization)

What it does: Converts Rust structs to/from JSON, YAML, etc.

Why we chose it:

• De facto standard for serialization


• Zero-cost abstractions


• Works with derive macros (easy!)

Example:

use serde::{Serialize, Deserialize};



#[derive(Serialize, Deserialize)]

struct Server {

    name: String,

    port: u16,

}



// Now you can do:

let json = serde_json::to_string(&server)?;

let yaml = serde_yaml::to_string(&server)?;

Learning Resources:

• Serde docs


• Serde derive guide

Gotcha: Remember the #[cfg_attr(feature = "serde", derive(...))] pattern for optional serialization!

CLI Dependencies

3. clap (Command-Line Argument Parsing)

What it does: Parses command-line arguments and generates help text

Why we chose it:

• Most popular CLI framework in Rust


• Derive macros make it easy


• Automatic help generation


• Subcommands, flags, options all built-in

Example:

use clap::{Parser, Subcommand};



#[derive(Parser)]

#[command(name = "nginx-discover")]

#[command(version, about)]

struct Cli {

    /// Path to nginx.conf

    #[arg(short, long)]

    config: Option<PathBuf>,



    #[command(subcommand)]

    command: Commands,

}



#[derive(Subcommand)]

enum Commands {

    /// Parse configuration

    Parse,

    /// Extract information

    Extract,

}

Learning Resources:

• Clap docs


• Clap cookbook

Common Error: Forgetting #[command(subcommand)] for nested commands!

4. colored (Terminal Colors)

What it does: Adds colors to terminal output

Why we chose it:

• Simple API


• Cross-platform


• Widely used

Example:

use colored::Colorize;



println!("{}", "Success!".green());

println!("{}", "Warning!".yellow());

println!("{}", "Error!".red().bold());

Learning Resources:

• colored docs

Tip: Use colored::control::set_override(false) to disable colors when piping output!

5. tabled (Table Formatting)

What it does: Creates beautiful ASCII tables

Why we chose it:

• Easy to use


• Lots of styling options


• Good performance

Example:

use tabled::{Table, Tabled};



#[derive(Tabled)]

struct Server {

    #[tabled(rename = "Name")]

    name: String,

    #[tabled(rename = "Port")]

    port: u16,

}



let servers = vec![...];

let table = Table::new(servers);

println!("{}", table);

Learning Resources:

• tabled docs

6. dialoguer (Interactive Prompts)

What it does: Creates interactive CLI prompts (menus, inputs, confirmations)

Why we chose it:

• Beautiful UI


• Easy to use


• Good theming support

Example:

use dialoguer::{Select, Input, Confirm};



let selection = Select::new()

    .with_prompt("What would you like to do?")

    .items(&["Parse", "Extract", "Exit"])

    .interact()?;



let name: String = Input::new()

    .with_prompt("Server name")

    .interact()?;



let confirmed = Confirm::new()

    .with_prompt("Continue?")

    .interact()?;

Learning Resources:

• dialoguer docs


• Example interactive CLI

Utility Dependencies

7. anyhow (Error Handling for Applications)

What it does: Simplified error handling for applications (not libraries)

Why we chose it:

• Use for the CLI binary (not the library)


• Great for quick prototyping


• Provides context to errors

Example:

use anyhow::{Context, Result};



fn load_config(path: &Path) -> Result<Config> {

    std::fs::read_to_string(path)

        .context("Failed to read config file")?

        // ...

}

Learning Resources:

• anyhow docs

Important: Use thiserror for libraries, anyhow for applications!

8. which (Finding Executables)

What it does: Finds executables in PATH (like which command)

Why we chose it:

• Needed to find nginx binary


• Cross-platform


• Simple API

Example:

use which::which;



match which("nginx") {

    Ok(path) => println!("Found nginx at: {}", path.display()),

    Err(_) => println!("nginx not found in PATH"),

}

Common Rust Errors and How to Fix Them

Let's look at the ACTUAL errors we encountered and how we fixed them.

Error 1: Borrow Checker - "Value borrowed after move"

The Error:

error[E0382]: borrow of moved value: `critical`

   --> src/commands/analyze.rs:180:21

    |

174 |  let critical: Vec<_> = issues.iter()...

    |      -------- move occurs because `critical` has type `Vec<&Issue>`

180 |      for issue in critical {

    |                   -------- `critical` moved due to implicit call to `.into_iter()`

208 |          critical.len(),

    |          ^^^^^^^^ value borrowed here after move

What it means:

• We created a Vec


• Used it in a for loop (which consumed it)


• Tried to use it again (can't! it's gone)

The Fix:

// BAD:

for issue in critical {  // Moves critical

    // ...

}

println!("{}", critical.len());  // Error! critical was moved



// GOOD:

for issue in &critical {  // Borrows critical

    // ...

}

println!("{}", critical.len());  // Works! critical still exists

Key Lesson: Add & to borrow instead of move!

Learning Resources:

• Rust Book on Ownership


• Rust by Example - Borrowing

Error 2: Clippy - "collapsible_if"

The Warning:

warning: this `if` statement can be collapsed

   |

268 | if condition1 {

269 |     if condition2 {

    |     ^^^^^^^^^^^^^^

What it means:

Nested ifs can be combined with &&

The Fix:

// BAD:

if server.names.is_empty() {

    if server.is_default() {

        // ...

    }

}



// GOOD:

if server.names.is_empty() && server.is_default() {

    // ...

}

Key Lesson: Clippy helps you write idiomatic Rust!

Error 3: Type Mismatch - "expected X, found Y"

The Error:

error[E0308]: mismatched types

  |

20 |     Commands::Analyze(args) => analyze::run(args, &cli.global)?,

   |                                             ^^^^ expected `DoctorArgs`, found `AnalyzeArgs`

What it means:

Function expects one type, you gave it another

The Fix:

// Check the function signature:

pub fn run(args: DoctorArgs, ...) -> Result<()> {

                  ^^^^^^^^^^^

// We were passing AnalyzeArgs!



// Fix: Change to correct type

pub fn run(args: AnalyzeArgs, ...) -> Result<()> {

                  ^^^^^^^^^^^^

Key Lesson: Rust's type system catches these at compile time!

Learning Resources:

• Rust Book on Types

Error 4: Unused Result - "unused Result that must be used"

The Warning:

warning: unused `std::result::Result` that must be used

   |

126 |     print_summary(passed, warnings, errors);

    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What it means:

Function returns Result<()>, but you're ignoring it

The Fix:

// BAD:

print_summary(passed, warnings, errors);



// GOOD:

print_summary(passed, warnings, errors)?;

// or

let _ = print_summary(passed, warnings, errors);

Key Lesson: Rust forces you to handle errors!

Error 5: Module Not Found

The Error:

error[E0583]: file not found for module `analyze`

   |

3  | pub mod analyze;

   | ^^^^^^^^^^^^^^^^

What it means:

Declared a module but file doesn't exist

The Fix:

Create the file! Either:

• 
  src/bin/cli/analyze.rs, OR


• src/bin/cli/analyze/mod.rs

Key Lesson: Module system can be tricky. Follow the naming conventions!

Learning Resources:

• Rust Book on Modules

Design Decisions Explained

Why Use Enums for Modifiers?

The Code:

pub enum LocationModifier {

    None,

    Exact,          // =

    PrefixPriority, // ^~

    Regex,          // ~

    RegexCaseInsensitive, // ~*

}

Why:

1. 
   Type Safety: Can't use invalid modifier


2. 
   Match Exhaustiveness: Compiler ensures all cases handled


3. 
   Self-Documenting: Clear what options exist

Alternative (Bad):

pub struct Location {

    modifier: String,  // Could be anything!

}

Why Optional Fields?

The Code:

pub struct Server {

    pub root: Option<PathBuf>,

    pub locations: Vec<Location>,

}

Why:

• 
  root is optional in NGINX


• 
  Option makes this explicit


• Forces caller to handle None case

Learning Resources:

• Rust Book on Option

Why Builder Pattern?

The Code:

let server = Server::new()

    .with_server_name("example.com")

    .with_listen(listen)

    .with_root("/var/www");

Why:

1. 
   Fluent API: Readable construction


2. 
   Optional Fields: Easy to omit


3. 
   Rust Idiom: Common pattern

Implementation:

impl Server {

    #[must_use]

    pub fn with_server_name(mut self, name: impl Into<String>) -> Self {

        self.server_names.push(name.into());

        self  // Return self for chaining

    }

}

Note the #[must_use] attribute - Clippy suggests this!

Why Feature Flags?

Cargo.toml:

[features]

default = ["system"]

system = ["dep:which"]

serde = ["dep:serde", "dep:serde_json"]

cli = ["dep:clap", "dep:colored", "system", "serde"]

Why:

1. 
   Optional Dependencies: Users only get what they need


2. 
   Smaller Binaries: Exclude unused features


3. 
   Library vs Binary: Different needs

Usage:

// In code:

#[cfg(feature = "serde")]

use serde::{Serialize, Deserialize};



#[cfg_attr(feature = "serde", derive(Serialize))]

pub struct Server { ... }

The Build Process

Development Workflow

# 1. Check code compiles

cargo check



# 2. Run tests

cargo test



# 3. Run Clippy (linter)

cargo clippy -- -D warnings



# 4. Format code

cargo fmt



# 5. Build release

cargo build --release



# 6. Run benchmarks (if any)

cargo bench

Understanding Cargo.toml

[package]

name = "nginx-discovery"

version = "0.4.0"

edition = "2021"           # Rust edition

rust-version = "1.70.0"    # Minimum Rust version



[dependencies]

thiserror = "1.0"          # Version without ^

serde = { version = "1.0", features = ["derive"], optional = true }



[dev-dependencies]          # Only for tests

pretty_assertions = "1.4"



[features]

default = ["system"]

cli = ["dep:clap", "system"]



[[bin]]

name = "nginx-discover"

required-features = ["cli"]

Key Points:

• 
  edition: Language version


• 
  rust-version: MSRV (minimum supported Rust version)


• 
  optional = true: For feature flags


• 
  dev-dependencies: Not in final binary


• 
  [[bin]]: Binary targets

Build Times

First build (downloads + compiles all deps):

• Debug: ~2-3 minutes


• Release: ~3-5 minutes

Incremental builds (only changed code):

• Debug: ~5-15 seconds


• Release: ~30-60 seconds

Tips to Speed Up Builds:

1. Use cargo check (faster than cargo build)


2. Use sccache or mold linker


3. Increase parallel jobs: cargo build -j 8
   

Learning Resources

Essential Rust Resources

Books (Free Online):

1. 
   The Rust Book - Start here!


2. Rust by Example


3. The Cargo Book


4. Rust Design Patterns

Interactive Learning:

1. 
   Rustlings - Small exercises


2. Exercism Rust Track


3. 
   Rust Playground - Online REPL

Video Resources:

1. 
   Let's Get Rusty - YouTube channel


2. 
   Jon Gjengset - Advanced Rust

Documentation:

1. 
   docs.rs - All crate documentation


2. 
   std docs - Standard library


3. Rust API Guidelines

Crate-Specific Learning

Clap:

• Clap tutorial


• Derive reference

Serde:

• Serde Book


• Common patterns

Error Handling:

• Error Handling in Rust


• anyhow vs thiserror

Community Resources

Forums & Chat:

• Rust Users Forum


• Rust Discord


• r/rust subreddit

Finding Crates:

• 
  crates.io - Official registry


• 
  lib.rs - Alternative interface


• 
  Blessed.rs - Curated crates

Tips for Learning Rust with AI

1. Ask for Explanations, Not Just Code

Good:

"Why did you use &str instead of String here? What's the difference?"

Bad:

"Write me a function"

2. Request Error Analysis

When you get an error:

I got this error: [paste error]


Can you explain what it means and why it happened?

1. Ask for Alternatives
   

You used approach X. What are the alternatives and their trade-offs?

Can you recommend resources for learning about [topic]?

Why did you choose this crate over alternatives?

What are the downsides of this approach?

Is this the idiomatic Rust way to do this?

What would Clippy suggest here?

Let's build this feature step by step. Start with the simplest version.

The code compiles but doesn't work as expected. Let's debug it together.

Symptom: Constant borrow checker errors

Solution:

• Learn ownership rules first


• Use clone() liberally while learning (optimize later)


• Read the error messages carefully

2. Over-using Lifetimes

Symptom: Adding 'a everywhere

Solution:

• Most of the time, you don't need explicit lifetimes


• Let the compiler infer them


• Only add when compiler asks

3. Not Reading Compiler Errors

Symptom: Giving up when seeing long errors

Solution:

• Rust errors are helpful! Read them


• Look for the help: suggestions


• Google the error code (E0308, etc.)

4. Avoiding unwrap()

Symptom: unwrap() everywhere

Solution:

• Use ? operator in functions that return Result
  


• Use match or if let to handle errors


• Reserve unwrap() for cases where you know it's safe

5. Not Using Clippy

Symptom: Writing non-idiomatic code

Solution:

• Run cargo clippy regularly


• Fix warnings (they're learning opportunities!)


• Read the explanations at the URLs

Conclusion

Building nginx-discovery was a journey of learning Rust through a real-world project. The key takeaways:

What Worked Well

1. 
   AI as Learning Companion - Claude explained errors and design decisions


2. 
   Real Project - Much better than toy examples


3. 
   Incremental Development - Building feature by feature


4. 
   Good Crates - Standing on shoulders of giants


5. 
   Testing - Caught bugs early

What Was Challenging

1. 
   Borrow Checker - Takes time to internalize


2. 
   Type System - More complex than dynamic languages


3. 
   Async - Didn't need it, but it's tricky


4. 
   Module System - Initial confusion


5. 
   Compile Times - Patience required

Advice for Beginners

1. 
   Start Small - Don't build nginx-discovery on day 1


2. 
   Read Errors - They're your teachers


3. 
   Use Clippy - It teaches idiomatic Rust


4. 
   Write Tests - They document your learning


5. 
   Ask Questions - AI or community, both help


6. 
   Build Real Things - Motivation matters


7. 
   Be Patient - Rust has a learning curve

What's Next?

Consider building:

• 📊 A simple CLI tool


• 🔍 A log parser


• 🌐 A web scraper


• 📝 A static site generator


• 🎮 A game (with Bevy)

Start with something you care about. That's the best way to learn!

Resources from This Article:

• nginx-discovery on GitHub


• Complete codebase to study


• All the tests

Questions? Comments? Drop them below! I'm happy to help other learners navigate their Rust journey.

Remember: Every Rust expert was once a beginner fighting the borrow checker. You've got this! 🦀