コンテンツにスキップ
2.x保守ブランチのドキュメントです。最新リリースタグは v2.7.12。導入例の対象バージョンを確認してください。開発中の3.xは、3.xのドキュメントを読んでください。

ngx_mruby v2.7.12

1. mrubyの出力フィルタを通るHEAD、204、304のレスポンスの後も、接続を再利用できる(#853)

Section titled “1. mrubyの出力フィルタを通るHEAD、204、304のレスポンスの後も、接続を再利用できる(#853)”
  • 変更前:ヘッダだけで終わるレスポンスがmrubyの出力フィルタを通ると、クライアントはConnection: keep-aliveの付いたヘッダを受け取り、その後にnginxが接続を閉じていました。こうしたレスポンスには、HEADのリクエストへのレスポンス、If-Modified-SinceかIf-None-Matchの付いたGETにnginxが返す304、return 204;のような204があります。クライアントがその接続で次に送ったリクエストには、レスポンスが返りませんでした。mruby_output_header_filterかmruby_output_header_filter_codeを持ち、mrubyのボディフィルタを持たないlocationでは、HEAD、204、304のすべてで起きていました。mruby_output_body_filterかmruby_output_body_filter_codeを持つlocationでは、autoindexの一覧や、Content-Lengthをnginxが取り除く静的なファイルの304のようにContent-Lengthの無いレスポンスで起きていました。nginxがContent-Lengthを0にするreturn 204;の204のように、Content-Lengthのある204と304でも起きていました。ボディフィルタを通る、長さの分かっているHEADのレスポンスの後は、2.7.5から接続を再利用できていました(#752)。
  • 変更後:HEADのリクエストへのレスポンスと、204と304のレスポンスは、ヘッダで終わります。このレスポンスのヘッダをnginxが送った後、ngx_mrubyは、ヘッダの送信の結果をそのまま返し、ボディを次のフィルタに渡しません。ヘッダでレスポンスが終わるときにnginx自身のハンドラが行うのと同じ扱いです。nginxは、再利用できる接続を次のリクエストのために開いておきます。クライアントが受け取るステータスとヘッダは変わらず、ヘッダの後にボディのバイトは続きません。次の3つは、これまでどおりに扱います。GETのレスポンス、ヘッダの送信の結果がNGX_ERRORの場合、フィルタのコードがエラーになった場合です。
  • 変更の理由:
    • 不具合:nginxのヘッダフィルタは、HEAD、204、304のレスポンスのヘッダを送るときにr->header_onlyを設定します。ngx_mrubyがヘッダを次のフィルタに渡す3か所は、ヘッダを送れていても、このフラグが立っているとNGX_ERRORを返していました。1つ目は、ボディフィルタの無いlocationで、ヘッダフィルタのコードを動かした後です。2つ目は、ボディフィルタが、長さの無いレスポンスを扱うときです。3つ目は、ボディフィルタのコードを動かした後のngx_mrb_finalize_body_filterで、2.7.5からはHEAD以外のメソッドでNGX_ERRORを返していました。静的なファイルのハンドラ、return、autoindexのようなnginxのハンドラは、そのNGX_ERRORをそのまま返すので、nginxはリクエストを失敗として終え、接続を閉じていました。3.0.0の開発ブランチでは、同じ不具合を#848と#849で直しています。
    • 前の挙動を残せなかった理由:nginxが正常に送ったHEAD、204、304のレスポンスは、出力のエラーではありません。nginxが接続を閉じていたので、keep-aliveで接続が続くと見込んでクライアントが送った次のリクエストが失われていました。locationのレスポンスにヘッダを足すヘッダフィルタがあると、そのlocationの静的なファイルへの条件付きGETのうち、クライアントがキャッシュを使えるものは、すべて接続を閉じられていました。
    • ドキュメントが示していた挙動:2.7.11のディレクティブのドキュメントは、出力フィルタのあるlocationでのHEAD、204、304のレスポンスについて、何も書いていませんでした。Nginx::Filter#body=は、ボディフィルタを通る長さの分かっているHEADのレスポンスの後は接続を使えること、ヘッダだけで終わるほかのレスポンスの挙動は変わらないことを書いていました。
  • 影響の範囲:mrubyの出力ヘッダフィルタか出力ボディフィルタを通るHEAD、204、304のレスポンスです。挙動が変わるのは、接続を再利用できる場合です。
  • 必要な対応:対応は不要です。接続を意図して閉じたいときは、これまでのように接続が閉じられることに頼らず、nginxのkeep-aliveの設定(keepalive_timeout、keepalive_requests)を使ってください。
  • テスト:ポート18112です(test/conf/conf.d/20-filter-connection.conf、test/t/cases/head_header_filter.rb、test/t/cases/header_only_keepalive.rb)。

2. Nginx::Headers_in#[]=で置き換えたリクエストヘッダは、リクエストの最後のヘッダだった場合も、スクリプトの値が中継先へ送られる(#858)

Section titled “2. Nginx::Headers_in#[]=で置き換えたリクエストヘッダは、リクエストの最後のヘッダだった場合も、スクリプトの値が中継先へ送られる(#858)”
  • 変更前:スクリプトがNginx::Headers_in#[]=でリクエストヘッダを置き換え、置き換えたヘッダがリクエストの最後のヘッダだった場合(たとえばHostだけのリクエスト)、設定によっては、proxy_passとgrpc_passはスクリプトの値を送らず、その名前についてproxy_set_header(かgrpc_set_header)の値か、nginx自身の値だけを送りました。置き換えたヘッダの後ろにほかのヘッダがあった場合と、スクリプトが新しい名前を足した場合は、スクリプトの値も、proxy_set_headerかnginxの値と並んで送られていました。ただし、設定によっては、workerプロセスが終了することもありました(「不具合の修正」を参照)。
  • 変更後:これらのどの場合も、置き換えたヘッダがリクエストのどこにあったかによらず、スクリプトの値も送られます。
  • 変更の理由:
    • 不具合:[]=で足したヘッダにはlowcase_keyとnextが設定されておらず、proxy_passかgrpc_passでリクエストを送るときに、nginxがそれを読んでいました(「不具合の修正」を参照)。スクリプトのヘッダをモジュールが外すかどうかは、nginxが読んだ値で決まっていました。
    • 前の挙動を残せなかった理由:修正では2つのフィールドを設定し、その値によって、どの場合も同じ結果になります。2.xでは、スクリプトが足したヘッダを、これらのモジュールが設定するヘッダの名前と照らし合わせません。最後のヘッダを置き換えた場合を除けば、これまでもそうなっていました。
    • ドキュメントが示していた挙動:2.7.11のNginx::Headers_in#[]=は、リクエストヘッダの値を設定すると書いていました。proxy_passとgrpc_passについては、何も書いていませんでした。
  • 影響の範囲:proxy_passかgrpc_passを使うlocationで、proxy_set_header(かgrpc_set_header)かモジュール自身も設定するリクエストヘッダ(Hostなど)を、スクリプトがNginx::Headers_in#[]=で置き換えていて、そのヘッダが最後のヘッダになるリクエストがある場合です。Hostの場合は、そのようなリクエストでも、ほかのリクエストと同じく、中継先がHostの行を2つ受け取り、中継先がnginxなら400を返します。
  • 必要な対応:スクリプトの値だけを送るには、そのヘッダをNginx::Headers_in#[]=で設定せず、値を変数に入れてproxy_set_headerに渡してください。たとえばmruby_set_code $backend_host '...';か、setで宣言した変数へのNginx::Varの代入で値を入れ、proxy_set_header Host $backend_host;(かgrpc_set_header)と書きます。モジュール自身が設定しない名前なら、その名前のproxy_set_headerを消しても、スクリプトの値だけが送られます。
  • テスト:ポート18099と18100です(test/conf/conf.d/74-headers-in-proxy.conf、test/t/cases/headers_in_proxy.rb)。置き換えたヘッダの後ろにほかのヘッダがある場合、最後のヘッダの場合、ただ1つのヘッダの場合と、Hostを置き換える場合、変数をproxy_set_headerに渡す場合を確かめます。

ありません。

  • return 204;の204のような長さ0のレスポンスがmrubyの出力ボディフィルタを通るとき、ボディフィルタは、空のボディのコピーにNULLを渡さなくなりました。コピーするバイトは無く、レスポンスも変わりません。UndefinedBehaviorSanitizerを有効にしたビルドが、このコピーについてnull pointer passed as argument 1を報告していました(#853)。
  • Nginx::Headers_in#[]=かNginx::Headers_out#[]=で足したヘッダに、lowcase_keyとnextを設定するようになりました。これまでは設定されておらず、proxy_passかgrpc_passがリクエストを中継先へ送るときに、nginxのproxyモジュールかgrpcモジュールがそのlowcase_keyを読んでいました。設定によっては、workerプロセスが終了することがありました。足したヘッダは、proxy_set_headerかgrpc_set_headerが同じ名前を設定している場合も含めて、中継先へ送られます。「更新前に確認する挙動の変更」の2つ目の項目も参照してください(#858)。
  • test/t/cases/head_header_filter.rbとtest/t/cases/header_only_keepalive.rbは、ヘッダだけで終わるレスポンスになるリクエストか、比較のためのリクエストを送り、その後に同じTCP接続でGETを送ります。送り先は、ポート18112のserverに足したlocationです(test/conf/conf.d/20-filter-connection.conf)。確かめるのは、次の場合です。ヘッダフィルタだけを通るreturnのレスポンスと静的なファイルのそれぞれへのHEAD、ボディフィルタを通るautoindexの一覧へのHEADです。この一覧は、ヘッダを1回の書き込みで送れないように毎秒50バイトで送る場合(limit_rate 50、send_timeout 3s)も確かめます。304と204を、ヘッダフィルタだけを通る場合とボディフィルタを通る場合のそれぞれで確かめます。304は、if_modified_since beforeを設定した静的なファイルに、If-Modified-Sinceの付いたGETを送ったときのレスポンスで、204はreturn 204;のレスポンスです。ボディフィルタのlocationが、ファイルより小さい出力バッファで読む静的なファイルには、output_buffers 1 8とsend_timeout 3sを設定したうえで、If-Modified-Sinceの付いたGETとHEADを送り、どちらも304になることを確かめます。test/t/cases/_head_filter_client.rbは、省略できる3つ目の引数でリクエストヘッダの行を受け取れるようになり、204と304のときは、HEADと同じく、最初のレスポンスをヘッダまでで読み終えます(#853)。
  • test/t/cases/headers_in_proxy.rbは、ポート18099と18100のserver(test/conf/conf.d/74-headers-in-proxy.conf)で、proxy_passの前にNginx::Headers_in#[]=でリクエストヘッダを足すか置き換え、中継先が受け取るヘッダを確かめます。確かめるのは、足したヘッダがすべて届くこと(proxy_set_headerも設定する名前と、proxyモジュール自身が設定する名前も含む)、置き換えたヘッダがリクエストのどこにあっても届くこと、変数を通してproxy_set_headerに渡した値が届くことです。#858より前のビルドをvalgrindで動かすと、ここで、設定されていないlowcase_keyの読み取りが報告されます(#858)。
  • ディレクティブの追加、名前の変更、削除はありません。2.7.11と同じ方法でこのリリースのモジュールをビルドし、バイナリか動的モジュールをいつもどおり置き換えてください。Nginx.module_versionは2.7.12を返します。
  • mrubyの出力ヘッダフィルタか出力ボディフィルタを通るHEAD、204、304のレスポンス:対応は不要です。接続を意図して閉じたいときは、nginxのkeep-aliveを設定してください(#853)。
  • proxy_passかgrpc_passを使うlocationで、モジュールも設定する名前のリクエストヘッダをNginx::Headers_in#[]=で置き換える場合:スクリプトの値だけを送るには、代わりに、値を変数に入れてproxy_set_header(かgrpc_set_header)に渡してください(#858)。

アップグレードの前に、上の「更新前に確認する挙動の変更」を読んでください。