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

mem-

req-

conf-

handler-

filter-

upstream-

event-

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