開発ガイド

はじめに
     コード レイアウト
     インクルード ファイル
     数字
     共通 リターン コード
     エラーハンドリング
文字列
     概要
     フォーマット
     数値変換
     正規表現
コンテナ
     配列
     リスト
     キュー
     Red-Black tree
     ハッシュ
メモリ管理
     ヒープ
     プール
     共有メモリ
ログ
サイクル
バッファ
ネットワーク
     接続
イベント
     イベント
     I/O イベント
     タイマー イベント
     ポストされたイベント
     イベント ループ
プロセス
モジュール
     新しいモジュールの追加
     コア モジュール
     設定ディレクティブ
HTTP
     接続
     リクエスト
     設定
     フェーズ
     変数
     複雑な値
     応答
     応答ボディ
     ボディ フィルタ
     フィルタ モジュールのビルド
     バッファの再利用
     ロードバランシング

はじめに

コード レイアウト

インクルードファイル

各nginxファイルは以下の二つのファイルを含むところから始まらなければなりません: 

#include <ngx_config.h>
#include <ngx_core.h>

それに加えて、HTTPコードは以下を含まなければなりません 

#include <ngx_http.h>

メールコードは以下を含まなければなりません 

#include <ngx_mail.h>

ストリームコードは以下を含まなければなりません 

#include <ngx_stream.h>

整数

一般的な目的のために、nginxのコードはintptr_tとuintptr_tについての型定義である二つ整数型 ngx_int_t と ngx_uint_tを使います。

共通リターンコード

nginxのほとんどの関数は以下のコードを返します:

エラーハンドリング

最後のシステムエラーコードを取得するために、ngx_errno マクロが利用可能です。POSIXプラットフォーム上のerrnoにマップされ、Windows内でGetLastError() コールにマップされます。最後のソケットエラー番号を取得するために、ngx_socket_errno マクロが利用可能です。POSIXシステム上のerrno にマップされ、Windows上でWSAGetLastError() にマップされます。パフォーマンス上の理由でngx_errno あるいは ngx_socket_errno の値は連続して1回以上アクセスされるべきではありません。必要であれば、複数回使うために、エラー値はローカル変数型 ngx_err_t に格納されるべきです。エラーを設定するために、ngx_set_errno(errno) および ngx_set_socket_errno(errno) マクロが利用可能です。

ngx_errno あるいは ngx_socket_errno の値はログ関数ngx_log_error() と ngx_log_debugX() に渡すことができ、その場合、システムエラーテキストがログメッセージに追加されます。

ngx_errnoを使う例: 

void
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
    ngx_err_t  err;

    if (kill(pid, signo) == -1) {
        err = ngx_errno;

        ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);

        if (err == NGX_ESRCH) {
            return 2;
        }

        return 1;
    }

    return 0;
}

文字列

概要

Cの文字列については、nginxのコードは符号無し文字型ポインタ u_char * を使います。

nginxの文字列型 ngx_str_t は以下のように定義されます: 

typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;

len フィールドは文字列の長さを保持し、data は文字列のデータを保持します。ngx_str_tに保持されている文字列はlen バイトの後にnull終端子があるかも知れません。ほとんどの場合はありません。しかし、コードのある部分(例えば、設定をパースする場合)、ngx_str_t オブジェクトはnull終端だと知られていて、その知見は文字列の比較を単純化するために使われ、それらの文字列をシステムコールに渡すのを容易にします。

多くの文字列オペレータがnginx内で提供されます。それらはsrc/core/ngx_string.h内で定義されます。それらの幾つかは標準C関数をラップします:

幾つかのnginx固有の文字列関数:

幾つかの変換と比較関数:

フォーマット

多くのフォーマット関数がnginxによって提供されます。これらの関数はnginx固有の型をサポートします:

これらの関数によってサポートされるフォーマットオプションの完全なリストはsrc/core/ngx_string.cの中で見つけることができます。それらのうちの幾つか: 

%O — off_t
%T — time_t
%z — size_t
%i — ngx_int_t
%p — void *
%V — ngx_str_t *
%s — u_char * (null-terminated)
%*s — size_t + u_char *

The ‘u’ modifier makes most types unsigned, ‘X’/‘x’ convert output to hex.

例: 

u_char     buf[NGX_INT_T_LEN];
size_t     len;
ngx_int_t  n;

/* set n here */

len = ngx_sprintf(buf, "%ui", n) — buf;

数値変換

数値変換の幾つかの関数はnginx内で実装されています:

正規表現

nginxでの正規表現インタフェースはPCRE ライブラリのラッパーです。対応するヘッダファイルは src/core/ngx_regex.hです。

文字列のマッチングのために正規表現を使うためには、まず、コンパイルされる必要があります。これは通常設定フェーズで行われます。PCREサポートは任意のため、インタフェースを使用している全てのコードは周りを取り巻くNGX_PCRE マクロによって保護されなければなりません: 

#if (NGX_PCRE)
ngx_regex_t          *re;
ngx_regex_compile_t   rc;

u_char                errstr[NGX_MAX_CONF_ERRSTR];

ngx_str_t  value = ngx_string("message (\\d\\d\\d).*Codeword is '(?<cw>\\w+)'");

ngx_memzero(&rc, sizeof(ngx_regex_compile_t));

rc.pattern = value;
rc.pool = cf->pool;
rc.err.len = NGX_MAX_CONF_ERRSTR;
rc.err.data = errstr;
/* rc.options are passed as is to pcre_compile() */

if (ngx_regex_compile(&rc) != NGX_OK) {
    ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err);
    return NGX_CONF_ERROR;
}

re = rc.regex;
#endif

After successful compilation, ngx_regex_compile_t structure fields captures and named_captures are filled with count of all and named captures respectively found in the regular expression.

Later, the compiled regular expression may be used to match strings against it: 

ngx_int_t  n;
int        captures[(1 + rc.captures) * 3];

ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");

n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3);
if (n >= 0) {
    /* string matches expression */

} else if (n == NGX_REGEX_NO_MATCHED) {
    /* no match was found */

} else {
    /* some error */
    ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
}

The arguments of ngx_regex_exec() are: the compiled regular expression re, string to match s, optional array of integers to hold found captures and its size. The captures array size must be a multiple of three, per requirements of the PCRE API. In the example, its size is calculated from a total number of captures plus one for the matched string itself.

Now, if there are matches, captures may be accessed: 

u_char     *p;
size_t      size;
ngx_str_t   name, value;

/* all captures */
for (i = 0; i < n * 2; i += 2) {
    value.data = input.data + captures[i];
    value.len = captures[i + 1] — captures[i];
}

/* accessing named captures */

size = rc.name_size;
p = rc.names;

for (i = 0; i < rc.named_captures; i++, p += size) {

    /* capture name */
    name.data = &p[2];
    name.len = ngx_strlen(name.data);

    n = 2 * ((p[0] << 8) + p[1]);

    /* captured value */
    value.data = &input.data[captures[n]];
    value.len = captures[n + 1] — captures[n];
}

The ngx_regex_exec_array() function accepts the array of ngx_regex_elt_t elements (which are just compiled regular expressions with associated names), a string to match and a log. The function will apply expressions from the array to the string until the match is found or no more expressions are left. 合致した場合には返り値はNGX_OKで、そうでなければNGX_DECLINED、あるいはエラー時にはNGX_ERROR です。

コンテナ

配列

nginx配列型ngx_array_t は以下のように定義されます 

typedef struct {
    void        *elts;
    ngx_uint_t   nelts;
    size_t       size;
    ngx_uint_t   nalloc;
    ngx_pool_t  *pool;
} ngx_array_t;

配列の要素はelts フィールドを使って利用可能です。要素の数はnelts フィールドに格納されています。size フィールドは1つの要素のサイズを保持し、配列を初期化する時に設定されます。

配列はngx_array_create(pool, n, size) 呼び出しを使ってプール内に生成することができます。既に割り当てられている配列オブジェクトは ngx_array_init(array, pool, n, size) 呼び出しを使って初期化することができます。 

ngx_array_t  *a, b;

/* create an array of strings with preallocated memory for 10 elements */
a = ngx_array_create(pool, 10, sizeof(ngx_str_t));

/* initialize string array for 10 elements */
ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));

配列への要素の追加は以下の関数を使って行われます:

もし現在割り当てられているメモリが新しい要素に十分ではない場合、要素のための新しいメモリが割り当てられ、既存の要素がメモリにコピーされるでしょう。新しいメモリブロックは通常既存のものの2倍の大きさです。 

s = ngx_array_push(a);
ss = ngx_array_push_n(&b, 3);

リスト

nginxでのリストは配列の系列で、潜在的に大量の項目を挿入できるように最適化されています。リストの型は以下のように定義されます: 

typedef struct {
    ngx_list_part_t  *last;
    ngx_list_part_t   part;
    size_t            size;
    ngx_uint_t        nalloc;
    ngx_pool_t       *pool;
} ngx_list_t;

実施あの項目は、以下で定義されるリストの一部に格納されます: 

typedef struct ngx_list_part_s  ngx_list_part_t;

struct ngx_list_part_s {
    void             *elts;
    ngx_uint_t        nelts;
    ngx_list_part_t  *next;
};

最初に、リストはngx_list_init(list, pool, n, size) の呼び出しで初期化されるか、ngx_list_create(pool, n, size)の呼び出しで生成されなければなりません。両方の関数とも1つの項目のサイズとリスト部分ごとの項目の数を受け取ります。ngx_list_push(list) 関数はリストに項目を追加するために使われます。以下の例で分かるように、直接リストのフィールドにアクセスすることで項目の繰り返しが行われます。 

