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

ngx_mruby v2.7.9

initializeが例外を出したオブジェクトと、dupかcloneで作ったコピーで、upstreamのメソッドはnilを返したりworkerを終わらせたりせず、ArgumentErrorを出します(#816、#819)

Section titled “initializeが例外を出したオブジェクトと、dupかcloneで作ったコピーで、upstreamのメソッドはnilを返したりworkerを終わらせたりせず、ArgumentErrorを出します(#816、#819)”
  • 変更前:Nginx::Upstream#initializeとNginx::Stream::Connection#initializeは、その名前のupstreamがあることを確かめる前に、オブジェクトにupstreamを持たせていました。upstreamのメソッドは、オブジェクトが持つupstreamを確かめずに読んでいました。スクリプトは、initializeが例外を出した後も、そのオブジェクトを持ち続けることができました。1つ目の例は、allocateで作ったオブジェクトでinitializeを呼び、例外が出た場合です。2つ目の例は、スクリプトがsendでinitializeをもう一度呼び、その呼び出しが例外を出した場合です。3つ目の例は、initializeでsuperの例外をrescueするサブクラスのオブジェクトです。allocateで作り、initializeを一度も呼んでいないオブジェクトも、同じ状態でした。その名前のupstreamが無かったときは、Nginx::Upstream#serverとNginx::Stream::Connection#upstream_serverはnilを返しました。Nginx::Upstream#server=、#keepalive_cache、#keepalive_cache=とNginx::Stream::Connection#upstream_server=は、NULLポインタを参照し、workerプロセスはセグメンテーション違反で終わりました。upstreamに2つ以上のサーバーがあったとき、またallocateで作ったオブジェクトでは、#serverと#upstream_serverも含めて、これらのどのメソッドでも、同じようにworkerが終わりました。dupかcloneで作ったコピーも、元が.newの返したオブジェクトであっても、upstreamを持っていませんでした。mrubyは、データオブジェクト(RData)をコピーするとき、インスタンス変数をコピーし、データはコピーしないからです。そのようなコピーでこれらのメソッドのどれかを呼ぶと、workerはセグメンテーション違反で終わり、そのHTTPのリクエストにもstreamのセッションにも応答は返りませんでした(#819)。
  • 変更後:initializeは、upstreamとそのサーバーが見つかったときだけ、オブジェクトにupstreamを持たせます。upstreamを持たないオブジェクトでは、Nginx::Upstream#server、#server=、#keepalive_cache、#keepalive_cache=はArgumentErrorを出し、メッセージはuninitialized Nginx::Upstreamです。Nginx::Stream::Connection#upstream_serverと#upstream_server=はArgumentErrorを出し、メッセージはuninitialized Nginx::Stream::Connectionです。スクリプトのほかの例外と同じように、この例外でもハンドラは終わります。スクリプトはrescueでこの例外を捕まえられます。捕まえなければ、ngx_mrubyは例外をログに書き、HTTPのリクエストには500を返し、streamのセッションは閉じます。workerは、次のリクエストとセッションを続けて処理します。例外を出したinitializeの後に、initializeが成功すると、オブジェクトはupstreamを持ち、メソッドはまた動きます。dupかcloneで作ったコピーはupstreamを持たず、メソッドはコピーでも同じArgumentErrorを出します。元のオブジェクトは、upstreamを持ち続けます(#819)。
  • 変更の理由:
    • 不具合:initializeは、オブジェクトのコンテキストを確かめる前に保存していました。コンテキストは、upstream、そのピア、そのサーバーです。また、upstreamに2つ以上のサーバーがあると、古いコンテキストを解放した後、新しいコンテキストを保存する前に例外を出していました。メソッドは、そのコンテキストがupstreamを持つことを確かめずに読んでいました(#816)。
    • 前の挙動を残せなかった理由:upstreamを持たないオブジェクトには、返すサーバーも、変えるサーバーも、接続を保持するサーバーもありません。#serverのnilは、空のコンテキストを読んだ結果で、メソッドが定めた値ではありませんでした。また、同じオブジェクトで次のメソッドを呼ぶとworkerが終わり、そのworkerが処理していたほかのリクエストも終わりました。そのようなオブジェクトでは、upstreamのすべてのメソッドが例外を出す以外に、取りうる挙動はありません。メッセージにuninitializedとクラスの名前を含むArgumentErrorは、同梱のmrubyが、initializeが実行されていない自身のクラスのオブジェクトに対して出す例外です。Timeのuninitialized timeと、Rangeのuninitialized rangeがその例です。
    • ドキュメントが示していた挙動:2.7.8のNginx::Upstream#newとNginx::Stream::Connection#newは、その名前のupstreamが無いとメソッドがRuntimeErrorを出すと書いていました。その後のオブジェクトについては、何も書いていませんでした。
  • 影響の範囲:Nginx::UpstreamかNginx::Stream::Connectionのオブジェクトを、initializeが例外を出した後も使い続けるスクリプト、allocateで作ったオブジェクトを使うスクリプト、これらのクラスのオブジェクトをdupかcloneでコピーして使うスクリプト(#819)のうち、そのオブジェクトで#server、#server=、#keepalive_cache、#keepalive_cache=、#upstream_server、#upstream_server=を呼ぶものです。Nginx::Upstream.newかNginx::Stream::Connection.newが返したオブジェクトは、これまでと同じように動きます。ただし、そのオブジェクトをdupかcloneでコピーしたものは、これまでと同じようには動きません。#remote_ipや#stream_statusのように、upstreamを使わないNginx::Stream::Connectionのメソッドは、影響を受けません。
  • 必要な対応:オブジェクトはNginx::Upstream.newかNginx::Stream::Connection.newで作り、その呼び出しが例外を出したら使わないでください。別のupstreamを使うときは、別のオブジェクトを作ってください。オブジェクトをdupかcloneでコピーしないでください。同じupstreamを使う2つ目のオブジェクトが必要なときは、.newで作ってください(#819)。upstreamを持たないオブジェクトでこれらのメソッドを呼ぶコードは、2.7.8ではnilを受け取るか、workerを終わらせていました。

Nginx.module_versionとerror.logの起動時の行は、2.7.1ではなく、リリースのバージョンの2.7.9を示します(#822)

Section titled “Nginx.module_versionとerror.logの起動時の行は、2.7.1ではなく、リリースのバージョンの2.7.9を示します(#822)”
  • 変更前:2.7.2から2.7.8では、Nginx.module_versionは2.7.1を返しました。nginxは、http {}ブロックのある設定を読み込むと、error.logにレベルnoticeで、ngx_mruby/2.7.1 (mruby/3.3.0) mechanism enabledで始まる行を書きました。nginxは、この文字列の後に、設定ファイルの名前と行番号を示す in <file>:<line>を付けます。
  • 変更後:Nginx.module_versionは2.7.9を返し、error.logの行はngx_mruby/2.7.9 (mruby/3.3.0) mechanism enabledで始まります。以後のリリースも、自身のバージョンを示します。モジュールのバージョンが、docs/releases/にある最も新しいリリースのファイルのバージョンと異なると、テストスイートが失敗するからです。
  • 変更の理由:
    • 不具合:どちらも、src/http/ngx_http_mruby_module.hのMODULE_VERSIONを読みます。この値は2.7.1のリリースで2.7.1に設定され、その後の7回のリリースで一度も変更されていませんでした。docs/releases/README.mdにあるリリースの手順は、この値を設定することも、確かめることも求めていませんでした(#822)。
    • 前の挙動を残せなかった理由:この値は、モジュールをビルドしたリリースを示す値です。2.7.2から2.7.8では、この値は2.7.1を示していましたが、2.7.1は修正の内容も挙動もそれらのリリースと異なります。そのため、この値を読むスクリプトや監視は、それらのリリースを2.7.1とも、互いにも区別できませんでした。2.7.1のままにすれば、2.7.9も同じ誤った値を返すことになります。
    • ドキュメントが示していた挙動:2.7.1のリリースノートのアップグレードの節は、Nginx.module_versionがそのリリースのバージョンである2.7.1を返すと書いていました。2.7.8のNginx.module_versionは、このメソッドがngx_mrubyのバージョンを返すと書き、例として0.0.1を示していました。2.7.2から2.7.8のリリースノートは、この値に触れていませんでした。
  • 影響の範囲:Nginx.module_versionが返す文字列を比べるスクリプトです。たとえば、2.7.1と比べるスクリプトや、バージョンによって実行するコードを選ぶスクリプトです。error.logの、ngx_mruby/で始まりmechanism enabledを含む行を読む監視も影響を受けます。この値では、2.7.2から2.7.8を区別できません。どれも2.7.1を返すからです。
  • 必要な対応:スクリプトや監視がこの値を2.7.1と比べているときは、2.7.9か、使っているリリースのバージョンと比べてください。2.7.2から2.7.8を区別するには、この値ではなく、モジュールをビルドしたリリースのタグかコミットを使ってください。

ありません。

  • Nginx::Upstream#server、#server=、#keepalive_cache、#keepalive_cache=と、Nginx::Stream::Connection#upstream_server、#upstream_server=は、initializeが例外を出したオブジェクト、allocateで作ったオブジェクト、dupかcloneで作ったコピーで、ArgumentErrorを出すようになりました。これまでは、nilを返すか、NULLポインタを参照してworkerプロセスを終わらせていました(#816、#819)。
  • Nginx::Upstream.newとNginx::Stream::Connection.newは、upstreamに2つ以上のサーバーがあるために例外を出すとき、新しいオブジェクトのコンテキストのメモリを解放するようになりました。これまでは、そのような呼び出しのたびに、そのメモリがworkerが終了するまで確保されたままでした(#816)。
  • 新しいテストケースとして、test/t/cases/upstream_uninitialized.rbと、ポート18093のtest/conf/conf.d/97-upstream-uninitialized.confのサーバーと、ポート12397のtest/conf/conf.d/stream/53-upstream-uninitialized.confのstreamのサーバーを加えました(#816)。
  • test/t/cases/upstream_uninitialized.rbは、.newが返したオブジェクトのdupとcloneによるコピーでも、既存のケースと同じHTTPとstreamのサーバーでupstreamのメソッドを呼び、ArgumentErrorが出ることを確かめるようになりました。元のオブジェクトがupstreamを持ち続けることも確かめます(#819)。
  • test/t/cases/argument_types.rbがテストするtest/conf/conf.d/96-argument-types.confのサーバーを、ポート18200から、nextと同じ18092に移しました。新しいテストのケースは、masterとnextのどちらでも使われていないポートを、HTTPでは18080から18199、streamでは12345から12399の範囲から選びます。AGENTS.mdとdocs/test/README.mdに、この規則を書きました(#819)。
  • テストのnginxのworker_connections(test/conf/nginx.conf)を、200から、nextと同じ1024にしました。nginxは、listenしているソケットを1つずつworkerの接続として数えます。masterのテストのnginxは、TCPの87個とUDPの2個を合わせた89個のソケットでlistenし、200で通ります。nextのテストのnginxは125個のソケットでlistenし、valgrindの下では、test/t/cases/_wait_for_listen.rbが起動時に各ポートへ開く接続で、200の残りを使い切っていました。同じ値にしたので、この行は両方のブランチで同じになります(#819)。
  • test/t/cases/module_and_request.rbは、src/http/ngx_http_mruby_module.hのMODULE_VERSIONが、docs/releases/vX.Y.Z.mdのファイルのうち最も新しいバージョンと同じであることを確かめます。バージョンは数として比べます。新しいバージョンのリリースのファイルを作るプルリクエストは、同じプルリクエストでMODULE_VERSIONをそのバージョンにします。そうしないと、テストスイートが失敗します(#822)。
  • ディレクティブの追加、名前の変更、削除はありません。2.7.8と同じ方法でこのリリースのモジュールをビルドし、バイナリか動的モジュールを置き換えてください。Nginx.module_versionは2.7.9を返します。

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

  • initializeが例外を出した後も、Nginx::UpstreamかNginx::Stream::Connectionのオブジェクトを使い続けるスクリプトと、dupかcloneで作ったコピーを使うスクリプト:オブジェクトは.newで作り、その呼び出しが例外を出したら使わないでください。コピーは使わず、.newでもう1つ作ってください。
  • Nginx.module_versionや、error.logのngx_mruby/で始まりmechanism enabledを含む行を、2.7.1と比べるスクリプトと監視:2.7.9か、使っているリリースのバージョンと比べてください。2.7.2から2.7.8は、この値ではなく、リリースのタグかコミットで区別してください。