gonginx

README

Gonginx

A powerful and comprehensive nginx configuration management library for Go

Gonginx is a production-ready nginx configuration parser and management library that provides parsing, validation, modification, generation, and optimization capabilities for nginx configurations. It's designed to make nginx configuration management programmatic, safe, and efficient.

✨ Key Features

• Complete Configuration Management - Parse, validate, modify, and generate nginx configurations
• ️ Advanced Validation - Context-aware validation with detailed error reporting and fix suggestions
• High Performance - Optimized parsing with benchmark-tested performance
• Type Safety - Smart parameter type detection and validation with directive constants
• Advanced Search - Powerful configuration search and query capabilities
• Rich Templates - Pre-built templates for common nginx configurations
• ️ Utility Tools - Security checking, optimization suggestions, and format conversion
• Stream Support - Complete support for nginx stream module (TCP/UDP load balancing)
• 🔐 Directive Constants - Type-safe constants for 400+ nginx directives
• Comprehensive Testing - Full test coverage with integration and performance tests

Quick Start

Installation

go get github.com/lefeck/gonginx

Basic Usage

package main

import (
    "fmt"
    "log"

    "github.com/lefeck/gonginx/config"
    "github.com/lefeck/gonginx/dumper"
    "github.com/lefeck/gonginx/parser"
)

func main() {
    // Parse from file
    p, err := parser.NewParser("nginx.conf")
    if err != nil {
        log.Fatal(err)
    }

    conf, err := p.Parse()
    if err != nil {
        log.Fatal(err)
    }

    // Find all servers (using directive constants for type safety)
    servers := conf.FindDirectives(config.DirectiveServer)
    fmt.Printf("Found %d servers\n", len(servers))

    // Add a new server
    newServer := &config.Directive{
        Name: config.DirectiveServer,  // Use constants instead of strings
        Block: &config.Block{
            Directives: []config.IDirective{
                &config.Directive{
                    Name:       config.DirectiveListen,
                    Parameters: []config.Parameter{{Value: "80"}},
                },
                &config.Directive{
                    Name:       config.DirectiveServerName,
                    Parameters: []config.Parameter{{Value: "example.com"}},
                },
            },
        },
    }

    // Add to http block
    http := conf.FindDirectives(config.DirectiveHttp)[0]
    http.GetBlock().Directives = append(http.GetBlock().Directives, newServer)

    // Output the configuration
    fmt.Println(dumper.DumpConfig(conf, dumper.IndentedStyle))
}

Using Directive Constants

Gonginx provides type-safe constants for 400+ nginx directives:

// Type-safe directive names with IDE autocomplete
server := &config.Directive{
    Name: config.DirectiveServer,  // Instead of "server"
    Block: &config.Block{
        Directives: []config.IDirective{
            &config.Directive{
                Name:       config.DirectiveListen,
                Parameters: []config.Parameter{{Value: "443"}, {Value: "ssl"}},
            },
            &config.Directive{
                Name:       config.DirectiveSslCertificate,
                Parameters: []config.Parameter{{Value: "/path/to/cert.pem"}},
            },
            &config.Directive{
                Name:       config.DirectiveProxyPass,
                Parameters: []config.Parameter{{Value: "http://backend"}},
            },
        },
    },
}

// Search using constants
locations := conf.FindDirectives(config.DirectiveLocation)
upstreams := conf.FindDirectives(config.DirectiveUpstream)

Benefits:

• ✅ Compile-time typo prevention
• ✅ IDE autocomplete support
• ✅ Easier refactoring
• ✅ Self-documenting code
• ✅ Fully backward compatible (can mix with strings)

See DIRECTIVE_CONSTANTS.md for the complete list and usage guide.

Architecture

Core Components

Parser

Advanced nginx configuration parser with context-aware processing:

• Lexical Analysis: Tokenizes nginx configuration syntax
• Syntax Parsing: Builds Abstract Syntax Tree (AST)
• Context Awareness: Handles different directive contexts (http vs stream)
• Include Support: Recursive processing of include files
• Error Recovery: Detailed error reporting with suggestions

Config

Comprehensive configuration object model:

• Type System: 10+ parameter types with automatic detection
• Validation: Multi-level configuration validation
• Search API: Advanced querying and filtering capabilities
• Manipulation: Safe configuration modification methods
• Relationships: Parent-child directive linking

Dumper

Flexible configuration output formatting:

• Multiple Styles: Indented, compact, sorted output
• Custom Formatting: Configurable spacing and organization
• Comment Preservation: Maintains comments during round-trip
• File Writing: Direct file output with proper permissions

Generator

Template-based configuration generation:

• Builder Pattern: Fluent API for configuration construction
• Pre-built Templates: Common configuration patterns
• Type Safety: Compile-time validation of configurations
• Extensible: Custom template and directive support

Utils

Powerful utility functions:

• Security Analysis: Automated security best practice checking
• Performance Optimization: Configuration optimization suggestions
• Format Conversion: JSON/YAML export capabilities
• Diff Analysis: Configuration change tracking