ngx_str_t        *v;
ngx_uint_t        i;
ngx_list_t       *list;
ngx_list_part_t  *part;

list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
if (list == NULL) { /* error */ }

/* add items to the list */

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "foo");

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "bar");

/* iterate over the list */

part = &list->part;
v = part->elts;

for (i = 0; /* void */; i++) {

    if (i >= part->nelts) {
        if (part->next == NULL) {
            break;
        }

        part = part->next;
        v = part->elts;
        i = 0;
    }

    ngx_do_smth(&v[i]);
}

nginxでのリストの主要な使い方はHTTP入力と出力ヘッダです。

リストは項目の削除をサポートしません。しかし、必要であれば、項目はリストから実際に削除すること無しに外すように内部的に印をつけることができます。例えば、ngx_table_elt_t として格納されているHTTP出力ヘッダは、ngx_table_elt_tのhash フィールドをゼロに設定することで外すことができます。ヘッダ上を繰り返す時に、そのような項目は明示的にスキップされます。

キュー

nginxでのキューは各ノードが以下のように定義されている二重にリンクされた出しゃばりのリストです: 

typedef struct ngx_queue_s  ngx_queue_t;

struct ngx_queue_s {
    ngx_queue_t  *prev;
    ngx_queue_t  *next;
};

先頭のキューノードはどのようなデータともリンクしていません。使う前に、リストの先頭はngx_queue_init(q) 呼び出しで初期化される必要があります。キューは以下の操作をサポートします:

例: 

typedef struct {
    ngx_str_t    value;
    ngx_queue_t  queue;
} ngx_foo_t;

ngx_foo_t    *f;
ngx_queue_t   values;

ngx_queue_init(&values);

f = ngx_palloc(pool, sizeof(ngx_foo_t));
if (f == NULL) { /* error */ }
ngx_str_set(&f->value, "foo");

ngx_queue_insert_tail(&values, f);

/* insert more nodes here */

for (q = ngx_queue_head(&values);
     q != ngx_queue_sentinel(&values);
     q = ngx_queue_next(q))
{
    f = ngx_queue_data(q, ngx_foo_t, queue);

    ngx_do_smth(&f->value);
}

赤黒木

src/core/ngx_rbtree.hヘッダファイルは赤黒木の効果的な実装への参照を提供します。 

typedef struct {
    ngx_rbtree_t       rbtree;
    ngx_rbtree_node_t  sentinel;

    /* custom per-tree data here */
} my_tree_t;

typedef struct {
    ngx_rbtree_node_t  rbnode;

    /* custom per-node data */
    foo_t              val;
} my_node_t;

木を全体として扱うために、二つのノードが必要です: ルートと歩哨です。一般的にそれらは何らかの独自の構造に追加されます。従ってデータを葉がデータへのリンクあるいはデータを埋め込む木へ整理することができます。

木を初期化するには: 

my_tree_t  root;

ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);

insert_value_function は木を行き来し、新しい値を正しい場所に挿入する責任を持つ関数です。例えば、ngx_str_rbtree_insert_value 関数はngx_str_t 型を扱うように設計されています。 

void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
                                 ngx_rbtree_node_t *node,
                                 ngx_rbtree_node_t *sentinel)

引数は、挿入の付け根のノードへのポインタ、追加される新しく作成されたノード、および木の歩哨です。

行き来はとても率直なもので、以下の捜索機能パターンを使って実演することができます: 

my_node_t *
my_rbtree_lookup(ngx_rbtree_t *rbtree, foo_t *val, uint32_t hash)
{
    ngx_int_t           rc;
    my_node_t          *n;
    ngx_rbtree_node_t  *node, *sentinel;

    node = rbtree->root;
    sentinel = rbtree->sentinel;

    while (node != sentinel) {

        n = (my_node_t *) node;

        if (hash != node->key) {
            node = (hash < node->key) ? node->left : node->right;
            continue;
        }

        rc = compare(val, node->val);

        if (rc < 0) {
            node = node->left;
            continue;
        }

        if (rc > 0) {
            node = node->right;
            continue;
        }

        return n;
    }

    return NULL;
}

compare() は、ゼロより少ない、等しい、あるいは大きいという値を返す伝統的な比較器です。検索を高速化し、大きいかも知れないユーザのオブジェクトの比較を避けるために、整数のハッシュフィールドが使われます。

ノードを木に追加するために、新しいノードを割り当て、それを初期化し、そしてngx_rbtree_insert()を呼びます: 

    my_node_t          *my_node;
    ngx_rbtree_node_t  *node;

    my_node = ngx_palloc(...);
    init_custom_data(&my_node->val);

    node = &my_node->rbnode;
    node->key = create_key(my_node->val);

    ngx_rbtree_insert(&root->rbtree, node);

ノードを削除するには: 

ngx_rbtree_delete(&root->rbtree, node);

ハッシュ

ハッシュテーブル関数は src/core/ngx_hash.h で定義されています。正確、およびワイルドカードの合致がサポートされます。後者は特別なセットアップを必要とし、以下の別の章で説明されます。

nginxはハッシュを任意でビルドすることができるため、ハッシュを初期化するには、前もって要素の数を知る必要があります。設定するために必要な二つのパラメータは max_size と bucket_size です。これらのセットアップの詳細は、別のドキュメントの中で提供されます。通常、これらの二つのパラメータはユーザによって設定されます:ハッシュの初期化設定はngx_hash_init_t 型として格納され、ハッシュ自身は ngx_hash_tです: 

ngx_hash_t       foo_hash;
ngx_hash_init_t  hash;

hash.hash = &foo_hash;
hash.key = ngx_hash_key;
hash.max_size = 512;
hash.bucket_size = ngx_align(64, ngx_cacheline_size);
hash.name = "foo_hash";
hash.pool = cf->pool;
hash.temp_pool = cf->temp_pool;

キー は文字列からハッシュの整数キーを生成する関数へのポインタです。二つの一般的な関数が提供されています:ngx_hash_key(data, len) と ngx_hash_key_lc(data, len)。後者は文字列を小文字に変換します。従って渡される文字列が書き込み可能である必要があります。そうでない場合は、配列キーを初期化するNGX_HASH_READONLY_KEY フラグが関数に渡されるかも知れません (以下を見てください)。

ハッシュのキーはngx_hash_keys_arrays_tに格納され、ngx_hash_keys_array_init(arr, type)を使って初期化されます: 

ngx_hash_keys_arrays_t  foo_keys;

foo_keys.pool = cf->pool;
foo_keys.temp_pool = cf->temp_pool;

ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);

二つ目のパラメータはNGX_HASH_SMALL あるいは NGX_HASH_LARGE のどちらかが可能で、ハッシュのための予め割り当てられるリソースの量を制御します。ハッシュが多数の要素を含むことが期待される場合、NGX_HASH_LARGEを使ってください。

ngx_hash_add_key(keys_array, key, value, flags)関数はキーをハッシュキー配列に挿入するために使われます; 

ngx_str_t k1 = ngx_string("key1");
ngx_str_t k2 = ngx_string("key2");

ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY);
ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY);

ここで、ハッシュテーブルはngx_hash_init(hinit, key_names, nelts)の呼び出しを使って構築されるかも知れません: 

ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);

max_size あるいは bucket_size パラメータが十分に大きくない場合は、これは失敗するかも知れません。ハッシュが構築される時、ngx_hash_find(hash, key, name, len) 関数は要素を調べるために使われるかも知れません: 

my_data_t   *data;
ngx_uint_t   key;

key = ngx_hash_key(k1.data, k1.len);

data = ngx_hash_find(&foo_hash, key, k1.data, k1.len);
if (data == NULL) {
    /* key not found */
}

ワイルドカード マッチング

ワイルドカードを使って動作するハッシュを生成するには、ngx_hash_combined_t 型が使われます。それは、上で説明されるハッシュ型を含み、二つの追加のキー配列を持ちます: dns_wc_head と dns_wc_tail。基本的なプロパティの初期化は通常のハッシュと同じように行われます: 

ngx_hash_init_t      hash
ngx_hash_combined_t  foo_hash;

hash.hash = &foo_hash.hash;
hash.key = ...;

NGX_HASH_WILDCARD_KEY フラグを使ってワイルドカードキーを追加することが可能です: 

/* k1 = ".example.org"; */
/* k2 = "foo.*";        */
ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY);
ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY);

関数はワイルドカードを理解し、キーを対応する配列に追加します。ワイルドカードの構文と合致アルゴリズムの説明については、map モジュールのドキュメントを参照してください。

追加されたキーの内容に依存して、三つのキー配列を初期化する必要があるかも知れません: 1つは(上で説明された)完全な合致のため、2つは文字列の始まりあるいは終わりから開始する合致のためです。 

if (foo_keys.dns_wc_head.nelts) {

    ngx_qsort(foo_keys.dns_wc_head.elts,
              (size_t) foo_keys.dns_wc_head.nelts,
              sizeof(ngx_hash_key_t),
              cmp_dns_wildcards);

    hash.hash = NULL;
    hash.temp_pool = pool;

    if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts,
                               foo_keys.dns_wc_head.nelts)
        != NGX_OK)
    {
        return NGX_ERROR;
    }

    foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
}

キー配列はソートされる必要があり、初期化の結果は結合されたハッシュに追加されなければなりません。dns_wc_tail 配列の初期化は同じように行われます。

