Repository navigation
v2.7.7
Behavior changes: read before upgrading
The line of error.log for an exception whose class redefines inspect or backtrace (#803)
- Before: when Ruby code raised an exception whose class redefines
inspectin Ruby, ngx_mruby wrote no line for the exception toerror.log, whatever the redefined method did. ngx_mruby called the method while the exception was still pending in the mruby state. In that state the bundled mruby does not run the method to its end: it goes on with the pending exception, so neither the String that the method would return nor an exception of the method itself reached ngx_mruby. In a build with--with-debug, abacktraceredefined in Ruby went the same way, and ngx_mruby wrotebacktrace must be Array. mrb_type=18at the debug level and no frame. In the content handler of a location thatNginx.redirectran from anmruby_sethandler, this left the request unfinished, whatever the redefinedinspectdid, or in a build with--with-debugthe redefinedbacktrace, also when it returned a String or an Array: the pending exception went on to themruby_sethandler, past the nginx functions in between. Themruby_sethandler logged that exception again, which for a redefinedinspectagain wrote no line of the exception, and for a redefinedbacktracewrote the line of the exception a second time and no frame. nginx then answered 404 from the static files of the target location instead of 500, and the connection stayed open until the client gave up. - Now: ngx_mruby calls
inspectandbacktracewith the pending exception set aside, and stops an exception that they raise in the logging. Wheninspectreturns a String, the line has that String, as for an exception whose class does not redefine it. Wheninspectraises, the line has#<Class> (inspect raised Class), with the class of the exception and the class of the exception ofinspect; when it returns another value, the line has#<Class> (inspect did not return a String). In a build with--with-debug, the String elements of the result of a redefinedbacktraceare logged, one line each, and its other elements are skipped; abacktracethat raises or does not return an Array is logged at the debug level as before. Inside another mruby call, the request ends with 500 as it does directly under nginx, and the worker goes on to the next request. - Why it changed:
- The defect:
inspectandbacktracewere called while the exception was pending, so a method written in Ruby never gave its result. Inside another mruby call, the pending exception left the logging and the request unfinished, whatever the method did. The same calls are fixed onnextby #796 and #799; this pull request brings the fix to 2.x. - Why the old behavior could not be kept: when an exception leaves the logging and jumps past the nginx functions that handle the request, the request and its connection stay open. When no line of the exception is written, the operator cannot learn from the log that the error happened. The class name in place of an
inspectthat cannot give a String is the line that 3.x writes for the same exception, so 2.x and 3.x write the same line. - What the documentation promised: the documentation said nothing about exceptions whose class redefines
inspectorbacktrace.
- The defect:
- Affected: scripts of every kind of handler (HTTP and stream, and the code that runs when nginx reads the configuration or a worker starts or exits) that raise an exception whose class redefines
inspectorbacktracein Ruby. An exception whose class does not redefine them gets the same line as before, byte for byte. - What to do: nothing, unless you parse
error.logfor these exceptions: the line now exists, with the text of the redefinedinspector the class name.
A non-String argument to a Request setter, Nginx::Async::HTTP.sub_request or Nginx::Headers_in/out#[]=
Security advisory: GHSA-cjxv-4q9m-62pf.
- Before:
Nginx::Request#uri=,#args=,#method=,#protocol=,#request_line=,#unparsed_uri=and#content_type=(which share one macro),Nginx::Async::HTTP.sub_request(the request path), andNginx::Headers_in#[]=andNginx::Headers_out#[]=(the header name, and each value) did not check that the argument was a String, and read a non-String argument as if it were a String. - Now: these methods raise
TypeErrorfor a non-String argument, asNginx.rputs,Nginx.echo,Nginx.redirect,Nginx::Filter#body=and theNginx::Varsetter already do (#775). Anilargument keeps its meaning: a setter leaves the member unchanged and returns, andHeaders#[]=removes the header. - Why it changed:
- The defect: these methods read their argument as a String without checking its type. The advisory linked above has the details.
- Why the old behavior could not be kept: a value that is not a String has no string content, so reading it as a String has no defined result.
- What the documentation promised: the documentation of these methods describes a String argument.
- Affected: scripts that pass to one of these methods a value that may not be a String. A script that passes only a String (a literal, an interpolated string, or a value it has converted) is not affected.
- What to do: where a script may pass a non-String to one of these methods, convert it (for example with
.to_s) or handle theTypeError.
New features
None.
Fixes
- When the class of an exception redefines
inspect(or, in a build with--with-debug,backtrace) in Ruby and the exception is raised in the content handler of a location thatNginx.redirectruns from anmruby_sethandler, nginx now finishes the request with 500, whatever the method does. Before, the exception went on to themruby_sethandler, nginx answered 404, and the connection stayed open until the client gave up (#803) - In a build with
--with-debug, an element of the result of a redefinedbacktracethat is not a String is skipped, as on 3.x. Before, the code read every element as a String without checking its type (#803) Nginx::Upstream#server=and the streamNginx::Stream::Connection#upstream_server=reset their per-peer store when the nginx cycle pool is freed, so a later cycle after a reload inmaster_process offdoes not reuse the store of an earlier cycle (GHSA-pmjr-f94r-j47g)
Build and test changes
- New test case:
test/t/cases/exception_log_script_methods.rb, with the server oftest/conf/conf.d/94-exception-log-script-methods.confon port 18091 and the stream servers oftest/conf/conf.d/stream/52-exception-log-script-methods.confon ports 12383 and 12389 (#803) - New test case:
test/t/cases/type_unchecked_reads.rb, with the server oftest/conf/conf.d/95-type-unchecked-reads.confon port 18192
Upgrading
- No directive was added, renamed or removed. Rebuild the module with this
release the way you built 2.7.6, and replace the binary or the dynamic
module as usual.
Check these before upgrading. Each line is the "What to do" of its entry
above.
- Tools that parse
error.logfor exceptions whose class redefines
inspectorbacktrace: the line of such an exception now exists, with
the text of the redefinedinspector the class name. - Scripts that pass a value that may not be a String to a Request setter,
Nginx::Async::HTTP.sub_requestorNginx::Headers_in/out#[]=: convert it
(for example with.to_s) or handle theTypeErrorthat these methods now
raise for a non-String.
更新前に確認する挙動の変更
クラスがinspectかbacktraceを再定義している例外の、error.logの行(#803)
- 変更前:Rubyのコードが出した例外のクラスが
inspectをRubyで再定義していると、再定義したメソッドが何をしても、ngx_mrubyはその例外の行をerror.logに書きませんでした。ngx_mrubyは、例外がmrubyの状態に残ったままこのメソッドを呼んでいました。この状態では、同梱のmrubyはメソッドを最後まで実行せず、残っている例外のまま処理を進めます。そのため、メソッドが返すはずのStringも、メソッド自身が出す例外も、ngx_mrubyには届きませんでした。--with-debugのビルドでは、Rubyで再定義したbacktraceも同じように扱われ、ngx_mrubyはdebugのレベルでbacktrace must be Array. mrb_type=18を書き、フレームを書きませんでした。mruby_setのハンドラからNginx.redirectで移ったlocationのcontentハンドラでは、再定義したinspectが何をしても、また--with-debugのビルドでは再定義したbacktraceが何をしても、StringやArrayを返す場合も含めて、リクエストが終わりませんでした。残っている例外が、間にあるnginxの関数を飛び越えて、mruby_setのハンドラまで伝わったからです。mruby_setのハンドラは、その例外をもう一度ログに書きました。再定義したinspectの場合は、ここでも例外の行は書かれませんでした。再定義したbacktraceの場合は、例外の行がもう一度書かれ、フレームは書かれませんでした。その後、nginxは500の代わりに、移った先のlocationの静的ファイルから404を返しました。接続は、クライアントが待つのをあきらめるまで開いたままでした。 - 変更後:ngx_mrubyは、残っている例外を退避してから
inspectとbacktraceを呼び、これらのメソッドが出した例外をログの処理の中で止めます。inspectがStringを返すと、行にはそのStringが入ります。これは、inspectを再定義していないクラスの例外と同じ扱いです。inspectが例外を出すと、行には#<Class> (inspect raised Class)が入ります。前のClassは例外のクラス、後のClassはinspectが出した例外のクラスです。inspectがString以外を返すと、行には#<Class> (inspect did not return a String)が入ります。--with-debugのビルドでは、再定義したbacktraceの結果のうちStringの要素を1行ずつ書き、それ以外の要素は飛ばします。例外を出すか、Arrayを返さないbacktraceは、これまでどおりdebugのレベルで書きます。別のmrubyの呼び出しの中でも、nginxの直下と同じように、リクエストは500で終わり、workerは次のリクエストに進みます。 - 変更の理由:
- 不具合:
inspectとbacktraceは、例外が残ったまま呼ばれていました。そのため、Rubyで書いたメソッドは結果を返せませんでした。別のmrubyの呼び出しの中では、メソッドが何をしても、残っている例外がログの処理を抜け、リクエストが終わりませんでした。nextでは、同じ呼び出しを#796と#799で直しています。このプルリクエストは、その直しを2.xに入れます。 - 前の挙動を残せなかった理由:例外がログの処理を抜けて、リクエストを処理しているnginxの関数を飛び越えると、リクエストとその接続が開いたまま残ります。例外の行が書かれないと、運用者はエラーが起きたことをログから知ることができません。Stringを返せない
inspectの代わりにクラス名を書く行は、3.xが同じ例外に書く行と同じです。これで、2.xと3.xは同じ行を書きます。 - ドキュメントが示していた挙動:ドキュメントは、クラスが
inspectかbacktraceを再定義している例外について、何も書いていませんでした。
- 不具合:
- 影響の範囲:
inspectかbacktraceをRubyで再定義したクラスの例外を出す、すべての種類のハンドラのスクリプトです。HTTPとstreamのハンドラに加えて、nginxが設定を読むときと、workerの開始と終了のときに動くコードも含みます。これらを再定義していないクラスの例外は、これまでと1バイトも変わらない行になります。 - 必要な対応:ありません。ただし、このような例外の行を
error.logから読み取っている場合は、その行が書かれるようになり、再定義したinspectのテキストかクラス名が入ることに注意してください。
Requestのセッター、Nginx::Async::HTTP.sub_request、Nginx::Headers_in/out#[]=へのStringでない引数
アドバイザリ:GHSA-cjxv-4q9m-62pf
- 変更前:
Nginx::Request#uri=、#args=、#method=、#protocol=、#request_line=、#unparsed_uri=、#content_type=(1つのマクロを共有)、Nginx::Async::HTTP.sub_request(リクエストのpath)、Nginx::Headers_in#[]=とNginx::Headers_out#[]=(ヘッダ名と各値)は、引数がStringかどうかを確かめず、Stringでない引数をStringとして読んでいました。 - 変更後:これらのメソッドは、Stringでない引数に対して
TypeErrorを出します。Nginx.rputs、Nginx.echo、Nginx.redirect、Nginx::Filter#body=、Nginx::Varのセッターと同じ扱いです(#775)。nilの引数はこれまでの意味を保ちます。セッターはメンバーを変えずに戻り、Headers#[]=はヘッダを削除します。 - 変更の理由:
- 不具合:これらのメソッドは、引数の型を確かめずにStringとして読んでいました。詳細は、上にリンクしたアドバイザリが示します。
- 前の挙動を残せなかった理由:Stringでない値にはStringとしての内容がないため、Stringとして読んでも定まった結果になりません。
- ドキュメントが示していた挙動:これらのメソッドのドキュメントは、Stringの引数を説明しています。
- 影響の範囲:これらのメソッドのいずれかに、Stringでないかもしれない値を渡すスクリプトです。Stringだけを渡すスクリプト(リテラル、式展開した文字列、変換済みの値)は影響を受けません。
- 必要な対応:スクリプトがStringでない値をこれらのメソッドに渡しうる場合は、
.to_sなどで変換するか、TypeErrorを処理してください。
新機能
ありません。
不具合の修正
- 例外のクラスがRubyで
inspectを再定義しているか、--with-debugのビルドでbacktraceを再定義していて、mruby_setのハンドラからNginx.redirectで移ったlocationのcontentハンドラでその例外が出たとき、メソッドが何をしても、nginxはリクエストを500で終えるようになりました。これまでは、例外がmruby_setのハンドラまで伝わり、nginxは404を返し、接続はクライアントが待つのをあきらめるまで開いたままでした(#803)。 --with-debugのビルドで、再定義したbacktraceの結果のうちString以外の要素を、3.xと同じように飛ばすようになりました。これまでのコードは、型を確かめずに、すべての要素をStringとして読んでいました(#803)。Nginx::Upstream#server=とstreamのNginx::Stream::Connection#upstream_server=は、nginxのcycleのpoolが解放されるときに、peerごとのストアをリセットするようになりました。これにより、master_process offでの再読み込みの後の新しいcycleが、前のcycleのストアを再利用しなくなります(GHSA-pmjr-f94r-j47g)。
ビルドとテストの変更
- 新しいテストのケースとして、
test/t/cases/exception_log_script_methods.rbと、ポート18091のtest/conf/conf.d/94-exception-log-script-methods.confのサーバー、ポート12383と12389のtest/conf/conf.d/stream/52-exception-log-script-methods.confのstreamのサーバーを加えました(#803)。 - 新しいテストのケースとして、
test/t/cases/type_unchecked_reads.rbと、ポート18192のtest/conf/conf.d/95-type-unchecked-reads.confにあるサーバーを加えました。
アップグレード
- ディレクティブの追加、名前の変更、削除はありません。2.7.6と同じ方法でこのリリースのモジュールをビルドし、バイナリか動的モジュールを置き換えてください。
アップグレードの前に、次の点を確かめてください。各行は、項目の「必要な対応」です。
inspectかbacktraceを再定義したクラスの例外の行をerror.logから読み取っているツール:このような例外の行が書かれるようになり、再定義したinspectのテキストかクラス名が入ります。- Requestのセッター、
Nginx::Async::HTTP.sub_request、Nginx::Headers_in/out#[]=にStringでないかもしれない値を渡すスクリプト:.to_sなどで変換するか、これらのメソッドがStringでない引数に対して出すTypeErrorを処理してください。