Advanced Features

Configuration Validation

// Comprehensive validation with detailed reporting
validator := config.NewConfigValidator()
report := validator.ValidateConfig(conf)

if report.HasErrors() {
    for _, issue := range report.GetByLevel(config.ValidationError) {
        fmt.Printf("Error: %s\n", issue.Message)
        if issue.Fix != "" {
            fmt.Printf("Fix: %s\n", issue.Fix)
        }
    }
}

Advanced Search Operations

// Find servers by name
servers := conf.FindServersByName("example.com")

// Find upstream by name
upstream := conf.FindUpstreamByName("backend")

// Find locations by pattern
locations := conf.FindLocationsByPattern("/api/")

// Get all SSL certificates
certificates := conf.GetAllSSLCertificates()

// Get all upstream servers
upstreamServers := conf.GetAllUpstreamServers()

Template-Based Generation

// Generate reverse proxy configuration
template := generator.ReverseProxyTemplate{
    ServerName:    "api.example.com",
    BackendServer: "http://192.168.1.100:8080",
    SSLCert:       "/etc/ssl/certs/api.crt",
    SSLKey:        "/etc/ssl/private/api.key",
    RateLimit:     "10r/s",
}

conf, err := template.Generate()

Builder Pattern API

// Fluent configuration building
config := generator.NewConfigBuilder().
    WorkerProcesses("auto").
    HTTP().
        Upstream("backend").
            Server("127.0.0.1:8001", "weight=3").
            Server("127.0.0.1:8002", "weight=2").
            End().
        Server().
            Listen("443", "ssl").
            ServerName("example.com").
            SSL().
                Certificate("/path/to/cert.pem").
                CertificateKey("/path/to/key.pem").
                End().
            Location("/").
                ProxyPass("http://backend").
                End().
            End().
        End().
    Build()

Utility Functions

// Security analysis
securityReport := utils.CheckSecurity(conf)
fmt.Printf("Security score: %d/100\n", securityReport.Summary.Score)

// Configuration optimization
optimizationReport := utils.OptimizeConfig(conf)
for _, suggestion := range optimizationReport.Suggestions {
    fmt.Printf("Optimization: %s\n", suggestion.Title)
}

// Format conversion
jsonConfig, err := utils.ConvertToJSON(conf)
yamlConfig, err := utils.ConvertToYAML(conf)

// Configuration diff
diffReport := utils.CompareConfigs(oldConf, newConf)

Examples

Basic Examples

• Basic Parsing - Parse configuration and extract listen ports
• Configuration Updates - Modify directives and regenerate
• Server Management - Add and manage server blocks
• Custom Directives - Handle custom nginx directives

Advanced Examples

• Configuration Validation - Comprehensive validation examples
• Advanced Search - Complex configuration queries
• Error Handling - Best practices for error management
• Configuration Generation - Template-based generation
• Parameter Types - Parameter type system usage
• Utility Functions - Security, optimization, and conversion tools

Specialized Blocks

• Stream Configuration - TCP/UDP load balancing
• Map Blocks - Variable mapping configurations
• Geo Blocks - Geographic-based configurations
• Rate Limiting - Request rate limiting setup
• Connection Limiting - Connection limiting configuration
• Cache Configuration - Proxy caching setup
• Split Testing - A/B testing configurations

Performance

Gonginx is designed for high performance with comprehensive benchmarking:

• Small configs (~1KB): ~6μs parsing time
• Medium configs (~50KB): ~110μs parsing time
• Large configs (~1MB): ~400μs parsing time
• Memory efficient: ~10KB per config, 146 allocations average

Run benchmarks:

go test -bench=. ./benchmarks/

Testing

Run Tests

# All tests
go test ./...

# Specific packages
go test ./config/
go test ./parser/ 
go test ./dumper/

# Integration tests
go test ./integration_tests/

# Benchmarks
go test -bench=. ./benchmarks/

Test Coverage

• Unit Tests: Complete coverage of core functionality
• Integration Tests: End-to-end workflow testing
• Performance Tests: Benchmark testing for all operations
• Example Tests: Validation of all documentation examples

Documentation

• Complete Guide - Comprehensive usage guide with examples
• API Reference - Full API documentation
• Directive Constants - Type-safe directive constants reference
• Implementation Summary - Technical implementation details
• Test Summary - Testing strategy and results

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/lefeck/gonginx.git
cd gonginx
go mod download
make test

Production Ready

Gonginx is production-ready with:

• ✅ Comprehensive validation - Multi-level configuration checking
• ✅ Error recovery - Detailed error reporting with fix suggestions
• ✅ Performance tested - Benchmarked for various configuration sizes
• ✅ Memory efficient - Optimized for low memory usage
• ✅ Thread safe - Safe for concurrent use
• ✅ Backward compatible - Maintains API compatibility
• ✅ Well documented - Complete documentation and examples
• ✅ Fully tested - Comprehensive test suite

License

MIT License - see the license file for details.