結合されたハッシュ内での照合はngx_hash_find_combined(chash, key, name, len)によって扱われます: 

/* key = "bar.example.org"; — will match ".example.org" */
/* key = "foo.example.com"; — will match "foo.*"        */

hkey = ngx_hash_key(key.data, key.len);
res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len);

メモリ管理

ヒープ

システムヒープからメモリを割り当てるために、以下の関数がnginxによって提供されています:

プール

ほとんどのnginxの割り当てはプール内で行われます。nginxのプールで割り当てられたメモリはプールが破壊された時に自動的に開放されます。これにより割り当てのパフォーマンスが良くなり、メモリの制御が簡単になります。

プールはメモリの連続するブロックの中でオブジェクトを内部的に割り当てます。ブロックが埋まると、新しいブロックが割り当てられ、プールメモリブロックリストへ追加されます。ブロックに収まらない大きな割り当てが要求された場合、そのような割り当てはシステムのアロケータに転送され、更なる割り当ての解除のためにプール内に返されたポインタが格納されます。

Nginxのプールは型ngx_pool_tを持ちます。以下の操作がサポートされます: 

u_char      *p;
ngx_str_t   *s;
ngx_pool_t  *pool;

pool = ngx_create_pool(1024, log);
if (pool == NULL) { /* error */ }

s = ngx_palloc(pool, sizeof(ngx_str_t));
if (s == NULL) { /* error */ }
ngx_str_set(s, "foo");

p = ngx_pnalloc(pool, 3);
if (p == NULL) { /* error */ }
ngx_memcpy(p, "foo", 3);

nginxではチェイン リンク ngx_chain_t が積極的に使われるため、nginxのプールはそれらを再利用する方法を提供します。ngx_pool_tの chain フィールドは再利用のために以前割り当てられたリンクのリストを準備し続けます。プール内での効率的なチェインリンクの割り当てのために、関数ngx_alloc_chain_link(pool) が使われるべきです。This function looks up a free chain link in the pool list and only if it's empty allocates a new one. リンクを解放するにはngx_free_chain(pool, cl)が呼ばれるべきです。

クリーンナップ ハンドラはプール内に登録することができます。クリーンナップ ハンドラはプールが破壊される時に呼ばれる引数を持つコールバックです。プールは通常特定の(HTTPリクエスト)のようなnginxオブジェクトと紐付けられ、オブジェクトの生存期間の最後にはオブジェクト自身を解放しながら破壊されます。Registering a pool cleanup is a convenient way to release resources, close file descriptors or make final adjustments to shared data, associated with the main object.

A pool cleanup is registered by calling ngx_pool_cleanup_add(pool, size) which returns ngx_pool_cleanup_t pointer to be filled by the caller. size引数はクリーンナップ ハンドラのためにコンテキストを割り当てることができます。 

ngx_pool_cleanup_t  *cln;

cln = ngx_pool_cleanup_add(pool, 0);
if (cln == NULL) { /* error */ }

cln->handler = ngx_my_cleanup;
cln->data = "foo";

...

static void
ngx_my_cleanup(void *data)
{
    u_char  *msg = data;

    ngx_do_smth(msg);
}

共有メモリ

共有メモリはプロセス間での共通データを共有するためにnginxによって使われます。関数 ngx_shared_memory_add(cf, name, size, tag) はサイクルに新しい共有メモリ エントリ ngx_shm_zone_t を追加します。関数はゾーンのname と size を受け取ります。各共有ゾーンはユニークな名前を持たなければなりません。もし指定された名前を持つ共有ゾーン エントリが存在する場合、タグの値も一致すれば古いゾーン エントリは再利用されます。一致しないタグはエラーと見なされます。通常、モジュール構造のアドレスがタグとして渡され、1つのnginxモジュール内で名前によって共有ゾーンを再利用することができます。

共有メモリ エントリ構造 ngx_shm_zone_t は以下のフィールドを持ちます:

共有ゾーン エントリは設定がパースされた後でngx_init_cycle()内の実際のメモリにマップされます。POSIXシステム上では、mmap() syscall が共有匿名マッピングを生成するために使われます。Windows上では、CreateFileMapping()/MapViewOfFileEx() ペアが使われます。

共有メモリ内で割り当てるために、nginxはスラブ プール ngx_slab_pool_t を提供します。各nginx共有ゾーンの中で、スラブ プールはそのゾーン内でメモリを割り当てるために自動的に生成されます。プールは共有ゾーンの最初に位置していて、表現(ngx_slab_pool_t *) shm_zone->shm.addr によってアクセスすることができます。共有ゾーンでの割り当ては ngx_slab_alloc(pool, size)/ngx_slab_calloc(pool, size)関数のうちの一つの呼び出しによって行われます。メモリは ngx_slab_free(pool, p)の呼び出しによって解放されます。

スラブ プールは全ての共有ゾーンをページに分割します。各ページは同じサイズのオブジェクトを割り当てるために使われます。8以上の二乗のサイズが考慮されます。他のサイズはそれらの値のうちの一つに丸められます。For each page, a bitmask is kept, showing which blocks within that page are in use and which are free for allocation. 半分のページ(通常 2048バイト)より大きい場合、ページ全体まで割り当てが行われます。

同時アクセスから共有メモリ内のデータを守るためには、ngx_slab_pool_tのmutexフィールド内でmutexが利用可能です。メモリを割り当ておよび開放する間、スラブによってmutexが使われます。しかし、それは共有ゾーン内で割り当てられてる他のユーザデータ構造を保護するために使うことができます。ngx_shmtx_lock(&shpool->mutex)を呼び出すことでロッキングが行われ、ngx_shmtx_unlock(&shpool->mutex)を呼び出すことでアンロッキングが行われます。 

ngx_str_t        name;
ngx_foo_ctx_t   *ctx;
ngx_shm_zone_t  *shm_zone;

ngx_str_set(&name, "foo");

/* allocate shared zone context */
ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
if (ctx == NULL) {
    /* error */
}

/* add an entry for 65k shared zone */
shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
if (shm_zone == NULL) {
    /* error */
}

/* register init callback and context */
shm_zone->init = ngx_foo_init_zone;
shm_zone->data = ctx;


...


static ngx_int_t
ngx_foo_init_zone(ngx_shm_zone_t *shm_zone, void *data)
{
    ngx_foo_ctx_t  *octx = data;

    size_t            len;
    ngx_foo_ctx_t    *ctx;
    ngx_slab_pool_t  *shpool;

    value = shm_zone->data;

    if (octx) {
        /* reusing a shared zone from old cycle */
        ctx->value = octx->value;
        return NGX_OK;
    }

    shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;

    if (shm_zone->shm.exists) {
        /* initialize shared zone context in Windows nginx worker */
        ctx->value = shpool->data;
        return NGX_OK;
    }

    /* initialize shared zone */

    ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
    if (ctx->value == NULL) {
        return NGX_ERROR;
    }

    shpool->data = ctx->value;

    return NGX_OK;
}

ログ

nginxのコードを記録するには、ngx_log_t オブジェクトを使います。Nginxのロガーは出力の幾つかのタイプをサポートします:

ロガーインスタンスは実際にはお互いにnext フィールドでリンクされたロガーのチェーンかも知れません。各メッセージはチェーン内で全てのロガーに記録されます。

各ロガーはログに書き込まれるメッセージを制限するエラーレベルを持ちます。以下のエラーレベルがnginxでサポートされます:

デバッグのログのために、デバッグマスクもチェックされます。以下のデバッグマスクが存在します:

通常、ロガーは既存のnginxコードによってerror_log ディレクティブから生成され、サイクル、設定、クライアント接続および他のオブジェクトのほとんど全ての処理のステージで利用可能です。

Nginx は以下のログ マクロを提供します:

ログメッセージはスタック上のサイズNGX_MAX_ERROR_STR (現在のところ 2048 バイト)のバッファ内で整形されます。メッセージはエラーレベル、プロセスID,接続id (log->connectionに格納されています)およびシステムエラー テキストが前に付きます。非デバッグメッセージについては、もっと特定の情報がログメッセージに付くようにlog->handlerが呼ばれます。HTTP モジュールは、クライアントとサーバアドレス、現在のアクション(log->actionに格納されています)、クライアント リクエスト ライン、サーバ名などを記録するためにログ ハンドラとしてngx_http_log_error()関数を設定します。

例: 

/* specify what is currently done */
log->action = "sending mp4 to client”;

/* error and debug log */
ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
              closed connection”);

ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
               "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);

Logging result: 

2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1”
2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000

サイクル

サイクルオブジェクトは特定の設定から生成されるnginxの実行時コンテキストを保持します。サイクルの型はngx_cycle_tです。設定がリロードされる時、新しいサイクルがnginx設定の新しいバージョンから生成されます。古いサイクルは新しいものがうまく生成された後で通常削除されます。現在のところ、活動中のサイクルはngx_cycle グローバル変数に格納され、新しくスタートしたnginxワーカーによって継承されます。

サイクルは関数 ngx_init_cycle() によって生成されます。関数は古いサイクルを引数として取ります。それは設定ファイルの場所を特定するために使われ、nginxをスムーズに実行し続けるために古いサイクルからできる限り多くのリソースを継承します。nginxが開始した時に、"init cycle"と呼ばれる偽物のサイクルが生成され、その後設定から作られた通常のサイクルによって置き換えられます。

サイクルの幾つかのメンバー:

バッファ

