Crate nginx_lint_plugin 

Plugin SDK for building nginx-lint WASM plugins

This crate provides everything needed to create custom lint rules as WASM plugins for nginx-lint.

Getting Started

1. Create a library crate with crate-type = ["cdylib", "rlib"]
2. Implement the Plugin trait
3. Register with export_component_plugin!
4. Build with cargo build --target wasm32-unknown-unknown --release

Modules

• [types] - Core types: Plugin, PluginSpec, LintError, Fix, ConfigExt, DirectiveExt
• helpers - Utility functions for common checks (domain names, URLs, etc.)
• testing - Test runner and builder: testing::PluginTestRunner, testing::TestCase
• native - native::NativePluginRule adapter for running plugins without WASM
• prelude - Convenient re-exports for use nginx_lint_plugin::prelude::*

API Versioning

Plugins declare the API version they use via PluginSpec::api_version. This allows the host to support multiple output formats for backward compatibility. PluginSpec::new() automatically sets the current API version (API_VERSION).

Example

use nginx_lint_plugin::prelude::*;

#[derive(Default)]
struct MyRule;

impl Plugin for MyRule {
    fn spec(&self) -> PluginSpec {
        PluginSpec::new("my-custom-rule", "custom", "My custom lint rule")
            .with_severity("warning")
            .with_why("Explain why this rule matters.")
            .with_bad_example("server {\n    dangerous_directive on;\n}")
            .with_good_example("server {\n    # dangerous_directive removed\n}")
    }

    fn check(&self, config: &Config, _path: &str) -> Vec<LintError> {
        let mut errors = Vec::new();
        let err = self.spec().error_builder();

        for ctx in config.all_directives_with_context() {
            if ctx.directive.is("dangerous_directive") {
                errors.push(
                    err.warning_at("Avoid using dangerous_directive", ctx.directive)
                );
            }
        }
        errors
    }
}

// export_component_plugin!(MyRule);  // Required for WASM build

// Verify it works
let plugin = MyRule;
let config = nginx_lint_plugin::parse_string("dangerous_directive on;").unwrap();
let errors = plugin.check(&config, "test.conf");
assert_eq!(errors.len(), 1);

Re-exports

pub use nginx_lint_common::parser;

Modules

helpers

Helper functions for plugin development

native

Native plugin adapter.

prelude

Prelude module for convenient imports.

testing

Testing utilities for plugin development.

Macros

export_component_plugin

Macro to export a plugin as a WIT component

fixtures_dir

Macro to get the fixtures directory path relative to the plugin’s Cargo.toml

Structs

AllDirectivesWithContextIter

Iterator over all directives with their parent context.

Argument

A single argument to a directive.

Block

A brace-delimited block ({ … }).

Comment

A comment (# …)

Config

Root node of a parsed nginx configuration file.

Directive

A directive — either a simple directive (listen 80;) or a block directive (server { … }).

DirectiveWithContext

A directive paired with its parent block context.

ErrorBuilder

Builder for creating LintError with pre-filled rule and category

Fix

Represents a fix that can be applied to automatically resolve a lint error.

LintError

A lint error reported by a plugin.

PluginSpec

Plugin metadata describing a lint rule.

Position

A position (line, column, byte offset) in the source text.

Span

A half-open source range defined by a start and end Position.

Enums

ArgumentValue

The kind and value of a directive argument.

ConfigItem

An item in the configuration (directive, comment, or blank line).

Severity

Severity level for lint errors

Constants

API_VERSION

Current API version for the plugin SDK

Traits

ArgumentExt

Extension trait for Argument to add source reconstruction

ConfigExt

Extension trait for Config providing iteration and include-context helpers.

DirectiveExt

Extension trait for Directive providing inspection and fix-generation helpers.

Plugin

Trait that all plugins must implement.

Functions

parse_string

Parse nginx configuration from a string