nginx-discovery

Discover and parse NGINX configurations with ease.

A Rust library for parsing, analyzing, and extracting information from NGINX configuration files. Perfect for building tools that need to understand NGINX configs programmatically.

✨ Features

🔍 Parse NGINX Configs - Full support for directives, blocks, and nested structures
📊 Extract Information - High-level extractors for logs, servers, and more
🎯 Type-Safe - Strongly-typed AST and configuration objects
⚡ Fast - Efficient lexer and parser with zero-copy where possible
🛠️ Great Errors - Detailed error messages with source locations and suggestions
📚 Well Documented - Comprehensive docs and examples

🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
nginx-discovery = "0.1"

Parse a Configuration

use nginx_discovery::parse;

let config = r#"
server {
    listen 80;
    server_name example.com;

    location / {
        root /var/www/html;
    }
}
"#;

let parsed = parse(config)?;
println!("Found {} directives", parsed.directives.len());

Extract Access Logs

use nginx_discovery::{parse, extract};

let config = parse(config_text)?;
let logs = extract::access_logs(&config)?;

for log in logs {
    println!("Log: {}", log.path.display());
    println!("Format: {:?}", log.format_name);
    println!("Context: {:?}", log.context);
}

Extract Log Formats

use nginx_discovery::{parse, extract};

let config = parse(config_text)?;
let formats = extract::log_formats(&config)?;

for format in formats {
    println!("Format: {}", format.name());
    println!("Variables: {:?}", format.variables());
}

📖 Examples

Check out the examples/ directory:

lex_config.rs - Tokenize NGINX configs
extract_logs.rs - Extract log configurations

Run an example:

cargo run --example extract_logs

🎯 Use Cases

Log Analysis Tools - Extract log paths and formats for Fluentd, Vector, Logstash
Configuration Management - Validate and analyze NGINX configs
Monitoring Setup - Discover upstreams and servers for monitoring
Migration Tools - Parse existing configs for migration planning
Documentation - Auto-generate documentation from configs
Security Auditing - Analyze SSL/TLS and security settings

🏗️ Architecture

The library is organized in layers:

┌─────────────────────────────────────┐
│   High-Level API (extract::*)      │  ← Extract logs, servers, etc.
├─────────────────────────────────────┤
│   Parser (parse)                    │  ← Convert tokens to AST
├─────────────────────────────────────┤
│   Lexer (tokenize)                  │  ← Convert text to tokens
├─────────────────────────────────────┤
│   AST Types                         │  ← Type-safe representation
└─────────────────────────────────────┘

Low-Level: Lexer

use nginx_discovery::parser::Lexer;

let mut lexer = Lexer::new("server { listen 80; }");
let tokens = lexer.tokenize()?;

Mid-Level: Parser

use nginx_discovery::parse;

let config = parse("server { listen 80; }")?;
for directive in &config.directives {
    println!("{}", directive.name());
}

High-Level: Extractors

use nginx_discovery::{parse, extract};

let config = parse(config_text)?;
let logs = extract::access_logs(&config)?;

Extract Servers

use nginx_discovery::NginxDiscovery;

let config = r#"
server {
    listen 80;
    listen 443 ssl;
    server_name example.com www.example.com;

    location / {
        root /var/www/html;
    }

    location /api {
        proxy_pass http://backend:3000;
    }
}
"#;

let discovery = NginxDiscovery::from_config_text(config)?;

// Get all servers
let servers = discovery.servers();
println!("Found {} servers", servers.len());

// Get SSL servers only
let ssl_servers = discovery.ssl_servers();
println!("SSL servers: {}", ssl_servers.len());

// Get all listening ports
let ports = discovery.listening_ports();
println!("Listening on ports: {:?}", ports);

// Get proxy locations
let proxies = discovery.proxy_locations();
for location in proxies {
    println!("Proxy: {} -> {:?}", location.path, location.proxy_pass);
}

📚 Documentation

🧪 Testing

The library has comprehensive test coverage:

# Run all tests
cargo test --all-features

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

🔧 Feature Flags

[dependencies]
nginx-discovery = { version = "0.1", features = ["serde"] }

Available features:

serde - Serialize/deserialize AST types
system (default) - System interaction utilities

📊 Supported NGINX Directives

Currently supports:

✅ Simple directives: user nginx;
✅ Block directives: server { ... }, location { ... }
✅ Nested blocks: http { server { location { } } }
✅ Quoted strings: "value" and 'value'
✅ Variables: $host, ${variable}
✅ Numbers: 80, 443, 1024
✅ Comments: # comment
✅ Log formats and access logs
✅ Server blocks with listen directives and locations (v0.2.0)
✅ Listen directives with SSL, HTTP/2, HTTP/3 options (v0.2.0)
✅ Location blocks with all modifiers (=, ^~, ~, ~*) (v0.2.0)
✅ Proxy detection and static file serving (v0.2.0)

🗺️ Roadmap

v0.2.0 (Released)

✅ Server block extractor
✅ Location block extractor
✅ SSL/TLS server detection
✅ Proxy location detection

v0.3.0 (Planned)

Upstream extractor
Map directive support
Geo/GeoIP support
Include directive resolution
Rate limiting configuration
Auth configuration extractor

v1.0.0 (Future)

Complete NGINX directive support
Configuration validation
Config transformation tools

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Development

git clone https://github.com/urwithajit9/nginx-discovery.git
cd nginx-discovery

# Run tests
cargo test --all-features

# Run examples
cargo run --example extract_logs

# Format code
cargo fmt

# Run linter
cargo clippy --all-features -- -D warnings

📝 License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

🙏 Acknowledgments

Built with ❤️ in Rust.

Special thanks to the Rust community for excellent parser libraries and documentation.

📬 Contact

Author: Ajit Kumar
GitHub: @urwithajit9
Issues: GitHub Issues

Star ⭐ this repo if you find it useful!

nginx-discovery 0.2.0