入力/出力オペレーションのために、nginxはバッファ型 ngx_buf_tを提供します。通常、それは宛先に書き込まれるためのデータを保持するためか、ソースから読み込むために使われます。バッファはメモリ内およびファイル内でデータを参照することができます。技術的には、バッファが同時に二つを参照することができます。バッファのためのメモリは個々に割り当てられ、バッファ構造 ngx_buf_t には関係しません。

構造 ngx_buf_t は以下のフィールドを持ちます:

入力および出力のために、バッファはチェーンでリンクされます。チェーンはチェーンリンクngx_chain_tの順列で、以下のように定義されます: 

typedef struct ngx_chain_s  ngx_chain_t;

struct ngx_chain_s {
    ngx_buf_t    *buf;
    ngx_chain_t  *next;
};

各チェーンリンクはバッファへの参照と次のチェーンリンクへの参照を保持します。

バッファとチェーンの使用例: 

ngx_chain_t *
ngx_get_my_chain(ngx_pool_t *pool)
{
    ngx_buf_t    *b;
    ngx_chain_t  *out, *cl, **ll;

    /* first buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_calloc_buf(pool);
    if (b == NULL) { /* error */ }

    b->start = (u_char *) "foo";
    b->pos = b->start;
    b->end = b->start + 3;
    b->last = b->end;
    b->memory = 1; /* read-only memory */

    cl->buf = b;
    out = cl;
    ll = &cl->next;

    /* second buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_create_temp_buf(pool, 3);
    if (b == NULL) { /* error */ }

    b->last = ngx_cpymem(b->last, "foo", 3);

    cl->buf = b;
    cl->next = NULL;
    *ll = cl;

    return out;
}

ネットワーク

接続

接続型 ngx_connection_t はソケットディスクリプタのラッパーです。構造のフィールドの幾つかは次のようなものです:

nginxの接続は透過的にSSL層をカプセル化します。この場合、接続ssl フィールドはngx_ssl_connection_t 構造へのポインタを保持し、SSL_CTX と SSLを含む接続のための全てのSSLに関係するデータを持ち続けます。ハンドラ recv, send, recv_chain, send_chain はSSL関数へも設定されます。

nginxのワーカーあたりの接続の数はworker_connectionsの値によって制限されます。全ての接続の構造は、ワーカーが開始する時にあらかじめ作成され、サイクルオブジェクトのconnectionsフィールドの中に格納されます。接続の構造に手を伸ばすには、ngx_get_connection(s, log)関数が使われます。関数は接続構造の中でラップされる必要がある複数の ソケットディスクリプタを受け取ります。

ワーカーあたりの接続の数が制限されるため、nginxは現在使われている接続を横取りする方法を提供します。接続の再利用を有効あるいは無効にするために、関数ngx_reusable_connection(c, reusable) が呼ばれます。ngx_reusable_connection(c, 1)の呼び出しは接続構造のreuse フラグを設定し、その接続をサイクルのreusable_connections_queue に挿入します。ngx_get_connection()はサイクルのfree_connections リストの中に利用可能な接続が無いと分かるといつでも特定の数の再利用可能な接続lを解放するためにngx_drain_connections()を呼びます。For each such connection, the close flag is set and its read handler is called which is supposed to free the connection by calling ngx_close_connection(c) and make it available for reuse. 接続が再利用可能な時に状態を抜けるためにngx_reusable_connection(c, 0)が呼ばれます。nginxでの再利用可能な接続の例は、クライアントから何らかのデータを受け取るまで再利用可能だとマークされているHTTPクライアントの接続です。

イベント

イベント

nginxでのイベントオブジェクトngx_event_t は特定のイベントが起きていることを伝える方法を提供します。

ngx_event_tのフィールドの幾つかは次のようなものです:

I/O イベント

ngx_get_connection() 呼び出しによって受け取られた各接続は、それに付随する二つのイベントを持ちます: c->read と c->write。これらのイベントは読み込みあるいは書き込みの準備ができたソケットについての通知を受け取るために使われます。全てのそのようなイベントはEdge-Triggeredモードで操作されます。ソケットの状態の変更時にそれらは通知を引き起こすことを意味します。例えば、ソケット上の部分的な読み込みの実施は、ソケットにもっと多くのデータが到着するまでnginxに繰り返しの読み込み通知を配送しないでしょう。背後で動くI/O通知機構が本質的に Level-Triggered (poll, select など)であった場合でも、nginxは通知を Edge-Triggered に変えるでしょう。To make nginx event notifications consistent across all notifications systems on different platforms, it's required, that the functions ngx_handle_read_event(rev, flags) and ngx_handle_write_event(wev, lowat) are called after handling an I/O socket notification or calling any I/O functions on that socket. 通常、これらの関数は各読み込みあるいは書き込みイベントハンドラの最後に一度だけ呼ばれます。

タイマー イベント

イベントはタイムアウトの期限切れを通知するために設定することができます。関数 ngx_add_timer(ev, timer) はイベントのタイムアウトを設定し、ngx_del_timer(ev) は以前に設定されたタイムアウトを削除します。現在のところ全ての既存のイベントに設定されたタイムアウトはグローバルタイムアウト 赤黒木 ngx_event_timer_rbtree に保持されます。木でのキーは型ngx_msec_tを持ち、イベントが期限切れになる1970年1月1日 (modulus ngx_msec_t の最大値)からのミリ秒の時間です。木構造は高速な挿入と削除操作を提供し、もっとも近いタイムアウトへのアクセスを提供します。The latter is used by nginx to find out for how long to wait for I/O events and for expiring timeout events afterwards.

ポストされたイベント

イベントがポストされるかも知れません。ハンドルが現在のイベントループの繰り返しの中でどこかの時点の後で呼ばれるかも知れないという意味です。イベントのポストはコードを単純化しスタックオーバーフローを避けるための良い練習です。ポストされたイベントはポストキューの中に保持されます。マクロ ngx_post_event(ev, q) はイベント ev をポストキューqにポストします。マクロ ngx_delete_posted_event(ev) はイベント ev を現在ポストされたどのようなキューからでも削除します。通常、イベントは ngx_posted_events キューにポストされます。このキューはイベントループの中で、全てのI/Oおよびタイマーイベントがすでに処理された後で処理されます。関数 ngx_event_process_posted() はイベントキューを処理するために呼ばれます。この関数はキューが空になるまでイベントハンドラを呼びます。このことは、ポストされたイベントハンドラは現在のイベントループの繰り返しの中で処理されるされるようにもっと多くのイベントをポストすることができることを意味します。

例: 

void
ngx_my_connection_read(ngx_connection_t *c)
{
    ngx_event_t  *rev;

    rev = c->read;

    ngx_add_timer(rev, 1000);

    rev->handler = ngx_my_read_handler;

    ngx_my_read(rev);
}


void
ngx_my_read_handler(ngx_event_t *rev)
{
    ssize_t            n;
    ngx_connection_t  *c;
    u_char             buf[256];

    if (rev->timedout) { /* timeout expired */ }

    c = rev->data;

    while (rev->ready) {
        n = c->recv(c, buf, sizeof(buf));

        if (n == NGX_AGAIN) {
            break;
        }

        if (n == NGX_ERROR) { /* error */ }

        /* process buf */
    }

    if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
}

イベントループ

I/Oを行う全てのnginxプロセスはイベントループを持ちます。I/Oを持たないプロセスの唯一の型は、シグナルがやってくるのを待つsigsuspend()呼び出しの中でほとんどの時間を過ごすnginxのマスタープロセスです。イベントループはngx_process_events_and_timers() 関数の中で実装されています。この関数はプロセスが終了するまで繰り返し呼ばれます。以下のステージを持ちます:

全てのnginxプロセスもシグナルを処理します。シグナルハンドラは、ngx_process_events_and_timers()呼び出しの後でチェックされるグローバル変数にのみ設定します。

プロセス

nginxには処理の幾つかのタイプがあります:現在のプロセスのタイプはngx_process グローバル変数の中に保持されます:

全てのnginxプロセスは以下のシグナルを処理します:

全てのnginxワーカープロセスはPOSIXのシグナルを受け取り適切に処理することができますが、マスタープロセスは通常どのようなシグナルも標準のkill() syscollを持つワーカーやヘルパーに渡しません。代わりに、nginxは全てのnginxプロセス間でメッセージを送信することができる内部プロセスチャネルを使います。しかし、現在のところ、メッセージはマスターからその子プロセスにのみ送信されます。これらのメッセージは同じシグナルを伝搬することができます。チャネルは異なるプロセスに終端を持つソケットのペアです。

実行中のnginxバイナリの場合、-s パラメータの次に幾つかの値を指定することができます。これらの値は、stop, quit, reopen, reloadです。それらはシグナルNGX_TERMINATE_SIGNAL, NGX_SHUTDOWN_SIGNAL, NGX_REOPEN_SIGNAL および NGX_RECONFIGURE_SIGNAL に変換され、nginx pidファイルからpidを読み込んでnginxマスタープロセスに送信されます。

モジュール

新しいモジュールの追加

スタンドアローンのnginxモジュールは少なくとも以下の2つのファイルを含む別個のディレクトリ内にあります: config とモジュールのソースと一緒のファイル最初のファイルはnginxがモジュールを統合するために必要な全ての情報を含みます。例えば: 

ngx_module_type=CORE
ngx_module_name=ngx_foo_module
ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c"

. auto/module

ngx_addon_name=$ngx_module_name

