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

expose-

naming-

type-

scope-

default-

valid-

var-

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