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

Priority	Category	Impact	Prefix
1	Memory Management	CRITICAL	mem-
2	Request Lifecycle	CRITICAL	req-
3	Configuration System	HIGH	conf-
4	Handler Development	HIGH	handler-
5	Filter Chain	MEDIUM-HIGH	filter-
6	Upstream & Proxy	MEDIUM	upstream-
7	Event Loop & Concurrency	MEDIUM	event-
8	Data Structures & Strings	LOW-MEDIUM	ds-

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

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