2014年7月15日火曜日

リクエストの処理の流れ

handlerフック関数の実行の続きで、ap_process_async_request()関数から呼び出し関係を遡ってみる。


(1) ap_process_http_async_connection関数

呼び出し元の関数ではリクエストを読込み(ap_read_request())、ap_process_async_request()処理を実行している。

(httpd-2.4.9/modules/http/http_core.c)

    124 static int ap_process_http_async_connection(conn_rec *c)
    125 {
    126     request_rec *r;
    127     conn_state_t *cs = c->cs;
  :
    132     while (cs->state == CONN_STATE_READ_REQUEST_LINE) {
    133         ap_update_child_status_from_conn(c->sbh, SERVER_BUSY_READ, c);
    134
    135         if ((r = ap_read_request(c))) {
リクエスト行とリクエストヘッダを読み込み、request_rec情報に格納する。
ここで直接呼び出されるフック関数の実行関数には次のものがある
 * ap_run_create_request
 * ap_run_pre_read_request
 * ap_run_post_read_request
 * ap_run_log_transaction(エラー発生の場合)

     :
    141             if (r->status == HTTP_OK) {
    142                 cs->state = CONN_STATE_HANDLER;
    143                 ap_process_async_request(r);
     :
    151                 r = NULL;
    152             }
    153
    154             if (cs->state != CONN_STATE_WRITE_COMPLETION &&
    155                 cs->state != CONN_STATE_SUSPENDED) {
    156                 /* Something went wrong; close the connection */
    157                 cs->state = CONN_STATE_LINGER;
    158             }
    159         }
    160         else {   /* ap_read_request failed - client may have closed */
    161             cs->state = CONN_STATE_LINGER;
    162         }
    163     }
    164
    165     return OK;
    166 }

ここで conn_state_t という構造体が出てくる。
これは、コネクションの状態を管理している。

(httpd-2.4.9/include/httpd.h)

   1187 struct conn_state_t {
   1188     /** Current state of the connection */
   1189     conn_state_e state;
   1190     /** Whether to read instead of write, or write instead of read */
   1191     conn_sense_e sense;
   1192 };

ここにあるconn_state_e(列挙型)変数 stateは次の通り

(httpd-2.4.9/include/httpd.h)

   1167 typedef enum  {
   1168     CONN_STATE_CHECK_REQUEST_LINE_READABLE,
   1169     CONN_STATE_READ_REQUEST_LINE,
   1170     CONN_STATE_HANDLER,
   1171     CONN_STATE_WRITE_COMPLETION,
   1172     CONN_STATE_SUSPENDED,
   1173     CONN_STATE_LINGER,          /* connection may be closed with lingering */
   1174     CONN_STATE_LINGER_NORMAL,   /* MPM has started lingering close with normal timeout */
   1175     CONN_STATE_LINGER_SHORT     /* MPM has started lingering close with short timeout */
   1176 } conn_state_e;

ap_process_http_async_connection()でチェックされている CONN_STATE_READ_REQUEST_LINE は、その名の通り、リクエストの読み込みということだ。
リクエストの読み込み後、CONN_STATE_HANDLERに更新される(142行目)。
そして、ap_process_async_request()が実行される。

その処理を終えると、CONN_STATE_WRITE_COMPLETIONか、CONN_STATE_SUSPENDEDかチェックされ、いずれでもなければ、CONN_STATE_LINGERで更新される(157行目)。

この時点で、cs->stateは、CONN_STATE_WRITE_COMPLETIONか、CONN_STATE_SUSPENDEDか、CONN_STATE_LINGERということになるので、132行目からのwhile (cs->state == CONN_STATE_READ_REQUEST_LINE)ループからは抜ける。

この処理だけに着目する限り、whileループを実査にループする経路はなさそうだ。

(2)process_connectionフック関数

さて、もう一段、呼び出し元を辿ると、次の関数に辿り着く。

(httpd-2.4.9/modules/http/http_core.c)

    225 static int ap_process_http_connection(conn_rec *c)
    226 {
    227     if (async_mpm && !c->clogging_input_filters) {
    228         return ap_process_http_async_connection(c);
    229     }
    230     else {
    231         return ap_process_http_sync_connection(c);
    232     }
    233 }

これはフック関数だ。
以下で登録されている。process_connectionフック関数である。

(httpd-2.4.9/modules/http/http_core.c)

    275     ap_hook_process_connection(ap_process_http_connection, NULL, NULL,
    276                                APR_HOOK_REALLY_LAST);

上記のap_process_http_connection()で使用されているフラグasync_mpmはap_mpm_query()関数で設定されている。

    263     if (ap_mpm_query(AP_MPMQ_IS_ASYNC, &async_mpm) != APR_SUCCESS) {
    264         async_mpm = 0;
    265     }

