nginx.org C Module Development Best Practices

Comprehensive development guide for nginx C modules, derived from the official nginx development documentation and community expertise. Contains 49 rules across 8 categories, prioritized by impact to guide correct module implementation and prevent common crashes, memory leaks, and undefined behavior.

When to Apply

Reference these guidelines when:

• Writing new nginx C modules (handlers, filters, upstream, load-balancers)
• Implementing configuration directives and merge logic
• Managing memory with nginx pools and shared memory zones
• Handling the HTTP request lifecycle (body reading, subrequests, finalization)
• Working with nginx’s event loop, timers, and thread pools

Rule Categories by Priority

Quick Reference

1. Memory Management (CRITICAL)

• mem-pool-allocation – Use Pool Allocation Instead of Heap malloc
• mem-check-allocation – Check Every Allocation Return for NULL
• mem-pcalloc-structs – Use ngx_pcalloc for Struct Initialization
• mem-cleanup-handlers – Register Pool Cleanup Handlers for External Resources
• mem-pnalloc-strings – Use ngx_pnalloc for String Data Allocation
• mem-pfree-limitations – Avoid Relying on ngx_pfree for Pool Allocations
• mem-shared-slab – Use Slab Allocator for Shared Memory Zones

2. Request Lifecycle (CRITICAL)

• req-finalize-once – Finalize Requests Exactly Once
• req-no-access-after-finalize – Never Access Request After Finalization
• req-body-async – Handle Request Body Reading Asynchronously
• req-discard-body – Discard Request Body When Not Reading It
• req-subrequest-completion – Use Post-Subrequest Handlers for Completion
• req-count-reference – Increment Request Count Before Async Operations
• req-internal-redirect – Return After Internal Redirect

3. Configuration System (HIGH)

• conf-unset-init – Initialize Config Fields with UNSET Constants
• conf-merge-all-fields – Merge All Config Fields in merge_loc_conf
• conf-context-flags – Use Correct Context Flags for Directives
• conf-null-command – Terminate Commands Array with ngx_null_command
• conf-custom-handler – Use Custom Handlers for Complex Directive Parsing
• conf-module-ctx-null – Set Unused Module Context Callbacks to NULL
• conf-build-config – Write Correct config Build Script for Module Compilation

4. Handler Development (HIGH)

• handler-send-header-first – Send Header Before Body Output
• handler-last-buf – Set last_buf Flag on Final Buffer
• handler-phase-registration – Register Phase Handlers in postconfiguration
• handler-content-handler – Use content_handler for Location-Specific Response Generation
• handler-error-page – Return HTTP Status Codes for Error Responses
• handler-empty-response – Use header_only for Empty Body Responses
• handler-module-ctx – Use Module Context for Per-Request State
• handler-add-variable – Register Custom Variables in preconfiguration

5. Filter Chain (MEDIUM-HIGH)

• filter-registration-order – Save and Replace Top Filter in postconfiguration
• filter-call-next – Always Call Next Filter in the Chain
• filter-check-subrequest – Distinguish Main Request from Subrequest in Filters
• filter-buffer-chain-iteration – Iterate Buffer Chains Using cl->next Pattern
• filter-buffering-flag – Set Buffering Flag When Accumulating Response Data

6. Upstream & Proxy (MEDIUM)

• upstream-create-request – Build Complete Request Buffer in create_request
• upstream-process-header – Parse Upstream Response Incrementally in process_header
• upstream-peer-free – Track Failures in Peer free Callback
• upstream-finalize – Clean Up Resources in finalize_request Callback
• upstream-connection-reuse – Enable Keepalive for Upstream Connections

7. Event Loop & Concurrency (MEDIUM)

• event-no-blocking – Never Use Blocking Calls in Event Handlers
• event-timer-management – Delete Timers Before Freeing Associated Data
• event-handle-read-write – Call ngx_handle_read/write_event After I/O Operations
• event-thread-pool – Offload Blocking Operations to Thread Pool
• event-posted-events – Use Posted Events for Deferred Processing

8. Data Structures & Strings (LOW-MEDIUM)

• ds-ngx-str-not-null-terminated – Never Assume ngx_str_t Is Null-Terminated
• ds-ngx-str-set-literals – Use ngx_string Macro Only with String Literals
• ds-cpymem-pattern – Use ngx_cpymem for Sequential Buffer Writes
• ds-list-iteration – Iterate ngx_list_t Using Part-Based Pattern
• ds-hash-readonly – Build Hash Tables During Configuration Only

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