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

ngx_mruby v2.7.5

Nginx::Async.sleepの後にNginx::DECLINEDを返すrewriteかaccessのハンドラで、後のハンドラが500で応答しなくなります(#740)

Section titled “Nginx::Async.sleepの後にNginx::DECLINEDを返すrewriteかaccessのハンドラで、後のハンドラが500で応答しなくなります(#740)”
  • 変更前:rewriteハンドラ、つまりmruby_rewrite_handlerとmruby_rewrite_handler_codeか、accessハンドラ、つまりmruby_access_handlerとmruby_access_handler_codeが、Nginx::Async.sleepの後にNginx.returnでNginx::DECLINEDを返すと、リクエストはステータスを500にしたまま次のフェーズへ進みました。そのため、そのリクエストの後のmrubyのハンドラがステータスを設定せず出力も書かないと、500で応答しました。例えば、rewriteハンドラの後のaccessハンドラで、静的なファイルを返すlocationでも同じでした。accessハンドラの後の、出力の無いcontentハンドラも同じです。そのような後のmrubyのハンドラが無ければ、nginxのハンドラが自分でステータスを設定するので、nginxはいつもどおり応答し、静的なファイルを200で返していました。
  • 変更後:sleepなしでNginx::DECLINEDを返した場合と同じステータスで、次のフェーズへ進みます。後のmrubyのハンドラがステータスを設定しなくても、残った500は返しません。rewriteハンドラの後では、contentハンドラは自分の出力で応答し、nginxは静的なファイルを200で返します。
  • 変更の理由:
    • 不具合:sleepの後にハンドラを再開するコードが、Nginx::OK以外のすべての結果でリクエストのステータスを500にしていました。リクエストが先へ進むNginx::DECLINEDでも同じでした。この不具合は、メールで報告を受けました。
    • 前の挙動を残せなかった理由:ハンドラがNginx::DECLINEDを返すのは、後のハンドラに応答させるためです。残った500のせいで、どのハンドラも設定していないエラーを後のハンドラが返していました。
    • ドキュメントが示していた挙動:2.7.4のNginx::Async#sleepは、rewriteとaccessのハンドラでsleepを使えると説明し、その後のステータスについては何も書いていませんでした。
  • 影響の範囲:Nginx::Async.sleepを呼んだ後にNginx::DECLINEDを返すrewriteとaccessのハンドラです。同じリクエストの後のmrubyハンドラがステータスを設定せず出力も書かないlocationに限ります。
  • 必要な対応:ありません。500に頼っていた設定では、そのステータスをNginx.returnでハンドラから返してください。

出力ボディフィルターを通るHEAD応答の後も接続を使えます(#752)

Section titled “出力ボディフィルターを通るHEAD応答の後も接続を使えます(#752)”
  • 変更前:mruby_output_body_filterかmruby_output_body_filter_codeのあるlocationへのHEADリクエストで、応答の長さがわかっている場合、応答ヘッダーを受け取った後に接続が閉じられました。ヘッダーがkeep-aliveを示していても同じで、その接続で次に送ったGETへの応答はありませんでした。置き換えた本文が空でも、空でなくても起きました。
  • 変更後:HEADのヘッダー送信に成功すると、本文を送らず処理を終えます。再利用できる接続は次のリクエストにも使います。GET応答、HEAD以外のヘッダーだけの応答、ヘッダーフィルターのエラーの扱いは変えません。
  • 変更の理由:
    • 不具合:ボディフィルターの終了処理が、ヘッダーだけの応答を正常に送った後にもNGX_ERRORを返していました。nginxは出力エラーとして接続を閉じていました。#574のレビューと#628のレビューで確認されています。
    • 前の挙動を残せなかった理由:正常なHEAD応答を出力エラーとして扱い、keep-aliveで使うはずの接続を閉じてしまうためです。
    • ドキュメントが示していた挙動:2.7.4のNginx::Filter#body=は、本文の置き換えとその長さを説明していました。HEADの後に接続を閉じるという記載はありませんでした。
  • 影響の範囲:長さが既知のHEAD応答をmrubyの出力ボディフィルターが送信し、接続を再利用できる場合です。
  • 必要な対応:ありません。接続を意図して閉じる場合は、このエラーに頼らずnginxのkeep-aliveを設定してください。

UDPセッションの待機中にデータグラムが届いてもハンドラを開始し直しません

Section titled “UDPセッションの待機中にデータグラムが届いてもハンドラを開始し直しません”

アドバイザリ:GHSA-wx6w-gpg3-cmc3

  • 変更前:UDPのstreamハンドラが待機している間に同じクライアントからデータグラムが届くたびに、コードを開始し直して待機タイマーを置き換えました。そのタイマーで再開するのは最後に開始したコードだけで、後から届いたデータグラムによって待機の終了時刻が延びました。

  • 変更後:後続のデータグラムが届いても、待機中のハンドラとその待機の終了時刻を保ちます。コードは、自分が呼んだ各sleepの後に1回ずつ再開します。最初のデータグラムは、コードの後のフェーズで使えます。

    待機中に届いた後続のペイロードは、従来どおり破棄します。蓄積しておいて、待機後にproxy_passへ再送することはありません。

    コードが終了してセッションがproxy_passへ進んだ後のデータグラムは、nginxが同じセッションで通常どおり転送します。

    待機中にworker_shutdown_timeoutを迎えると、UDPセッションを終了します。

  • 変更の理由:

    • 不具合:別のデータグラムが待機中の呼び出しを置き換え、そのsleep後のコードを完了させませんでした。
    • 前の挙動を残せなかった理由:先に呼んだsleepの後のコードが実行されず、その待機の終了時刻も指定した時間ではなく後続のデータグラムに左右されました。セッションのaccessハンドラで待機を重ねて開始しても、各データグラムを1回ずつ処理する仕組みにはなりません。
    • ドキュメントが示していた挙動:2.7.4のNginx::Stream::Async#sleepは、待機中にUDPデータグラムが届くたびにコードを開始し直すと明記していました。このリリースでは、その記載どおりの挙動を変更します。
  • 影響の範囲:mruby_streamまたはmruby_stream_codeのハンドラがNginx::Stream::Async.sleepを呼ぶUDPサーバーで、待機が終わる前に同じセッションの別のデータグラムが届く場合です。

  • 必要な対応:streamハンドラはセッション単位の判断に使ってください。各データグラムで必ず行う処理は、転送先のアプリケーションへ移してください。

    すべてのペイロードを届ける必要がある場合は、UDPハンドラで待機しないか、アプリケーションのプロトコルで再送してください。待機中に届いたペイロードをngx_mrubyが再送することはありません。

ありません。

ありません。

  • UDPのstreamハンドラの待機を確かめるテストを加えました。同じセッションへの有限個のデータグラム、連続するsleep、UDPエコーの転送先とのバイナリペイロードの完全一致、再開後の同じプロキシセッションでの通信、待機中のワーカー終了を確認します。独立したnginxはポート12393〜12396を使い、主なケースは12392を使います。

  • CI:masterへのプルリクエストでは、site-v2.ymlのジョブを流しません。site-v2.ymlは、プルリクエストのdocs/から、サイトの2.xのページをビルドしていました。プルリクエストの作者は、2.xのページを手元で確かめます。nextのcheck_links.pyでMarkdownのファイルの相対リンクを確かめ、nextのsite/でNGX_MRUBY_V2_TREE=DIR npm run check:ciを流して、プルリクエストから2.xのページをビルドします。site-v2.ymlは「Run workflow」でだけ動きます。masterへのpushごとに、site-dispatch.ymlがnextのsite.ymlを起こすことは変わりません。site.ymlは、新しいmasterから/v2/をビルドして確かめてから、サイトを公開します。プルリクエストのbaseが進んだとき、CIを流し直すのは、プルリクエストとbaseの新しいコミットの両方がコードかテストを変えたときだけです。説明は、AGENTS.mdの「Review and merge」の条件2と、docs/test/README.mdの「The 2.x pages of the site」にあります(#739)。

  • 新しいテストのケースとして、test/t/cases/async_rewrite_declined.rbと、ポート18187のtest/conf/conf.d/82-async-rewrite-declined.confのサーバーを加えました(#740)。

  • 新しい回帰テストtest/t/cases/head_body_filter.rbは、1本のTCP接続でHEADの後にGETを送ります。2種類の本文の生成元、空の置き換え、通常のHEADとGETの対照ケースを確かめます(#752)。

  • ディレクティブの追加、名前の変更、削除はありません。2.7.4と同じ方法でこのリリースのモジュールをビルドし、バイナリか動的モジュールを置き換えてください。

アップグレードの前に、次の点を確かめてください。各行は、項目の「必要な対応」です。

  • Nginx::Async.sleepの後にNginx::DECLINEDを返すrewriteかaccessのハンドラ:対応は要りません。500に頼っていた設定では、そのステータスをNginx.returnでハンドラから返してください。

  • Nginx::Stream::Async.sleepを呼ぶUDPのstreamハンドラ:セッション単位の判断に使ってください。各データグラムの必須処理は、転送先のアプリケーションに実装してください。

    すべてのペイロードを届ける必要がある場合は、待機しないか、アプリケーションのプロトコルで再送してください。待機中に届いたペイロードをngx_mrubyが再送することはありません。

  • mrubyの出力ボディフィルターを通るHEAD応答:対応は要りません。接続を意図して閉じる場合は、このエラーに頼らずnginxのkeep-aliveを設定してください。