ファイルはPOSIXのシェルスクリプトで以下の変数を設定(あるいはアクセス)することができます:

静的なコンパイルについては--add-module=/path/to/module を、動的なコンパイルについては--add-dynamic-module=/path/to/moduleを使って、設定スクリプトをによってnginxにモジュールを追加することができます。

コアモジュール

モジュールはnginxのブロックを構築し、その機能のほとんどはモジュールとして実装されます。モジュールのソースファイルは以下のように定義されるグローバル変数ngx_module_t 型を含まなければなりません: 

struct ngx_module_s {

    /* private part is omitted */

    void                 *ctx;
    ngx_command_t        *commands;
    ngx_uint_t            type;

    ngx_int_t           (*init_master)(ngx_log_t *log);

    ngx_int_t           (*init_module)(ngx_cycle_t *cycle);

    ngx_int_t           (*init_process)(ngx_cycle_t *cycle);
    ngx_int_t           (*init_thread)(ngx_cycle_t *cycle);
    void                (*exit_thread)(ngx_cycle_t *cycle);
    void                (*exit_process)(ngx_cycle_t *cycle);

    void                (*exit_master)(ngx_cycle_t *cycle);

    /* stubs for future extensions are omitted */
};

省略されたprivate部分はモジュールのバージョン、シグネチャーを含み、事前定義されたマクロNGX_MODULE_V1を使って埋められます。

各モジュールはprivateデータをctx フィールドに保持し、特定の設定ディレクティブを理解し、commands 配列の中で指定され、nginxのライフサイクルの特定のステージで起動されるかも知れません。モジュールのライフサイクルは以下のイベントから成ります:

設定の再読み込みが要求された場合には、init_module ハンドラがマスタープロセス内で複数回呼ばれるかも知れません。

init_master, init_thread および exit_thread ハンドラは今のところ実装されていません; nginxでのスレッドは独自のAPIによって補助的なI/O機能としてのみ使われており、init_master ハンドラは必要無いように思われます。

モジュールのtype 型はctx フィールド内に何が保持されるかを正確に定義します。モジュールの型には幾つかあります:

NGX_CORE_MODULE は最も基本的で、従って最も一般的で最も低レベルのモジュールの型です。他のモジュール型はその上に実装され、イベントあるいはhttpリクエストの処理のような対応する問題ドメインを扱うための便利な方法を提供します。

コアモジュールの例は ngx_core_module, ngx_errlog_module, ngx_regex_module, ngx_thread_pool_module, ngx_openssl_module モジュール、そしてもちろん http, stream, mail および イベントモジュール自身です。コアモジュールのコンテキストは以下のように定義されます: 

typedef struct {
    ngx_str_t             name;
    void               *(*create_conf)(ngx_cycle_t *cycle);
    char               *(*init_conf)(ngx_cycle_t *cycle, void *conf);
} ngx_core_module_t;

ここで、name は便利なようにモジュール名を持つ文字列で、create_conf と init_conf はそれぞれモジュールの設定を生成および初期化する関数へのポインタです。コアモジュールについては、nginxは新しい設定をパースする前にcreate_conf を呼び、全ての設定のパースが成功した後で init_conf を呼ぶでしょう。代表的な create_conf 関数は設定のためのメモリを割り当て、デフォルトの値を設定します。init_conf は良く知られた設定を扱い、従って正常性チェックと徹底的な初期化をおこなうかも知れません。

例えば、極度に単純化されたngx_foo_moduleは以下のように見えるかも知れません: 

/*
 * Copyright (C) Author.
 */


#include <ngx_config.h>
#include <ngx_core.h>


typedef struct {
    ngx_flag_t  enable;
} ngx_foo_conf_t;


static void *ngx_foo_create_conf(ngx_cycle_t *cycle);
static char *ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf);

static char *ngx_foo_enable(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t  ngx_foo_enable_post = { ngx_foo_enable };


static ngx_command_t  ngx_foo_commands[] = {

    { ngx_string("foo_enabled"),
      NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_FLAG,
      ngx_conf_set_flag_slot,
      0,
      offsetof(ngx_foo_conf_t, enable),
      &ngx_foo_enable_post },

      ngx_null_command
};


static ngx_core_module_t  ngx_foo_module_ctx = {
    ngx_string("foo"),
    ngx_foo_create_conf,
    ngx_foo_init_conf
};


ngx_module_t  ngx_foo_module = {
    NGX_MODULE_V1,
    &ngx_foo_module_ctx,                   /* module context */
    ngx_foo_commands,                      /* module directives */
    NGX_CORE_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};


static void *
ngx_foo_create_conf(ngx_cycle_t *cycle)
{
    ngx_foo_conf_t  *fcf;

    fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t));
    if (fcf == NULL) {
        return NULL;
    }

    fcf->enable = NGX_CONF_UNSET;

    return fcf;
}


static char *
ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf)
{
    ngx_foo_conf_t *fcf = conf;

    ngx_conf_init_value(fcf->enable, 0);

    return NGX_CONF_OK;
}


static char *
ngx_foo_enable(ngx_conf_t *cf, void *post, void *data)
{
    ngx_flag_t  *fp = data;

    if (*fp == 0) {
        return NGX_CONF_OK;
    }

    ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled");

    return NGX_CONF_OK;
}

設定ディレクティブ

ngx_command_t は1つの設定ディレクティブを記述します。設定をサポートする各モジュールは、引数をどうやって処理するか、どのハンドラを呼ぶかを記述する、そのような仕様の配列を提供します: 

struct ngx_command_s {
    ngx_str_t             name;
    ngx_uint_t            type;
    char               *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
    ngx_uint_t            conf;
    ngx_uint_t            offset;
    void                 *post;
};

配列は特別な値 “ngx_null_command” を使って終わらなければなりません。The name is the literal name of a directive, as it appears in configuration file, for example “worker_processes” or “listen”. type は対応するフラグを使った、引数の数、コマンド型、および他のプロパティを制御するビット列です。引数のフラグ:

ディレクティブ型:

ディレクティブのコンテキストは設定のどこに現れるか、そして対応する値を格納するためにモジュールコンテキストにアクセスする方法を定義します。

設定パーサは間違ったディレクティブの場合にエラーを投げるためにこのフラグを使用し、適切な設定ポインタによって提供されるディレクティブハンドラを呼び出します。そしやって、異なるlocation内の同じディレクティブが個々の場所でそれらの値を格納できるようにします。

set フィールドはディレクティブを処理するハンドラを定義し、パースされた値を対応する設定に格納します。Nginxは共通の変換を行う便利な関数のセットを提供します:

conf フィールドはどのコンテキストがディレクティブの値を格納するために使われるかを定義します。コンテキストが使われない場合はゼロです。1つのコアモジュールだけがコンテキスト無しの設定を使用し、NGX_DIRECT_CONF フラグを設定します。実際には、httpあるいはstreamのようなモジュールはpre-serverあるいはpre-location、あるいはもっと正確に“if” ディレクティブあるいは何らかの制限の中に適用することができるようなもっと洗練された設定を必要とします。このモジュール内では、設定構造はもっと複雑です。それらが設定をどう管理するかについて理解するために対応するモジュールの説明を参照してください。

offset はこの特定のディレクティブの値を保持するモジュール設定構造内のフィールドのオフセットを定義します。代表的な使い方はoffsetof() マクロを使うことです。

post は二つの部分からなるフィールドです: メインのハンドラが終了した後で呼ばれるか、あるいは追加のデータをメインのハンドラに渡すために使われるかも知れません。最初の場合には、ngx_conf_post_t 構造はハンドラへのポインタを使って初期化される必要があります。例えば: 

static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t  ngx_foo_post = { ngx_do_foo };

post の引数はngx_conf_post_t オブジェクト自身で、data は値へのポインタで、適切な型を持つメインのハンドラによって引数から変換されます。

HTTP

接続

各クライアントのHTTP接続は以下のステージを通過します:

リクエスト

各クライアントのHTTPリクエストに関して、ngx_http_request_t オブジェクトが生成されます。このオブジェクトの幾つかのフィールド:

設定

各HTTPモジュールは3つの種類の設定を持つかも知れません:

設定構造は関数の呼び出しによってnginx設定ステージで生成されます。これらの構造を割り当て、初期化し、そして合併します。以下の例は1つのモジュールの location 設定を生成する方法を示します。設定は1つのunsigned integer型のfoo を持ちます。 

typedef struct {
    ngx_uint_t  foo;
} ngx_http_foo_loc_conf_t;


static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    NULL,                                  /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    ngx_http_foo_create_loc_conf,          /* create location configuration */
    ngx_http_foo_merge_loc_conf            /* merge location configuration */
};


static void *
ngx_http_foo_create_loc_conf(ngx_conf_t *cf)
{
    ngx_http_foo_loc_conf_t  *conf;

    conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t));
    if (conf == NULL) {
        return NULL;
    }

    conf->foo = NGX_CONF_UNSET_UINT;

    return conf;
}


static char *
ngx_http_foo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
    ngx_http_foo_loc_conf_t *prev = parent;
    ngx_http_foo_loc_conf_t *conf = child;

    ngx_conf_merge_uint_value(conf->foo, prev->foo, 1);
}