このMPMの情報を取得する関数自体が内部でmpm_queryフック関数を呼び出している。
MPMによって、登録されているフック関数が異なり、実際にセットされる値も変わるという訳だ。
event MPMの場合は、このmpm_queryフック関数は、event_query()だ。
この関数が、AP_MPMQ_IS_ASYNCというコードを与えられたときに、引数async_mpmにセットする値は、1である。

ちなみに、worker MPMにおける、mpm_queryフック関数はworker_query()だが、AP_MPMQ_IS_ASYNCに対して返す値の指定がない。ここでは、APR_ENOTIMPLがエラーとして返されるので、結果として、264行目によって値が0となる。
prefork MPMも worker MPMと同様だった。

clogging_input_filtersは、2.4.9では使用されていないので、初期値の0のままだ。

従って、ap_process_http_connection()関数は、event MPMでは、ap_process_http_async_connection()が実行され、worker MPM/prefork MPMでは、ap_process_http_sync_connection()が実行される。

clogging_input_filtersをセットすると、worker MPMと同様にリクエスト処理でワーカスレッドを占有する、というのは、要はこの処理の分岐の話だ。


(3)event MPM: process_socket関数


続いて、このap_process_http_connection()を実行するprocess_connectionフック関数の呼び出し箇所を見てみる。
event MPMでは process_socket()関数の処理で呼ばれている。
これは、event MPMのworkerスレッドで実行される。
listenerスレッドが受け付けたリクエストの処理を行うのが、workerスレッドのprocess_socket()関数だ。

もう少し細かく見ると、listenerスレッドは、listenソケットのacceptを監視し、既に接続済みのソケットが読込可能/書込可能となるのを監視している。
またapr_skiplistを利用したタイマー処理のタイムアップも監視しており、そのほかにも4種類のタイムアウト処理を実行する。

読込可能チェックには、以下の状態がある。
  • KeepAlive接続における次リクエストの受信待ち
  • lingeringクローズでの通信相手ソケットからのクローズ(FIN)待ち

書込可能チェックは、以下の状態だ。
  • クライアントに送ろうとしたデータがブロックされてしまった場合(送信できなかった場合)、再び、書込可能なるのを待っている状態
これらのうち、lingeringクローズソケットのクローズ処理以外は、workerスレッドで処理される。
そして、acceptされたソケットの処理、KeepAlive接続の読込処理、書込み可能になったソケットの書込処理がprocess_socket関数で行われる。
タイマー処理は、process_socket関数では処理されない。

新たなソケットの処理とKeepAlive接続の読込処理では、conn_state_tがCONN_STATE_CHECK_REQUEST_LINE_READABLE状態になる。
書込み可能となったソケットの場合は、conn_state_tがCONN_STATE_WRITE_COMPLETION状態だ。

