nginx-c-module-design

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