例にあるように、ngx_http_foo_create_loc_conf() 関数は新しい設定構造を生成し、ngx_http_foo_merge_loc_conf() は設定を高レベルからの他の設定とマージします。実際、serverとlocation設定はserverとlocationレベルだけに存在するだけでなく、その上の全ての設定のためにも生成されます。特に、server設定はmainレベルに生成され、location設定はmain, server および location レベルのために生成されます。これらの設定によりnginx設定ファイルの任意のレベルでserverおよびlocation固有の設定を指定することができます。結果的に設定がマージされます。マージの間で消える設定と無視される設定を示すために、nginxはNGX_CONF_UNSETおよびNGX_CONF_UNSET_UINTのような多くのマクロを提供します。ngx_conf_merge_value() およびngx_conf_merge_uint_value()のような標準のnginxマージ マクロ は、明示的な値で設定がされない場合に設定をマージしデフォルト値を設定する簡単な方法を提供します。異なる型のための完全なマクロのリストについては、src/core/ngx_conf_file.hを見てください。

設定時の任意のHTTPモジュールの設定にアクセスするには、以下のマクロが利用可能です。それらは最初の引数としてngx_conf_t の参照を受け取ります。

以下の例は標準nginxコアモジュール ngx_http_core_module のlocation設定へのポインタを取得し、構造の handler フィールド内に保持されたlocationコンテントハンドラを変更します。 

static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);


static ngx_command_t  ngx_http_foo_commands[] = {

    { ngx_string("foo"),
      NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
      ngx_http_foo,
      0,
      0,
      NULL },

      ngx_null_command
};


static char *
ngx_http_foo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_core_loc_conf_t  *clcf;

    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
    clcf->handler = ngx_http_bar_handler;

    return NGX_CONF_OK;
}

実行時には、以下のマクロがHTTPモジュールの設定を取得するために利用可能です。

これらのマクロはHTTPリクエスト ngx_http_request_t へのリファレンスを受け取ります。リクエストのメインの設定は変更されません。server 設定は、リクエストのためのバーチャルサーバを選択した後で、デフォルトのものから変わるかもしれません。リクエストのlocation設定は、rewriteあるいは内部リダイレクトの結果として、複数回変更されるかも知れません。以下の例は実行時にHTTP設定へアクセスする方法を示します。 

static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_http_foo_loc_conf_t  *flcf;

    flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module);

    ...
}

フェーズ

各HTTPリクエストはHTTPフェーズのリストを通過します。各フェーズは特定の処理が得意です。ほとんどのフェーズはハンドラを差し込むことができます。フェーズハンドラは、いったんリクエストがフェーズに到達すると連続して呼ばれます。多くの標準のnginxモジュールが特定のリクエストの処理ステージで呼ばれる方法としてフェーズハンドラを差し込みます。以下はnginx HTTPフェーズのリストです。

以下はアクセス前のフェーズハンドラの例です。 

static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    ngx_http_foo_init,                     /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};


static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_str_t  *ua;

    ua = r->headers_in->user_agent;

    if (ua == NULL) {
        return NGX_DECLINED;
    }

    /* reject requests with "User-Agent: foo" */
    if (ua->value.len == 3 && ngx_strncmp(ua->value.data, "foo", 3) == 0) {
        return NGX_HTTP_FORBIDDEN;
    }

    return NGX_DECLINED;
}


static ngx_int_t
ngx_http_foo_init(ngx_conf_t *cf)
{
    ngx_http_handler_pt        *h;
    ngx_http_core_main_conf_t  *cmcf;

    cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);

    h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    *h = ngx_http_foo_handler;

    return NGX_OK;
}

フェーズハンドラは特定のコードを返すことを期待されます:

幾つかのフェーズは戻りコードを少し異なった方法で扱います。コンテントフェーズでは、NGX_DECLINED以外のどのようなコードも終了コードと見なされます。locationコンテントハンドラについては、それらからのどのような返り値も終了コードと見なされます。satisfy any モードのアクセスフェーズでは、NGX_OK, NGX_DECLINED, NGX_AGAIN, NGX_DONE 以外の戻りコードは拒否と見なされます。将来のアクセスハンドラのいずれもが新しいコードでアクセスあるいは拒否しない場合は、拒否コードが終了コードになるでしょう。

変数

既存の変数へのアクセス

変数はインデックス(これは最も一般的な方法です)あるいは名前(変数の生成については以下の章を見てください)を使って参照することができます。インデックスは変数が設定に追加される時に設定ステージで生成されます。変数のインデックスはngx_http_get_variable_index()を使って取得することができます: 

ngx_str_t  name;  /* ngx_string("foo") */
ngx_int_t  index;

index = ngx_http_get_variable_index(cf, &name);

ここで、cf はnginxの設定へのポインタで、name は変数名を持つ文字列へのポインタです。関数はエラー時にNGX_ERROR を返すか、そうでなければ有効なインデックスを返します。これは一般的に後で使うためにモジュール内のどこかに格納されます。

全てのHTTP変数はHTTPリクエストのコンテキスト内で評価され、結果はHTTPリクエストに固有でその中にキャッシュされます。変数を評価する全ての関数はngx_http_variable_value_t型を返し、変数の値を表します: 

typedef ngx_variable_value_t  ngx_http_variable_value_t;

typedef struct {
    unsigned    len:28;

    unsigned    valid:1;
    unsigned    no_cacheable:1;
    unsigned    not_found:1;
    unsigned    escape:1;

    u_char     *data;
} ngx_variable_value_t;

ここで:

ngx_http_get_flushed_variable() と ngx_http_get_indexed_variable() 関数は変数の値を取得するために使われます。それらは同じインタフェースを持ちます - HTTP リクエスト r を変数を評価するためのコンテキストとして受け取り、それを識別するためのindexを受け取ります。一般的な使い方の例: 

ngx_http_variable_value_t  *v;

v = ngx_http_get_flushed_variable(r, index);

if (v == NULL || v->not_found) {
    /* we failed to get value or there is no such variable, handle it */
    return NGX_ERROR;
}

/* some meaningful value is found */

関数間の違いはngx_http_get_indexed_variable() はキャッシュされた値を返し、ngx_http_get_flushed_variable() はキャッシュできない変数のためにキャッシュをフラッシュすることです。

例えばSSIあるいはPerlモジュールのように、設定時には名前が知られておらず従ってインデックスを使ってアクセスすることができない変数を扱う必要がある場合があります。ngx_http_get_variable(r, name, key) 関数はそのような場合に使われるかも知れません。指定されたname とそのハッシュkeyを使ってvariable を検索します

変数の作成

変数を作成するためにngx_http_add_variable() 関数が使われます。それは、挙動を制御する設定(ここで変数が登録されます)、変数名およびフラグを取ります:

関数は、エラー時にはNULL、そうでなければngx_http_variable_tへのポインタを返します: 

struct ngx_http_variable_s {
    ngx_str_t                     name;
    ngx_http_set_variable_pt      set_handler;
    ngx_http_get_variable_pt      get_handler;
    uintptr_t                     data;
    ngx_uint_t                    flags;
    ngx_uint_t                    index;
};

get および set ハンドラは変数値を取得あるいは設定するために呼ばれ、data は変数ハンドラに渡され、index 変数を参照するために使われる割り当てられた可変のインデックスを持つでしょう。

通常、そのような構造おnullで終わる静的な配列はモジュールによって生成され、変数を設定に追加するために事前設定のステージで処理されます: 

static ngx_http_variable_t  ngx_http_foo_vars[] = {

    { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, NULL, 0, 0 },

    { ngx_null_string, NULL, NULL, 0, 0, 0 }
};

static ngx_int_t
ngx_http_foo_add_variables(ngx_conf_t *cf)
{
    ngx_http_variable_t  *var, *v;

    for (v = ngx_http_foo_vars; v->name.len; v++) {
        var = ngx_http_add_variable(cf, &v->name, v->flags);
        if (var == NULL) {
            return NGX_ERROR;
        }

        var->get_handler = v->get_handler;
        var->data = v->data;
    }

    return NGX_OK;
}

この関数はHTTPモジュールのコンテキストのpreconfiguration フィールドを初期化するために使われ、HTTP設定をパースする前に呼ばれます。つまり、それはこれらの変数を参照することができます。

get ハンドラは特定のリクエストのコンテキストの中で変数を評価する責任があります。例えば: 

static ngx_int_t
ngx_http_variable_connection(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data)
{
    u_char  *p;

    p = ngx_pnalloc(r->pool, NGX_ATOMIC_T_LEN);
    if (p == NULL) {
        return NGX_ERROR;
    }

    v->len = ngx_sprintf(p, "%uA", r->connection->number) - p;
    v->valid = 1;
    v->no_cacheable = 0;
    v->not_found = 0;
    v->data = p;

    return NGX_OK;
}

内部エラー(例えば、メモリ割り当ての失敗)の場合はNGX_ERROR を返し、そうでなければNGX_OK を返します。変数の評価の状態はngx_http_variable_value_t (上の説明を見てください)のフラグの精査によって理解されるかも知れません。

set ハンドラによって変数によるプロパティの参照を設定することができます。例えば、$limit_rate 変数の設定ハンドラはリクエストの limit_rate フィールドを修正します: 

...
{ ngx_string("limit_rate"), ngx_http_variable_request_set_size,
  ngx_http_variable_request_get_size,
  offsetof(ngx_http_request_t, limit_rate),
  NGX_HTTP_VAR_CHANGEABLE|NGX_HTTP_VAR_NOCACHEABLE, 0 },
...