ここで、process_socket関数でap_run_process_connection()を実行するのは、CONN_STATE_CHECK_REQUEST_LINE_READABLE状態の場合の処理となる。

    881 static void process_socket(apr_thread_t *thd, apr_pool_t * p, apr_socket_t * sock,
    882                           event_conn_state_t * cs, int my_child_num,
    883                           int my_thread_num)
    884 {
    :

    893     if (cs == NULL) {           /* This is a new connection */

新しくacceptされたソケットの処理の場合、csはNULLとなっている。
KeepAlive接続の処理の場合はcsは作成済みなので、ここの処理を経由しない。
ここでコネクション情報の初期設定やevent_conn_state_t情報の初期設定
などの初期処理が実行される。
    897         c = ap_run_create_connection(p, ap_server_conf, sock,
    898                                      conn_id, sbh, cs->bucket_alloc);
     :
    920         ap_update_vhost_given_ip(c);
    921
    922         rc = ap_run_pre_connection(c, sock);


    942         cs->pub.state = CONN_STATE_READ_REQUEST_LINE;
    943
    944         cs->pub.sense = CONN_SENSE_DEFAULT;
    945     }
     :
    952     if (c->clogging_input_filters && !c->aborted) {

clogging_input_filtersフラグが立っている場合の処理。
実行されるのはap_run_process_connection()で、フラグが立っていない場合と
同じだが、終了時のconn_state_tに設定される状態が、CONN_STATE_LINGER状態
に限定されている(SUSPENDでなければ)。
     :
    959         apr_atomic_inc32(&clogged_count);
    960         ap_run_process_connection(c);
    961         if (cs->pub.state != CONN_STATE_SUSPENDED) {
    962             cs->pub.state = CONN_STATE_LINGER;
    963         }
    964         apr_atomic_dec32(&clogged_count);
    965     }
     :


    967 read_request:
    968     if (cs->pub.state == CONN_STATE_READ_REQUEST_LINE) {

1件のリクエスト処理はここから始まる。
    969         if (!c->aborted) {
    970             ap_run_process_connection(c);

これこそ、今まで見てきた処理を実行する process_connectionフック関数の
実行だ。
     :
    976         }
    977         else {
    978             cs->pub.state = CONN_STATE_LINGER;
    979         }
    980     }
    981
    982     if (cs->pub.state == CONN_STATE_WRITE_COMPLETION) {

process_connectionフック関数からreturnすると、通常、conn_state_tは
CONN_STATE_WRITE_COMPLETION状態となっている。
ap_process_async_request()関数の最後に実行される 1件のリクエスト処理の
終了処理であるap_process_request_after_handler関数内で、
CONN_STATE_WRITE_COMPLETIONがセットされる。
そして、ここでは bucket brigadeが NULLで出力フィルタに引き渡されている。
内部に保持されているbucket brigadeが処理対象ということだ。
    983         ap_filter_t *output_filter = c->output_filters;
     :

    989         rv = output_filter->frec->filter_func.out_func(output_filter, NULL);

     :
   1065     return;
   1066 }


この処理は、listenerスレッドと相互に関係しながら処理を進めるので、少し分かりにくい気がする。
が、リクエスト処理の流れを追うという意味では、ここが最上流、源流にあたる。
そういうわけで、上流から下流に簡単な図を書いてみた。


フック関数を中心に追ってみた。今日は終わり。

2014年7月7日月曜日

handlerフック関数の実行処理

handlerフック関数の例の続きだ。

(1)ap_invoke_handler関数

フック関数は以下のap_run_handler()処理で実行される。

(httpd-2.4.9/server/config.c)
    385 AP_CORE_DECLARE(int) ap_invoke_handler(request_rec *r)
    386 {
     :
    401     ap_run_insert_filter(r);
ap_run_insert_filterもフック関数の実行処理だ。
基本的には、リクエスト処理に用いる入力フィルタや出力フィルタがセットアッ
プされる。

     :

    439     result = ap_run_handler(r);

ここでhandlerフック関数を実行する

     :
    465     return result == DECLINED ? HTTP_INTERNAL_SERVER_ERROR : result;
    466 }


(2)ap_process_async_request関数

これを行っている、ap_invoke_handler()関数は、内部リダイレクトの処理や、サブリクエストの処理などを含め数か所で呼ばれている。
そのうち、外部から受け取ったリクエストをそのまま処理するのは、次の箇所だった。
受信したリクエストの情報が引数のrequest_rec情報に保存されている。
この関数がリクエスト処理の本体だと言えそうだ。

(httpd-2.4.9/modules/http/http_request.c)

    272 void ap_process_async_request(request_rec *r)
    273 {
     :
    313     access_status = ap_run_quick_handler(r, 0);  /* Not a look-up request */
    314     if (access_status == DECLINED) {

ap_run_quick_hanlder()もフック関数の実行処理だ。
その戻り値がDECLINEDの場合にこのif文内の処理が行われる。
quick_handlerフック関数は、AP_IMPLEMENT_HOOK_RUN_FIRSTタイプなので、
handlerフック関数と同じだ。
フック関数の戻り値がDECLINE以外の場合に処理を終了する。
フック関数は処理を行うと、エラーステータスやOKを返す。このタイプでDECLINEDを
返すのは、次のフック関数に処理を継続させるためだ。
この戻り値がDECLINEDということは、登録されたフック関数はすべて実行されたが、
結局、エラーやOKを返すような処理は行われなかったことになる。
これが何を意味するかだが、例えば、特定の条件でキャッシュがヒットした場合には
ここの処理には入らない(キャッシュが返される)、というようなことだ。キャッ
シュについては、あとで少し細かく見たい。

    315         access_status = ap_process_request_internal(r);

この関数内で、アクセス権限チェックを含む、多くの処理が実行される。
フック関数の実行も、直接呼び出されるだけで以下のものがある。
* ap_run_post_perdir_config * ap_run_translate_name * ap_run_map_to_storage * ap_run_header_parser * ap_run_access_checker * ap_run_access_checker_ex * ap_run_check_user_id * ap_run_auth_checker * ap_run_type_checker * ap_run_fixups
このチェックに合格すると、OKが返される
316 if (access_status == OK) { 317 access_status = ap_invoke_handler(r); ap_invoke_handle()はap_process_request_internal()がOKを返した場合にのみ実行 される。 ここから、ap_run_handler()が実行された。 318 } 319 } : リクエストの処理結果はaccess_statusにセットされている。 結果に応じて(OKか否か)処理が振り分けられている。 345 if (access_status == OK) { 346 ap_finalize_request_protocol(r); 347 } 348 else { 349 r->status = HTTP_OK; 350 ap_die(access_status, r); 351 } 352 353 ap_process_request_after_handler(r); 最後のこの処理は、リクエスト処理1件分の終了処理だ。 EOR(END of Request)バケットを生成し、これを収めたbucket brigadeを出力フィル タにap_pass_brigadeする。 default_handler等リクエスト処理中は、bucket brigadeを引き渡す出力フィルタが request_recのoutput_filters だったが、ここでは、conn_recのoutput_filtersに なっていた。 354 }


これだけでは、ap_run_handler()がどういうタイミングで処理されるのか分からない。
そこで、このあと少し、リクエスト処理の流れを追ってみる。
その際には、再度、ap_process_async_request()やap_invoke_handler()の処理内容も確認したい。
行ったり来たりだが、リクエスト処理の流れを追いながらフック関数の呼出し位置を確認し、その後また、フック関数を幾つか確認するという作業に戻る予定とする。

2014年7月1日火曜日

ハンドラ(handler)フック関数の例: send-as-is ハンドラ

send-as-isハンドラ

default_handerの続き
もう一つ、asisモジュール(mod_asis.so)の提供するハンドラを見てみる。
まず簡単に、使い方を確認する。
default_handlerは何もしない場合に使われるが、send-as-isは適用条件を指定してやる必要がある。

(1)使い方

send-as-isハンドラを利用するには、AddHandlerディレクティブを使って、拡張子.asisのファイルと結びつけるなどして、ハンドラとリソースを結び付けておく必要がある。

AddHandler send-as-is asis

send-as-isハンドラの処理するファイルは、特定の書式に従って書かれている。
と言っても、内容はほぼ、HTTPレスポンスをそのまま書いたものだ。
ただ1行目のステータス行だけはHTTPヘッダ風(Status:値)で、実際のレスポンスと異なる書式で定義している。
そして、Apacheは、この内容をほぼそのままクライアントへのレスポンスとする。
プロジェクトのドキュメントには以下のような例が書かれている。

Status: 301 Now where did I leave that URL
Location: http://xyz.example.com/foo/bar.html
Content-type: text/html

<html>
<head>
<title>Lame excuses'R'us</title>
</head>
<body>
<h1>Fred's exceptionally wonderful page has moved to
<a href="http://xyz.example.com/foo/bar.html">Joe's</a> site.
</h1>
</body>
</html>
</pre>

このファイルは301応答を生成し、Locationヘッダにここに書かれているURLを渡す。
上記の内容をsample.asisというファイルに保存して、curlコマンドでアクセスしてみる。

$ curl -v http://localhost:8080/sample.asis
* About to connect() to localhost port 8080 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 8080 (#0)
> GET /sample.asis HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.3.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: localhost:8080
> Accept: */*
>
< HTTP/1.1 301 Now where did I leave that URL
ステータス行のReason-Phraseも、ファイルに書かれたものが使われている
< Date: Wed, 25 Jun 2014 08:24:38 GMT
Dateヘッダは自動的に追加
< Server: Apache/2.4.9 (Unix)
Serverヘッダは自動的に追加
< Location: http://xyz.example.com/foo/bar.html < Content-Length: 199
Content-Lengthも自動的に追加
< Content-Type: text/html < <html> <head> <title>Lame excuses'R'us</title> </head> <body> <h1>Fred's exceptionally wonderful page has moved to <a href="http://xyz.example.com/foo/bar.html">Joe's</a> site. </h1> </body> </html> * Connection #0 to host localhost left intact * Closing connection #0

この結果、一般的なブラウザは http://xyz.example.com/foo/bar.html へのリクエストを自動的に実行するはずだ。

参考: http://httpd.apache.org/docs/2.4/en/mod/mod_asis.html

(2)フック関数の登録

フック関数の登録は以下の処理で行われている。


(httpd-2.4.9/modules/generators/mod_asis.c)

    114 static void register_hooks(apr_pool_t *p)
    115 {
    116     ap_hook_handler(asis_handler,NULL,NULL,APR_HOOK_MIDDLE);
    117 }


タイミングはAPR_HOOK_MIDDLEになっている。
つまり、default_handlerより先に実行される。

(3)ハンドラフック関数の処理


処理の流れを追ってみる。
処理対象のリクエストかどうかの判定を行い、対象でなければ、DECLINEで終了する処理が開始時に行われる。
あとは、リクエストのファイルを読み込み、解析し、必要なレスポンスを生成し、出力フィルタに引き渡す処理が行われている。
以下の処理を眺めるだけでは、Dateヘッダや、Serverヘッダや、Content-Lengthヘッダが追加されている様子はない。これは出力フィルタで行われる。


(httpd-2.4.9/modules/generators/mod_asis.c)
     31 static int asis_handler(request_rec *r)
     32 {
     33     apr_file_t *f;
     :
     37     if (strcmp(r->handler, ASIS_MAGIC_TYPE) && strcmp(r->handler, "send-as-is")) {
リクエストが、send-as-isハンドラで処理されるべきかどうかを判定している 箇所。ASIS_MAGIC_TYPEは "httpd/send-as-is"で、仮想的なMIME Typeになって いる。これでも指定できるということだ。 AddHandler send-as-is asis と指定しているなら、r->handlerに"send-as-is" が設定されている場合に処理される。
     38         return DECLINED;
DECLINEDで返るのは、次のhandlerフック関数の処理を継続するためだ
     39     }
     :
     42     if (r->method_number != M_GET) {
send-as-isハンドラはGETリクエストだけを処理する。 POSTリクエストなどの場合は、処理対象としない。
     43         return DECLINED;
     44     }
     45
     46     if (r->finfo.filetype == APR_NOFILE) {
     47         ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r, APLOGNO(01233)
     48                     "File does not exist: %s", r->filename);
     49         return HTTP_NOT_FOUND;
指定したファイルが存在しない場合は 404 not foundを返す。
     50     }
     51
     52     if ((rv = apr_file_open(&f, r->filename, APR_READ,
     53                 APR_OS_DEFAULT, r->pool)) != APR_SUCCESS) {
     54         ap_log_rerror(APLOG_MARK, APLOG_ERR, rv, r, APLOGNO(01234)
     55                     "file permissions deny server access: %s", r->filename);
     56         return HTTP_FORBIDDEN;
指定したファイルをオープンする。 失敗した場合には、 403 Forbidden を返す
     57     }
     58
     59     ap_scan_script_header_err_ex(r, f, NULL, APLOG_MODULE_INDEX);
ファイルのHTTPレスポンスヘッダ部分(空行までの部分)の処理を実行している。 Status: XXX の場合は、ステータス行にセットされ、 その他、適宜、レスポンス用のヘッダ情報にセットされる。
     60     location = apr_table_get(r->headers_out, "Location");
     61
     62     if (location && location[0] == '/' &&
     63         ((r->status == HTTP_OK) || ap_is_HTTP_REDIRECT(r->status))) {
これは、指定したファイルにLocationヘッダが指定されており、 リクエストがリダイレクトされるように指定されていたことを意味している。 しかもリダイレクト先が "/"で始まるので、自サーバ上のパスと考えられる。 ここではこのlocationへのリクエスト(内部リダイレクトリクエスト)を実行 している。
     64
     65         apr_file_close(f);
     66
     67         /* Internal redirect -- fake-up a pseudo-request */
     68         r->status = HTTP_OK;
     69
     70         /* This redirect needs to be a GET no matter what the original
     71          * method was.
     72          */
     73         r->method = "GET";
     74         r->method_number = M_GET;
     75
     76         ap_internal_redirect_handler(location, r);
     77         return OK;
     78     }
     79
     80     if (!r->header_only) {
HEADではない場合の処理となる。 先に指定されたファイルのHTTPレスポンスヘッダ部分の処理を終えている。 ここは、引き続きボディ部の処理を実行する。
     81         conn_rec *c = r->connection;
     82         apr_bucket_brigade *bb;
     83         apr_bucket *b;
     84         apr_off_t pos = 0;
     85
     86         rv = apr_file_seek(f, APR_CUR, &pos);
     87         if (rv != APR_SUCCESS) {
     88             ap_log_rerror(APLOG_MARK, APLOG_ERR, rv, r, APLOGNO(01235)
     89                           "mod_asis: failed to find end-of-headers position "
     90                           "for %s", r->filename);
     91             apr_file_close(f);
     92             return HTTP_INTERNAL_SERVER_ERROR;
     93         }
     94
     95         bb = apr_brigade_create(r->pool, c->bucket_alloc);
bucket brigade bbを作成する
     96         apr_brigade_insert_file(bb, f, pos, r->finfo.size - pos, r->pool);
指定したファイルの現在位置(ボディ部の開始)~終了位置(ファイルサイ ズから、開始位置を引いた値)でファイルbucketを生成し それを bucket brigade bb に挿入する。
     97
     98         b = apr_bucket_eos_create(c->bucket_alloc);
     99         APR_BRIGADE_INSERT_TAIL(bb, b);
EOS bucket(メタデータ)を作成し、これを bucket brigade bb の末尾に 追加する
    100         rv = ap_pass_brigade(r->output_filters, bb);
そして bucket brigade bb を出力フィルタに引き渡す。
    101         if (rv != APR_SUCCESS) {
    102             ap_log_rerror(APLOG_MARK, APLOG_ERR, rv, r, APLOGNO(01236)
    103                           "mod_asis: ap_pass_brigade failed for file %s", r->filename);
    104             return HTTP_INTERNAL_SERVER_ERROR;
    105         }
    106     }
    107     else {

HEADリクエストの場合は、ボディ部の処理はないので、終了する。
ヘッダ情報は、request_rec情報のheaders_out配列に登録されているが、
まだ送信はされていない。
空のbucket brigadeを出力フィルタに渡すなどの処理も行われていない。


    108         apr_file_close(f);
    109     }
    110
    111     return OK;
    112 }


