nginx-c-modules

nginx.org C モジュール開発のベストプラクティス

nginx の公式開発ドキュメントとコミュニティの知見に基づく、nginx C モジュールの包括的な開発ガイドです。8 つのカテゴリにわたる 49 のルールを含み、影響度に応じて優先順位を付けることで、モジュールを正しく実装し、よくあるクラッシュ、メモリリーク、未定義動作を防ぎます。

適用するタイミング

次の作業では、これらのガイドラインを参照してください。

• 新しい nginx C モジュール（ハンドラー、フィルター、アップストリーム、ロードバランサー）を作成するとき
• 設定ディレクティブとマージロジックを実装するとき
• nginx のプールと共有メモリゾーンを使用してメモリを管理するとき
• HTTP リクエストのライフサイクル（ボディの読み取り、サブリクエスト、完了処理）を扱うとき
• nginx のイベントループ、タイマー、スレッドプールを使用するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	メモリ管理	CRITICAL	mem-
2	リクエストのライフサイクル	CRITICAL	req-
3	設定システム	HIGH	conf-
4	ハンドラー開発	HIGH	handler-
5	フィルターチェーン	MEDIUM-HIGH	filter-
6	アップストリームとプロキシ	MEDIUM	upstream-
7	イベントループと並行処理	MEDIUM	event-
8	データ構造と文字列	LOW-MEDIUM	ds-

クイックリファレンス

1. メモリ管理（CRITICAL）

• mem-pool-allocation - ヒープの malloc ではなく、プール割り当てを使用する
• mem-check-allocation - すべての割り当ての戻り値が NULL かどうか確認する
• mem-pcalloc-structs - 構造体の初期化に ngx_pcalloc を使用する
• mem-cleanup-handlers - 外部リソースにプールクリーンアップハンドラーを登録する
• mem-pnalloc-strings - 文字列データの割り当てに ngx_pnalloc を使用する
• mem-pfree-limitations - プール割り当てで ngx_pfree に依存しない
• mem-shared-slab - 共有メモリゾーンにはスラブアロケーターを使用する

2. リクエストのライフサイクル（CRITICAL）

• req-finalize-once - リクエストを完了処理するのは必ず 1 回だけにする
• req-no-access-after-finalize - 完了処理後にリクエストへアクセスしない
• req-body-async - リクエストボディの読み取りを非同期で処理する
• req-discard-body - 読み取らないリクエストボディは破棄する
• req-subrequest-completion - 完了処理にはサブリクエスト後のハンドラーを使用する
• req-count-reference - 非同期処理の前にリクエストカウントを増やす
• req-internal-redirect - 内部リダイレクト後は処理を返す

3. 設定システム（HIGH）

• conf-unset-init - UNSET 定数を使って設定フィールドを初期化する
• conf-merge-all-fields - merge_loc_conf ですべての設定フィールドをマージする
• conf-context-flags - ディレクティブに正しいコンテキストフラグを使用する
• conf-null-command - コマンド配列の末尾を ngx_null_command にする
• conf-custom-handler - 複雑なディレクティブ解析にはカスタムハンドラーを使用する
• conf-module-ctx-null - 使用しないモジュールコンテキストのコールバックを NULL に設定する
• conf-build-config - モジュールのコンパイルに適した config ビルドスクリプトを記述する

4. ハンドラー開発（HIGH）

• handler-send-header-first - ボディ出力の前にヘッダーを送信する
• handler-last-buf - 最終バッファーで last_buf フラグを設定する
• handler-phase-registration - postconfiguration でフェーズハンドラーを登録する
• handler-content-handler - ロケーション固有のレスポンス生成には content_handler を使用する
• handler-error-page - エラーレスポンスでは HTTP ステータスコードを返す
• handler-empty-response - ボディが空のレスポンスには header_only を使用する
• handler-module-ctx - リクエストごとの状態にはモジュールコンテキストを使用する
• handler-add-variable - preconfiguration でカスタム変数を登録する

5. フィルターチェーン（MEDIUM-HIGH）

• filter-registration-order - postconfiguration でトップフィルターを保存して置き換える
• filter-call-next - チェーン内の次のフィルターを必ず呼び出す
• filter-check-subrequest - フィルター内でメインリクエストとサブリクエストを区別する
• filter-buffer-chain-iteration - cl->next パターンを使ってバッファーチェーンを反復処理する
• filter-buffering-flag - レスポンスデータの蓄積時にバッファリングフラグを設定する

6. アップストリームとプロキシ（MEDIUM）

• upstream-create-request - create_request で完全なリクエストバッファーを構築する
• upstream-process-header - process_header でアップストリームレスポンスを段階的に解析する
• upstream-peer-free - Peer free コールバックで失敗を追跡する
• upstream-finalize - finalize_request コールバックでリソースをクリーンアップする
• upstream-connection-reuse - アップストリーム接続で Keepalive を有効にする

7. イベントループと並行処理（MEDIUM）

• event-no-blocking - イベントハンドラー内ではブロッキング呼び出しを使用しない
• event-timer-management - 関連データを解放する前にタイマーを削除する
• event-handle-read-write - I/O 操作後に ngx_handle_read/write_event を呼び出す
• event-thread-pool - ブロッキング操作をスレッドプールに移す
• event-posted-events - 遅延処理にはポスト済みイベントを使用する

8. データ構造と文字列（LOW-MEDIUM）

• ds-ngx-str-not-null-terminated - ngx_str_t がヌル終端されていると仮定しない
• ds-ngx-str-set-literals - ngx_string マクロは文字列リテラルにのみ使用する
• ds-cpymem-pattern - バッファーへの連続書き込みには ngx_cpymem を使用する
• ds-list-iteration - 部分ベースのパターンを使って ngx_list_t を反復処理する
• ds-hash-readonly - ハッシュテーブルは設定時にのみ構築する

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクション定義 - カテゴリー構成と影響レベル
• ルールテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報