static void
ngx_http_variable_request_set_size(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data)
{
    ssize_t    s, *sp;
    ngx_str_t  val;

    val.len = v->len;
    val.data = v->data;

    s = ngx_parse_size(&val);

    if (s == NGX_ERROR) {
        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
                      "invalid size \"%V\"", &val);
        return;
    }

    sp = (ssize_t *) ((char *) r + data);

    *sp = s;

    return;
}

comoplex値

複雑な値という名前にも関わらず、それはテキスト、変数およびそれらの組み合わせを含む表現の評価を簡単にする方法を提供します。

ngx_http_compile_complex_value 内のcomplex値の概要は設定ステージにおいて、評価された表現の結果を取得するために実行時に使われるngx_http_complex_value_t へコンパイルされます。 

ngx_str_t                         *value;
ngx_http_complex_value_t           cv;
ngx_http_compile_complex_value_t   ccv;

value = cf->args->elts; /* directive arguments */

ngx_memzero(&ccv, sizeof(ngx_http_compile_complex_value_t));

ccv.cf = cf;
ccv.value = &value[1];
ccv.complex_value = &cv;
ccv.zero = 1;
ccv.conf_prefix = 1;

if (ngx_http_compile_complex_value(&ccv) != NGX_OK) {
    return NGX_CONF_ERROR;
}

ここで、ccv はcomplex値 cvを初期化することを必要とする全てのパラメータを保持します:

ゼロで終了する文字列を必要とするライブラリに結果が渡される場合はzero フラグが利用可能です。ファイル名を扱う場合にはプリフィックスが便利です。

Upon successful compilation, cv.lengths may be inspected to get information about the presence of variables in the expression. The NULL value means that the expression contained static text only, and there is no need in storing it as a complex value, so a simple string can be used.

ngx_http_set_complex_value_slot()はディレクティブ定義の中でcomplex値を完全に正しく初期化するために使われる便利な関数です。

実行時には、complex値はngx_http_complex_value() 関数を使って計算されるかも知れません: 

ngx_str_t  res;

if (ngx_http_complex_value(r, &cv, &res) != NGX_OK) {
    return NGX_ERROR;
}

Given the request r and previously compiled value cv the function will evaluate expression and put result into res.

応答

nginxでのHTTP応答は、任意の応答ボディが続く応答ヘッダを送信することで生成されます。ヘッダとボディの両方はフィルタチェインを通過し、結果的にクライアントのソケットに書き込まれます。nginxモジュールはハンドラをヘッダあるいはボディフィルタに差し込み、以前のハンドラからの出力を処理することができます。

応答ヘッダ

出力ヘッダは関数ngx_http_send_header(r)によって送信されます。この関数の呼び出しの前に、r->headers_out はHTTP応答ヘッダを生成するために必要な全てのデータを含める必要があります。常にr->headers_outのstatusフィールドを設定することが必要とされます。もし応答ステータスがヘッダに続く応答ボディを暗示する場合、content_length_n も同様に設定することができます。このフィールドのデフォルトの値は-1です。このことはボディサイズが未知であることを意味します。この場合、chunked transfer encoding が使われます。任意のヘッダを出力するには、headers リストが追加されなければなりません。 

static ngx_int_t
ngx_http_foo_content_handler(ngx_http_request_t *r)
{
    ngx_int_t         rc;
    ngx_table_elt_t  *h;

    /* send header */

    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = 3;

    /* X-Foo: foo */

    h = ngx_list_push(&r->headers_out.headers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    h->hash = 1;
    ngx_str_set(&h->key, "X-Foo");
    ngx_str_set(&h->value, "foo");

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }

    /* send body */

    ...
}

ヘッダフィルタ

ngx_http_send_header(r) 関数はトップヘッダフィルタハンドラngx_http_top_header_filterを呼び出すことでヘッダフィルタチェーンを起動します。最後のハンドラngx_http_header_filter(r) が呼ばれるまで、各ヘッダハンドラがチェーン内の次のハンドラを呼ぶと仮定します。最後のヘッダハンドラはr->headers_out に基づいたHTTP応答を構築し、それを出力のためにngx_http_writer_filter に渡します。

ヘッダフィルタチェーンにハンドラを追加するには、そのアドレスを設定時にngx_http_top_header_filter グローバル変数に格納する必要があります。前のハンドラのアドレスは通常モジュールの静的変数に格納され、終了する前に新しく追加されたハンドラによって呼ばれます。

以下は、HTTPヘッダ "X-Foo: foo" をステータス200で各出力に追加するヘッダフィルタモジュールの例です。 

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>


static ngx_int_t ngx_http_foo_header_filter(ngx_http_request_t *r);
static ngx_int_t ngx_http_foo_header_filter_init(ngx_conf_t *cf);


static ngx_http_module_t  ngx_http_foo_header_filter_module_ctx = {
    NULL,                                   /* preconfiguration */
    ngx_http_foo_header_filter_init,        /* postconfiguration */

    NULL,                                   /* create main configuration */
    NULL,                                   /* init main configuration */

    NULL,                                   /* create server configuration */
    NULL,                                   /* merge server configuration */

    NULL,                                   /* create location configuration */
    NULL                                    /* merge location configuration */
};


ngx_module_t  ngx_http_foo_header_filter_module = {
    NGX_MODULE_V1,
    &ngx_http_foo_header_filter_module_ctx, /* module context */
    NULL,                                   /* module directives */
    NGX_HTTP_MODULE,                        /* module type */
    NULL,                                   /* init master */
    NULL,                                   /* init module */
    NULL,                                   /* init process */
    NULL,                                   /* init thread */
    NULL,                                   /* exit thread */
    NULL,                                   /* exit process */
    NULL,                                   /* exit master */
    NGX_MODULE_V1_PADDING
};


static ngx_http_output_header_filter_pt  ngx_http_next_header_filter;


static ngx_int_t
ngx_http_foo_header_filter(ngx_http_request_t *r)
{
    ngx_table_elt_t  *h;

    /* 
     * The filter handler adds "X-Foo: foo" header
     * to every HTTP 200 response
     */

    if (r->headers_out.status != NGX_HTTP_OK) {
        return ngx_http_next_header_filter(r);
    }

    h = ngx_list_push(&r->headers_out.headers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    h->hash = 1;
    ngx_str_set(&h->key, "X-Foo");
    ngx_str_set(&h->value, "foo");

    return ngx_http_next_header_filter(r);
}


static ngx_int_t
ngx_http_foo_header_filter_init(ngx_conf_t *cf)
{
    ngx_http_next_header_filter = ngx_http_top_header_filter;
    ngx_http_top_header_filter = ngx_http_foo_header_filter;

    return NGX_OK;
}

応答ボディ

応答ボディは関数 ngx_http_output_filter(r, cl)の呼び出しによって送信されます。関数は複数回呼び出すことができます。各回でバッファチェーンとして渡された応答ボディの部分を送信します。最後のボディバッファはlast_buf フラグ セットを持つ必要があります。

以下の例はボディとして "foo" を持つ完全なHTTP出力を生成します。例がメインのリクエストとしてだけでなくサブリクエストとしても動作するために、出力の最後のバッファにlast_in_chain_flag が設定されます。最後のバッファは出力全体の最後では無いので、last_buf フラグはメインのリクエストのためだけに設定されます。 

static ngx_int_t
ngx_http_bar_content_handler(ngx_http_request_t *r)
{
    ngx_int_t     rc;
    ngx_buf_t    *b;
    ngx_chain_t   out;

    /* send header */

    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = 3;

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }

    /* send body */

    b = ngx_calloc_buf(r->pool);
    if (b == NULL) {
        return NGX_ERROR;
    }

    b->last_buf = (r == r->main) ? 1: 0;
    b->last_in_chain = 1;

    b->memory = 1;

    b->pos = (u_char *) "foo";
    b->last = b->pos + 3;

    out.buf = b;
    out.next = NULL;

    return ngx_http_output_filter(r, &out);
}

ボディ フィルタ

関数 ngx_http_output_filter(r, cl) はトップのボディフィルタハンドラを呼び出すことでボディフィルタを起動します。最後のハンドラngx_http_write_filter(r, cl) が呼ばれるまで、各ボディハンドラがチェーン内の次のハンドラを呼ぶと仮定します。

ボディフィルタハンドラはバッファのチェーンを受け取ります。ハンドラはバッファを処理し、できる限り新しいチェーンを次のハンドラに渡すとされています。It's worth noting that the chain links ngx_chain_t of the incoming chain belong to the caller. それらは再利用されたり変更されたりすべきではありません。ハンドラが完了するとすぐに、呼び出し元はそれを送信したバッファの追跡を続けるために出力チェーンのリンクを使うことができます。更に送信する前に、バッファチェーンの保存あるいは幾つかのバッファの置き換えをするために、ハンドラは自身のチェーンリンクを割り当てる必要があります。

以下はボディのバイト数をカウントする簡単なボディフィルタの例です。結果はアクセスログ内で使うことができる $counter 変数として利用可能です。 

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>


typedef struct {
    off_t  count;
} ngx_http_counter_filter_ctx_t;


static ngx_int_t ngx_http_counter_body_filter(ngx_http_request_t *r,
    ngx_chain_t *in);
static ngx_int_t ngx_http_counter_variable(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data);
static ngx_int_t ngx_http_counter_add_variables(ngx_conf_t *cf);
static ngx_int_t ngx_http_counter_filter_init(ngx_conf_t *cf);


static ngx_http_module_t  ngx_http_counter_filter_module_ctx = {
    ngx_http_counter_add_variables,        /* preconfiguration */
    ngx_http_counter_filter_init,          /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};