その他のハンドラフック関数も順に調査していきたいが、とりあえず、今回はここまで。

2014年6月26日木曜日

ハンドラ(handler) フック関数の例: default_handler

フック関数の一覧の続きだ。
フックポイントには多くの種類があって、どういったタイミングで呼ばれるのか、私にはよく分からないものも多い。
ハンドラフック関数は、ハンドラ処理のフック関数だ。
ハンドラは、ドキュメントには「ファイルが呼ばれたときに実行される動作の Apache における内部表現」とある。
参考: http://httpd.apache.org/docs/2.4/ja/handler.html

default_handler

ふつうApacheはHTMLファイルをリクエストされれば、ファイルシステム上のそのHTMLファイルを読み込んでレスポンスとして返す。
その処理を行うのが、default_handler ハンドラだ。

(1)フック関数の登録


フック関数 default_handler を登録する処理は次のようになっている

(httpd-2.4.9/server/core.c)


4885 ap_hook_handler(default_handler,NULL,NULL,APR_HOOK_REALLY_LAST);

APR_HOOK_REALLY_LASTは、実行順序の最後を意味する。
(apr-util-1.5.3/include/apr_hooks.h より)
マクロ 値 備考
APR_HOOK_REALLY_FIRST -10 どれよりも先に実行したい
APR_HOOK_FIRST 0 先頭グループ
APR_HOOK_MIDDLE 10 中間グループ
APR_HOOK_LAST 20 最終グループ
APR_HOOK_REALLY_LAST 30 どれよりも後に実行したい

