Skip to content

v2.7.9

Choose a tag to compare

@matsumotory matsumotory released this 15 Nov 14:53
a7800d8

Behavior changes: read before upgrading

The upstream methods raise ArgumentError on an object whose initialize raised and on a copy made with dup or clone, instead of returning nil or ending the worker (#816, #819)

  • Before: Nginx::Upstream#initialize and Nginx::Stream::Connection#initialize gave the object its upstream before they checked that an upstream had the name, and the upstream methods read it without a check. A script could keep such an object after initialize raised: an object from allocate whose initialize raised, an object on which the script called initialize again (with send) and that call raised, or the object of a subclass whose initialize rescued the exception of super. An object from allocate that never got an initialize was in the same state. When no upstream had the name, Nginx::Upstream#server and Nginx::Stream::Connection#upstream_server returned nil, and Nginx::Upstream#server=, #keepalive_cache, #keepalive_cache= and Nginx::Stream::Connection#upstream_server= read through a NULL pointer, and the worker process ended with a segmentation fault. When the upstream had more than one server, and on an object from allocate, every one of these methods, #server and #upstream_server included, ended the worker in the same way. A copy that dup or clone made of an object, also of one that .new returned, had no upstream either: when mruby copies a data object (RData), it copies the instance variables and not the data. Each of these methods on such a copy ended the worker with a segmentation fault, and the request or session got no response (#819).
  • Now: initialize gives the object its upstream only when it found the upstream and its server. On an object without an upstream, Nginx::Upstream#server, #server=, #keepalive_cache and #keepalive_cache= raise ArgumentError (uninitialized Nginx::Upstream), and Nginx::Stream::Connection#upstream_server and #upstream_server= raise ArgumentError (uninitialized Nginx::Stream::Connection). The exception ends the handler like any other exception of the script: a rescue in the script catches it, and otherwise ngx_mruby logs it, the request gets 500, and the stream session is closed. The worker goes on to serve the next request and session. An initialize that succeeds after one that raised gives the object its upstream, and the methods work again. A copy made with dup or clone has no upstream, and the methods raise on it in the same way; the original object keeps its upstream (#819).
  • Why it changed:
    • The defect: initialize stored the context of the object (the upstream, its peers and its server) before it checked them, and freed the old context and raised before it stored a new one for an upstream with more than one server; the methods read that context without checking that it held an upstream (#816).
    • Why the old behavior could not be kept: an object without an upstream has no server to return, change or keep connections for. nil from #server was the result of reading an empty context, not a value that the method defined, and the next method on the same object ended the worker, which also ended the other requests that the worker was serving. Raising for every upstream method is the one behavior that the methods can have on such an object. ArgumentError with uninitialized and the name is what the bundled mruby raises for its own objects whose initialize did not run, such as Time (uninitialized time) and Range (uninitialized range).
    • What the documentation promised: Nginx::Upstream#new and Nginx::Stream::Connection#new in 2.7.8 said that the method raises RuntimeError when no upstream has the name, and said nothing about the object afterwards.
  • Affected: scripts that keep using an Nginx::Upstream or Nginx::Stream::Connection object after its initialize raised, an object from allocate, or a copy that dup or clone made of any object of these classes (#819), and call #server, #server=, #keepalive_cache, #keepalive_cache=, #upstream_server or #upstream_server= on it. An object that Nginx::Upstream.new or Nginx::Stream::Connection.new returned behaves as before (its copies do not), and the methods of Nginx::Stream::Connection that do not use the upstream, such as #remote_ip and #stream_status, are not affected.
  • What to do: create the object with Nginx::Upstream.new or Nginx::Stream::Connection.new, and do not use it when the call raises; to use another upstream, create another object. Do not copy the object with dup or clone: where a script needs a second object for the same upstream, create it with .new (#819). Code that called these methods on an object without an upstream got nil or ended the worker on 2.7.8.

Nginx.module_version and the startup line of error.log give 2.7.9, the version of the release, instead of 2.7.1 (#822)

  • Before: on 2.7.2 to 2.7.8, Nginx.module_version returned 2.7.1, and when nginx read a configuration with an http {} block it logged a line at level notice in error.log that starts with ngx_mruby/2.7.1 (mruby/3.3.0) mechanism enabled (nginx adds in <file>:<line> of the configuration after it).
  • Now: Nginx.module_version returns 2.7.9, and the line in error.log starts with ngx_mruby/2.7.9 (mruby/3.3.0) mechanism enabled. Each later release gives its own version: the suite fails when the version in the module differs from the newest release file in docs/releases/.
  • Why it changed:
    • The defect: both read MODULE_VERSION in src/http/ngx_http_mruby_module.h, which was set to 2.7.1 for that release and was not changed in the seven releases after it. The release procedure in docs/releases/README.md neither set the value nor checked it (#822).
    • Why the old behavior could not be kept: the value names the release that the module was built from. On 2.7.2 to 2.7.8 it named 2.7.1, whose fixes and behavior differ from those releases, so a script or a monitor that read it could not tell those releases from 2.7.1 or from one another. Keeping 2.7.1 would have given 2.7.9 the same wrong value.
    • What the documentation promised: "Upgrading" in v2.7.1.md said that Nginx.module_version returns 2.7.1, the version of that release. Nginx.module_version in 2.7.8 said that the method returns the ngx_mruby version, with 0.0.1 as the example. The release notes of 2.7.2 to 2.7.8 said nothing about the value.
  • Affected: scripts that compare the string that Nginx.module_version returns, for example with 2.7.1 or to choose code by version, and monitoring that reads the line of error.log that starts with ngx_mruby/ and contains mechanism enabled. The value does not tell 2.7.2 to 2.7.8 apart: each of them gives 2.7.1.
  • What to do: where a script or a monitor compares this value with 2.7.1, compare it with 2.7.9, or with the version of the release that you run. To tell 2.7.2 to 2.7.8 apart, use the release tag or the commit that the module was built from, not this value.

更新前に確認する挙動の変更

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)

  • 変更前: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を区別するには、この値ではなく、モジュールをビルドしたリリースのタグかコミットを使ってください。