nginx.org C Module Directive Design Best Practices

Comprehensive directive design guide for nginx C module authors, focused on creating clear, consistent, and admin-friendly configuration interfaces. Contains 46 rules across 8 categories, prioritized by impact to guide decisions about what to expose, how to name it, and how to evolve it safely.

When to Apply

Reference these guidelines when:

• Deciding which values to expose as directives vs hardcode
• Naming new directives and choosing argument types
• Selecting scope placement (http, server, location)
• Setting default values and validation behavior
• Designing nginx variables for runtime data
• Deprecating or renaming existing directives

Companion Skills

This skill focuses on design decisions (the "what" and "why"). For implementation mechanics, see:

• nginx-c-modules — C implementation: memory pools, request lifecycle, config parsing, handlers, filters
• nginx-c-perf — Performance: buffers, connections, locks, caching, timeouts
• nginx-c-debug — Debugging: crash diagnosis, GDB, tracing, sanitizers

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Exposure Decisions	CRITICAL	expose-
2	Naming Conventions	CRITICAL	naming-
3	Directive Types	HIGH	type-
4	Scope Design	HIGH	scope-
5	Default Values	MEDIUM-HIGH	default-
6	Validation & Error Messages	MEDIUM	valid-
7	Variable Design	MEDIUM	var-
8	Evolution & Compatibility	LOW-MEDIUM	compat-

Quick Reference

1. Exposure Decisions (CRITICAL)

• expose-configurable-vs-hardcode - Framework for Configurable vs Hardcoded Values
• expose-escape-hatch - Provide Escape Hatches for Hardcoded Defaults
• expose-feature-gate - Use Feature Gates for Optional Behavior
• expose-too-many-directives - Avoid Over-Configuration
• expose-path-resource - Always Expose External Resource Paths
• expose-security-surface - Audit Security Implications of Every Exposed Directive
• expose-environment-dependent - Expose Values That Vary by Deployment Environment

2. Naming Conventions (CRITICAL)

• naming-module-prefix - Use a Consistent Module Prefix for All Directives
• naming-sub-prefix-groups - Group Related Directives with Sub-Prefixes
• naming-noun-over-verb - Prefer Noun Phrases for Directive Names
• naming-no-abbreviations - Avoid Custom Abbreviations in Directive Names
• naming-cross-module-consistency - Mirror Nginx Core Suffix Patterns for Analogous Directives
• naming-lowercase-underscore - Use Lowercase with Underscores Only

3. Directive Types (HIGH)

• type-flag-for-toggles - Use NGX_CONF_FLAG for Binary Toggles
• type-enum-over-string - Use Enum Slot for Known Value Sets
• type-time-size-units - Use Time and Size Slot Functions for Time and Size Values
• type-take-n-fixed-args - Use TAKE1/TAKE2/TAKE12 for Fixed Argument Counts
• type-one-more-lists - Use 1MORE for Variable-Length Value Lists
• type-avoid-block - Avoid Block Directives for Features
• type-custom-handler-complex - Use Custom Handlers for Complex Directive Parsing

4. Scope Design (HIGH)

• scope-default-three-levels - Default to http + server + location Scope
• scope-http-only-shared-resources - Restrict Shared Resource Directives to http Level Only
• scope-server-connection-level - Use http + server Scope for Connection-Level Settings
• scope-avoid-if-context - Do Not Support the if Context Unless Fully Tested
• scope-location-path-operations - Restrict Path-Routing Directives to Location Context

5. Default Values (MEDIUM-HIGH)

• default-zero-config-safe - Ensure Zero-Config Produces Safe Behavior
• default-performance-optin - Make Performance Features Opt-In
• default-safety-on - Default Security Settings to Restrictive Values
• default-generous-timeouts - Default Timeouts to Generous Values
• default-zero-unlimited - Use Zero to Mean Unlimited or Disabled for Numeric Limits
• default-platform-aware-buffers - Use Platform-Aware Buffer Size Defaults

6. Validation & Error Messages (MEDIUM)

• valid-parse-time-check - Validate All Directive Values at Config Parse Time
• valid-show-invalid-value - Include the Invalid Value in Error Messages
• valid-suggest-range - Include Valid Range or Format in Error Messages
• valid-conflict-detection - Detect Conflicting Directives at Merge Time
• valid-actionable-guidance - Provide Actionable Guidance in Error Messages

7. Variable Design (MEDIUM)

• var-runtime-data-only - Expose Variables for Per-Request Runtime Data Only
• var-naming-convention - Name Variables with Module Prefix and Descriptive Suffix
• var-dynamic-prefix - Use Dynamic Prefix Variables for Key-Value Data
• var-lazy-evaluation - Leverage Lazy Evaluation for Expensive Variables
• var-in-directive-values - Support Variables in Directive Values Only When Per-Request Variation Is Needed
• var-read-only-diagnostics - Expose Read-Only Diagnostic Variables for Observability

8. Evolution & Compatibility (LOW-MEDIUM)

• compat-deprecation-warning - Log Warnings for Deprecated Directives Before Removal
• compat-alias-old-directive - Keep Old Directive Name as an Alias
• compat-multi-version-window - Maintain a Multi-Version Deprecation Window
• compat-document-migration - Document Migration Path in Both Old and New Directive Documentation

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information