Gonginx

Gonginx maintains a hierarchical structure in its AST (Abstract Syntax Tree) to allow for easier manipulation of nested configurations:

• Root-level directives: Leaf directives located at the root of the configuration have a nil parent.
• Nested directives: Every nested directive points to its enclosing directive wrapper (for example, a location directive will point to its enclosing server directive, which in turn points to http).

By default, Gonginx handles includes. You can customize this behavior using parser options:

• Enable include parsing: Use parser.WithIncludeParsing().
• Include deduplication: Includes are automatically deduplicated by their canonical file path.
• Cycle detection: Cyclic include branches are skipped by default to prevent infinite recursion. To return an explicit error when a cycle is detected, use parser.WithIncludeCycleErr().

Gonginx is composed of three primary functional areas:

• Parser: The main engine that analyzes Nginx structured files and converts them into Go objects. It utilizes a lexer to generate tokens and a parser to transform those tokens into configuration objects.
• Config: Provides the Go representations (models and AST) for any context, directive, or parameter within an Nginx configuration.
• Dumper: Handles the styling and formatting configuration for regenerating (dumping) the configuration files.

When searching for upstream blocks, Gonginx offers two modes:

• FindUpstreams(): Permissive mode. It skips unexpected types and continues searching.
• FindUpstreamsStrict(): Strict mode. It returns a typed error if it encounters unexpected upstream directive types.

To parse Nginx configuration content provided as a string, use parser.NewStringParser(fullConf) followed by the .Parse() method. This is useful for manipulating configuration snippets in memory.

p := parser.NewStringParser(fullConf)
conf, err := p.Parse()
if err != nil {
	panic(err)
}

Gonginx provides two ways to regenerate Nginx configuration from a config.Config object:

1. To a string: Use dumper.DumpConfig(conf, style). Use dumper.IndentedStyle for human-readable output.
2. To a file: Use dumper.WriteConfig(conf, style, overwrite). You can set the target path on the config object itself using conf.FilePath = filePath before calling this.

Available styles include dumper.IndentedStyle.

// Dump to string
dumpString := dumper.DumpConfig(conf, dumper.IndentedStyle)

// Dump to file
conf.FilePath = "/path/to/nginx.conf"
dumper.WriteConfig(conf, dumper.IndentedStyle, false)

To parse an existing Nginx configuration file from disk, use parser.NewParser(filePath) followed by the .Parse() method. This returns a config.Config object representing the parsed structure.

func parseConfigAndGetPorts(filePath string) ([]string, error) {
	p, err := parser.NewParser(filePath)
	if err != nil {
		return nil, fmt.Errorf("failed to create parser: %w", err)
	}
	conf, err := p.Parse()
	if err != nil {
		return nil, fmt.Errorf("failed to parse config: %w", err)
	}
	// ... use conf to find directives
}

The dumper package manages how the configuration is written back to a file.

• Non-mutating Sort: Using dumper.NoIndentSortedStyle or other sorted dump options will sort the output, but it will not mutate the order of directives in the in-memory AST. This allows you to maintain a specific logical order in your code while producing a formatted output.

To add a completely new directive to an existing block, find the target block, cast it to a *config.Block, and append a new *config.Directive to its Directives slice.

blocks := conf.FindDirectives(blockName)
block := blocks[0].GetBlock()
realBlock := block.(*config.Block)

newDirective := &config.Directive{
	Name:       directiveName,
	Parameters: []string{directiveValue},
}
realBlock.Directives = append(realBlock.Directives, newDirective)

To modify an existing directive (e.g., changing a proxy_pass URL), find the directive using FindDirectives(name), iterate through the results, and update the Parameters slice directly.

directives := c.FindDirectives("proxy_pass")
for _, directive := range directives {
	if directive.GetParameters()[0] == "http://old-url.com/" {
		directive.GetParameters()[0] = "http://new-url.com/"
	}
}