値が小さいものが先に実行される。
別のハンドラがハンドラフックポイントに登録されている場合、そのハンドラを先に実行してから、default_handlerは実行される。
ハンドラフック関数は、RUN_FIRSTタイプなので、フック関数の戻り値がDECLINE以外の場合に処理を終了する。
つまり、OKや、エラーステータスが返されると処理は終了する。
終了するということは、登録された次のフック関数は処理されないということだ。
要するに、default_handlerは他のハンドラで処理されなかったリクエストを処理するハンドラ、ということになる。

(2)ハンドラフック関数の処理

実行される処理は次の通り。

(httpd-2.4.9/server/core.c)

   4248 static int default_handler(request_rec *r)
   4249 {
   4250     conn_rec *c = r->connection;
   4251     apr_bucket_brigade *bb;
   4252     apr_bucket *e;
    :

   4277     if ((errstatus = ap_discard_request_body(r)) != OK) {
KeepAliveな接続の場合は、入力フィルタからbucket brigadeを吸い上げ、 Content-Length分のボディ部分を読み捨てるなどの処理を実行している
   4278         return errstatus;
   4279     }
    :

   4281     if (r->method_number == M_GET || r->method_number == M_POST) {
    :

   4330         if ((status = apr_file_open(&fd, r->filename, APR_READ | APR_BINARY
   4331 #if APR_HAS_SENDFILE
   4332                             | AP_SENDFILE_ENABLED(d->enable_sendfile)
   4333 #endif
   4334                                     , 0, r->pool)) != APR_SUCCESS) {

r->filenameがリクエストされたファイルを指している オープンできない場合には、403 Forbiddenを返す 
   4335             ap_log_rerror(APLOG_MARK, APLOG_ERR, status, r, APLOGNO(00132)
   4336                           "file permissions deny server access: %s", r->filename);
   4337             return HTTP_FORBIDDEN;
   4338         }
   4339
   4340         ap_update_mtime(r, r->finfo.mtime);

リソースの最終更新日時の情報(r->mtime)を更新している
   4341         ap_set_last_modified(r);

Last-Modifiedヘッダをレスポンス情報にセットしている。 値は、ap_update_mtime()で更新された値
   4342         ap_set_etag(r);

ETagヘッダをレスポンス情報にセットしている。
   4343         ap_set_accept_ranges(r);

Accept-Rangesヘッダをレスポンス情報にセットしている。 MaxRangesディレクティブの指定が"none"の場合は、"none"。それ以外は、"bytes"
   4344         ap_set_content_length(r, r->finfo.size);

Content-Lengthヘッダをレスポンス情報にセットしている。 値は、r->finfo.size。
   4345         if (bld_content_md5) {
   4346             apr_table_setn(r->headers_out, "Content-MD5",
   4347                            ap_md5digest(r->pool, fd));

ContentDigestディレクティブに指定に応じて、 Content-MD5ヘッダをレスポンス情報にセットしている
   4348         }
   4349
   4350         bb = apr_brigade_create(r->pool, c->bucket_alloc);

ここでbucket brigade bbを作成している
   4351
   4352         if ((errstatus = ap_meets_conditions(r)) != OK) {
   4353             apr_file_close(fd);
   4354             r->status = errstatus;
   4355         }
   4356         else {
   4357             e = apr_brigade_insert_file(bb, fd, 0, r->finfo.size, r->pool);

ここで、ターゲットのファイルのファイルbucket を作成し bucket brigade bbに挿入している
   4358
   4359 #if APR_HAS_MMAP
   4360             if (d->enable_mmap == ENABLE_MMAP_OFF) {
   4361                 (void)apr_bucket_file_enable_mmap(e, 0);
   4362             }
   4363 #endif
   4364         }
   4365
   4366         e = apr_bucket_eos_create(c->bucket_alloc);
   4367         APR_BRIGADE_INSERT_TAIL(bb, e);

EOSメタデータbucketを作成し、 bucket brigade bb に追加した。 ここまでで、bb には ファイルbucketとEOSバケットが格納されている
   4368
   4369         status = ap_pass_brigade(r->output_filters, bb);

ここで、bucket brigade bb を出力フィルタに引き渡す。
   4370         if (status == APR_SUCCESS
   4371             || r->status != HTTP_OK
   4372             || c->aborted) {
   4373             return OK;
   4374         }
   4375         else {
   4376             /* no way to know what type of error occurred */
   4377             ap_log_rerror(APLOG_MARK, APLOG_DEBUG, status, r, APLOGNO(00133)
   4378                           "default_handler: ap_pass_brigade returned %i",
   4379                           status);
   4380             return HTTP_INTERNAL_SERVER_ERROR;
   4381         }
    :

   4406 }

ひとまず、もう一つくらい、handlerの例を書く。

2014年6月16日月曜日

フック関数の一覧

続いて、フック関数の種類について書く。

フックポイントの一覧

Apache httpdで用意されているフックポイントにはどんなものがあるか。
あるフック関数の実行関数 ap_run_hogehoge()の実行箇所は一か所とは限らず、また必ず実行されるわけでもないので、どういった条件で実行されるかを明確にするのは難しいケースがある。

ひとまずは、httpd-2.4.9でAP_IMPLEMENT_HOOK_RUN_ALL/RUN_FIRST/VOID で定義されているフックポイントの一覧を作成した。
比較として、httpd-2.2.27からも同じマクロで定義されているフックポイントを並べている。
減ったフックポイントは見当たらない。追加されたポイントが、17あった。
分類は、下記で説明するmod_infoでの分類を書いた。が、もう少し細かく分類してもいいと思う。

seq フックポイント 処理タイプ フックポイント(2.2.27) 分類(mod_info)
1 access_checker RUN_ALL access_checker リクエスト処理系
2 access_checker_ex RUN_FIRST
リクエスト処理系
3 auth_checker RUN_FIRST auth_checker リクエスト処理系
4 check_config RUN_ALL
起動処理系
5 check_user_id RUN_FIRST check_user_id リクエスト処理系
6 child_init VOID child_init 起動処理系
7 child_status VOID
その他
8 create_connection RUN_FIRST create_connection リクエスト処理系
9 create_request RUN_ALL create_request リクエスト処理系
10 default_port RUN_FIRST default_port リクエスト処理系
11 dirwalk_stat RUN_FIRST
(なし)
12 drop_privileges RUN_ALL
起動処理系
13 end_generation VOID
その他
14 error_log VOID error_log その他
15 expr_lookup RUN_FIRST
その他
16 fatal_exception RUN_ALL fatal_exception その他
17 fixups RUN_ALL fixups リクエスト処理系
18 generate_log_id RUN_FIRST
リクエスト処理系
19 get_mgmt_items RUN_FIRST get_mgmt_items その他
20 get_suexec_identity RUN_FIRST get_suexec_identity (なし)
21 handler RUN_FIRST handler リクエスト処理系
22 header_parser RUN_ALL header_parser リクエスト処理系
23 http_scheme RUN_FIRST http_scheme, リクエスト処理系
24 insert_error_filter VOID insert_error_filter リクエスト処理系
25 insert_filter VOID insert_filter リクエスト処理系
26 insert_network_bucket RUN_FIRST
(なし)
27 log_transaction RUN_ALL log_transaction リクエスト処理系
28 map_to_storage RUN_FIRST map_to_storage リクエスト処理系
29 monitor RUN_ALL monitor その他
30 mpm RUN_FIRST
起動処理系
31 mpm_get_name RUN_FIRST
その他
32 mpm_query RUN_FIRST
その他
33 mpm_register_timed_callback RUN_FIRST
その他
34 note_auth_failure RUN_FIRST
リクエスト処理系
35 open_htaccess RUN_FIRST
(なし)
36 open_logs RUN_ALL open_logs 起動処理系
37 optional_fn_retrieve VOID optional_fn_retrieve 起動処理系
38 post_config RUN_ALL post_config 起動処理系
39 post_perdir_config RUN_ALL
(なし)
40 post_read_request RUN_ALL post_read_request リクエスト処理系
41 pre_config RUN_ALL pre_config 起動処理系
42 pre_connection RUN_ALL pre_connection リクエスト処理系
43 pre_mpm RUN_ALL pre_mpm 起動処理系
44 pre_read_request VOID
リクエスト処理系
45 process_connection RUN_FIRST process_connection リクエスト処理系
46 quick_handler RUN_FIRST quick_handler リクエスト処理系
47 test_config VOID test_config 起動処理系
48 translate_name RUN_FIRST translate_name リクエスト処理系
49 type_checker RUN_FIRST type_checker リクエスト処理系

mod_infoで見るフック関数情報

mod_infoで各フックポイントに登録されているフック関数の情報を一覧することができる。
http://localhost/server-info?hooks
ただ、調べてみると、出力されるフックポイントは一部欠けている(上の表で「(なし)」と書いたのが欠けているフックポイント)。
関数も関数名が一覧されるわけではなく、その関数を登録したファイル名が出力されている。

処理を見ると、ap_hook_get_hogehoge()でhogehogeフックポイントの登録情報(apr_array_header_t情報)を取得する。
apr_array_header_t情報は、配列情報の管理情報で、内部にメモリプールの情報なども持っているが、基本的には、apr_array_header_t.nelts 個の有効な要素を持つ配列 apr_array_header_t.elts の格納庫だ。
このapr_array_header_t構造体自体は汎用で フック関数の登録先に利用する場合にはapr_array_header_t.eltsには、各フック関数用の構造体 ap_LINK_hogehoge_t が格納される。

mod_infoで出力されるのは、ap_LINK_hogehoge_t.szNameで、ここにはモジュールのCファイル名が入っている。
各モジュールごとにフック関数の型が異なるので、この構造体の個々の定義は異なっているが、その辺気にしなければ(実際に関数をを呼び出すのでなければ)、ダミーの構造体で処理可能らしい。mod_infoでは、処理用の構造体を用意してこのモジュールCファイル名と、実行時の順序を制御するための値 ap_LINK_hogehoge_t.nOrder を出力している。



引き続き、主なフック関数を確認すれば、フック関数の全体のイメージが把握できるのではないか。

2014年6月9日月曜日

フック関数の概要

フック関数について書く
フック関数の処理はマクロ化されているので、まず、そのあたりをまとめる。
概要は、2.4系も2.2系も異ならないのではないか。


http://httpd.apache.org/docs/2.4/en/developer/hooks.html

Apache httpdのライフサイクルには、起動時/再起動時の設定ファイルの読込みから、リクエスト処理のための子プロセス/スレッドの生成、接続の受付け、リクエストの受付け、内容を解析し、処理し、レスポンスを返すという、リクエスト処理のサイクルを通して、多数のフックポイントが用意されている。
例えば、hogehogeというフックポイントがあって、そこでフック関数を呼び出すために行われる処理は、 ap_run_hogehoge() という名前の関数だ。
このap_run_hogehoge()関数は、hogehogeフック関数の登録リストに登録されたフック関数を順に実行する。
このフック関数実行関数ap_run_hogehoge()には、登録されたフック関数をすべて無条件に実行するものと、いずれかの関数が所定の戻り値を返すと処理を終了するものが存在する。
そして、ap_run_hogehoge() で実行されるフック関数を登録するのが、ap_hook_hogehoge()という名前の関数だ。

ソースコードをgrepなどで検索すると、ap_run_hogehogeやap_hook_hogehogeという関数が使われる個所は多数見つかるが、実際にその関数が定義されている個所はない。これは、ap_run_hogehogeとap_hook_hogehogeがマクロで定義されているためだ。

と書きながら、実際にgrepしてみたところ、 post_configフック関数が検索で見つかる(server/config.c)。
マクロを展開したコードがコメントとして残されているようだ。

2014年6月2日月曜日

入力フィルタの概要

入力フィルタについて書くが、出力フィルタの概要の記述を前提とする。

出力フィルタは、メイン処理が送り出したデータを加工、処理し、ネットワークへの出力までを行った。
入力フィルタは、ネットワークから受け取ったデータを加工、処理してメイン処理に引き渡す。
データの流れる方向は、当たり前だが出力フィルタとは逆向きになる。
出力フィルタは、ap_pass_brigade()関数によって、bucket brigadeをフィルタの階層の下流に向かって送り出していた。
入力フィルタもまた、階層をなしている。
メイン処理は、入力フィルタの階層を通して、bucket brigadeを吸い上げる処理を行う。
吸い上げると言うのは、相変わらず下にネットワークがあって、メイン処理が上にあるというイメージからの表現だ。
各入力フィルタは、下流のフィルタから吸い上げた bucket brigadeを処理し、それを上流のフィルタに引き渡している。