ngx_module_t  ngx_http_counter_filter_module = {
    NGX_MODULE_V1,
    &ngx_http_counter_filter_module_ctx,   /* module context */
    NULL,                                  /* module directives */
    NGX_HTTP_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};


static ngx_http_output_body_filter_pt  ngx_http_next_body_filter;

static ngx_str_t  ngx_http_counter_name = ngx_string("counter");


static ngx_int_t
ngx_http_counter_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_chain_t                    *cl;
    ngx_http_counter_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
    if (ctx == NULL) {
        ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_counter_filter_ctx_t));
        if (ctx == NULL) {
            return NGX_ERROR;
        }

        ngx_http_set_ctx(r, ctx, ngx_http_counter_filter_module);
    }

    for (cl = in; cl; cl = cl->next) {
        ctx->count += ngx_buf_size(cl->buf);
    }

    return ngx_http_next_body_filter(r, in);
}


static ngx_int_t
ngx_http_counter_variable(ngx_http_request_t *r, ngx_http_variable_value_t *v,
    uintptr_t data)
{
    u_char                         *p;
    ngx_http_counter_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
    if (ctx == NULL) {
        v->not_found = 1;
        return NGX_OK;
    }

    p = ngx_pnalloc(r->pool, NGX_OFF_T_LEN);
    if (p == NULL) {
        return NGX_ERROR;
    }

    v->data = p;
    v->len = ngx_sprintf(p, "%O", ctx->count) - p;
    v->valid = 1;
    v->no_cacheable = 0;
    v->not_found = 0;

    return NGX_OK;
}


static ngx_int_t
ngx_http_counter_add_variables(ngx_conf_t *cf)
{
    ngx_http_variable_t  *var;

    var = ngx_http_add_variable(cf, &ngx_http_counter_name, 0);
    if (var == NULL) {
        return NGX_ERROR;
    }

    var->get_handler = ngx_http_counter_variable;

    return NGX_OK;
}


static ngx_int_t
ngx_http_counter_filter_init(ngx_conf_t *cf)
{
    ngx_http_next_body_filter = ngx_http_top_body_filter;
    ngx_http_top_body_filter = ngx_http_counter_body_filter;

    return NGX_OK;
}

フィルタモジュールのビルド

ボディあるいはヘッダフィルタを書く時に、フィルタの順番に特に注意が必要です。nginxの標準モジュールによって登録された多くのヘッダとボディフィルタがあります。他のフィルタを考慮して正しい場所にフィルタモジュールを登録することが重要です。通常、フィルタは事前設定ハンドラの中でモジュールによって登録されます。フィルタが呼ばれる順番は、当然それらが登録された時の逆順です。

サードパーティフィルタモジュールのための特別なスロット HTTP_AUX_FILTER_MODULES がnginxによって提供されます。スロット内でフィルタモジュールを登録するために、モジュールの設定の中で ngx_module_type 変数が HTTP_AUX_FILTERの値に設定されるべきです。

以下の例は、たった一つのソースファイル ngx_http_foo_filter_module.cを持つと仮定するフィルタモジュールの設定ファイルを示します。 

ngx_module_type=HTTP_AUX_FILTER
ngx_module_name=ngx_http_foo_filter_module
ngx_module_srcs="$ngx_addon_dir/ngx_http_foo_filter_module.c"

. auto/module

バッファの再利用

バッファのストリームを発行あるいは変更する時、割り当てられたバッファを再利用することがしばしば望ましいです。nginxのコードの中で広範囲に適用される標準的なやり方は、この目的のために二つのバッファのチェーンを保持します: free と busy. free チェーンは全てのフリーなバッファを保持します。これらのバッファは再利用することができます。busy チェーンは幾つかの他のフィルタハンドラによってまだ使われている現在のモジュールによって送信される全てのバッファを保持します。もしサイズが0より大きければ、バッファは使用中だと見なされます。通常、バッファがフィルタによって消費された場合、そのpos (あるいはファイルバッファについては file_pos ) は last (ファイルバッファについてはfile_last )に進みます。いったんバッファが完全に消費されると、再利用することができます。free チェーンを新しくfreeにされたバッファを使って更新するには、busy チェーンの一番上でサイズが0のバッファをfreeに移動するのを繰り返すことで十分です。この操作は一般的で、これを行う特別な関数ngx_chain_update_chains(free, busy, out, tag)があります。関数は出力チェーンoutを busy に追加し、freeなバッファをbusy の一番上から freeに移動します。指定されたtagを持つバッファだけが再利用されます。これはモジュールによって割り当てられたバッファだけがモジュールによって再利用されます。

以下の例は各入力のバッファの前に “foo” 文字列を挿入するボディフィルタの例です。モジュールによって割り当てられた新しいバッファは可能であれば再利用されます。この例を適切に動作させるには、ヘッダフィルタを設定しcontent_length_n を -1 に再設定することも必要なことに注意してください。これはこの章の範囲を超えます。 

typedef struct {
    ngx_chain_t  *free;
    ngx_chain_t  *busy;
}  ngx_http_foo_filter_ctx_t;


ngx_int_t
ngx_http_foo_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_int_t                   rc;
    ngx_buf_t                  *b;
    ngx_chain_t                *cl, *tl, *out, **ll;
    ngx_http_foo_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_foo_filter_module);
    if (ctx == NULL) {
        ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_foo_filter_ctx_t));
        if (ctx == NULL) {
            return NGX_ERROR;
        }

        ngx_http_set_ctx(r, ctx, ngx_http_foo_filter_module);
    }

    /* create a new chain "out" from "in" with all the changes */

    ll = &out;

    for (cl = in; cl; cl = cl->next) {

        /* append "foo" in a reused buffer if possible */

        tl = ngx_chain_get_free_buf(r->pool, &ctx->free);
        if (tl == NULL) {
            return NGX_ERROR;
        }

        b = tl->buf;
        b->tag = (ngx_buf_tag_t) &ngx_http_foo_filter_module;
        b->memory = 1;
        b->pos = (u_char *) "foo";
        b->last = b->pos + 3;

        *ll = tl;
        ll = &tl->next;

        /* append the next incoming buffer */

        tl = ngx_alloc_chain_link(r->pool);
        if (tl == NULL) {
            return NGX_ERROR;
        }

        tl->buf = cl->buf;
        *ll = tl;
        ll = &tl->next;
    }

    *ll = NULL;

    /* send the new chain */

    rc = ngx_http_next_body_filter(r, out);

    /* update "busy" and "free" chains for reuse */

    ngx_chain_update_chains(r->pool, &ctx->free, &ctx->busy, &out,
                            (ngx_buf_tag_t) &ngx_http_foo_filter_module);

    return rc;
}

ロードバランシング

ngx_http_upstream_module はリクエストをリモートサーバに渡す基本的な機能を提供します。この機能はHTTPあるいはFastCGIのような特定のプロトコルを実装するモジュールによって使われます。モジュールは独自のロードバランシングモジュールを作成するためのインタフェースも提供し、デフォルトのラウンドロビンバランシングメソッドを実装します。

別のロードバランシングメソッドを実装するモジュールの例は、least_conn と hash です。これらのモジュールは実際にはupstreamモジュールの拡張として実装されており、serverグループの表現のような多くのコードを共有することに注意してください。keepalive モジュールはupstream機能を拡張し、依存しないモジュールの例です。

The ngx_http_upstream_module may be configured explicitly by placing the corresponding upstream block into the configuration file, or implicitly by using directives that accept a URL evaluated at some point to the list of servers, for example, proxy_pass. 明示的な設定だけが代替のロードバランシングメソッドを使うかも知れません。upstreamモジュールの設定は独自のディレクティブコンテキスト NGX_HTTP_UPS_CONFを持ちます。その構造は以下のように定義されます: 

struct ngx_http_upstream_srv_conf_s {
    ngx_http_upstream_peer_t         peer;
    void                           **srv_conf;

    ngx_array_t                     *servers;  /* ngx_http_upstream_server_t */

    ngx_uint_t                       flags;
    ngx_str_t                        host;
    u_char                          *file_name;
    ngx_uint_t                       line;
    in_port_t                        port;
    ngx_uint_t                       no_port;  /* unsigned no_port:1 */

#if (NGX_HTTP_UPSTREAM_ZONE)
    ngx_shm_zone_t                  *shm_zone;
#endif
};

nginxがリクエストを処理のために他のホストに渡す必要がある場合は、接続先のアドレスを取得するために設定されたロードバランシングメソッドを使います。メソッドは型ngx_peer_connection_t のngx_http_upstream_peer_t.peer オブジェクトから取り出されます: 

struct ngx_peer_connection_s {
    [...]

    struct sockaddr                 *sockaddr;
    socklen_t                        socklen;
    ngx_str_t                       *name;

    ngx_uint_t                       tries;

    ngx_event_get_peer_pt            get;
    ngx_event_free_peer_pt           free;
    ngx_event_notify_peer_pt         notify;
    void                            *data;

#if (NGX_SSL || NGX_COMPAT)
    ngx_event_set_peer_session_pt    set_session;
    ngx_event_save_peer_session_pt   save_session;
#endif

    [..]
};

構造は以下のフィールドを持ちます:

全てのメソッドは少なくとも二つの引数を受け付けます; ngx_http_upstream_srv_conf_t.peer.init()によって生成された peer接続オブジェクト pc と data。ロードバランシングモジュールの“chaining”のため、一般的にはpc.dataとは異なることに注意してください。

TOP
inserted by FC2 system