3.0.0への移行
このガイドは、スクリプト、設定、ビルドを、ngx_mruby 2.xからngx_mruby 3.0.0へ移すためのものです。このガイドが扱う変更は、どれもv3.0.0のリリースノートのアップグレードの前に読む挙動の変更に1回ずつ書いてあります。2.xが何をしたか、3.0.0が何をするか、何に影響するか、何をすればよいかです。このガイドは、そのエントリーのそれぞれにリンクし、手順と例を加えます。エントリーが影響するスクリプトとビルドの見つけ方、スクリプトの変更の形、結果の確かめ方です。先に、動かしているバージョンより新しい2.xのリリースのリリースノートを読んでください。リリースノートはdocs/releasesにあります。
ngx_mruby 2.xは、mruby 3.3.0を同梱しています。ngx_mruby 3の開発のラインは、mruby 4.1.0-rc2を同梱しています。これは、mruby 4.1.0の2つ目のリリース候補です。v3の計画のdocs/proposals/v3-plan.mdは、7節の決定1で、mruby 4.1.0をv3のmrubyとしています。オーナーは2026年10月29日に、タグを待たずに4.1.0-rc2を同梱すると決めました。4.1.0のタグが付いたら、開発のラインは4.1.0に移ります。同梱のmrubyのエントリーは、ngx_mrubyについて見つけて測った変更で、すべての変更の一覧ではありません。mruby自身が利用者に見える変更をまとめた一覧は、mruby/のdoc/mruby3.4.md、doc/mruby4.0.mdと、4.1のNEWS.mdです。
- モジュールのビルドの方法を確かめます。ビルドの節を見てください。
- 3.0.0が断るディレクティブと、より多くのlocationで動かすディレクティブを見つけて、書き換えます。手順は、設定の節にあります。
- エントリーが影響するスクリプトを見つけて、書き換えます。スクリプトの節を見てください。
- ログのパーサとアラートの設定を更新します。ログの監視の節を見てください。
- mrubyのC APIを使うmrbgemやほかのCのコードをメンテナンスしているなら、そのコードを確かめます。C拡張とmrbgemsの節を見てください。
- 結果を確かめます。結果を確かめるの節を見てください。
-
Ruby 3.0以降でビルドしてください。同梱のmrubyのビルドは、Ruby 2.xでは止まります。詳しくは同梱のmrubyのビルドにRuby 3.0以降が要るにあります。
ruby --versionは、PATHにあるRubyのバージョンを出力します。 -
OpenSSL 3.0以降でビルドしてください。
--with-openssl-srcで渡すOpenSSLも同じです。既定のビルドのDigestとSecureRandomは、ngx_mrubyのgemが定義します。このgemはOpenSSLのEVP_MACとRAND_bytesのAPIを使うので、OpenSSL 1.1.1、LibreSSL、BoringSSLではビルドが止まります。詳しくはDigestとSecureRandomを、OpenSSL 3.0以降が要るngx_mrubyのgemが定義するにあります。openssl versionは、PATHにあるopensslのコマンドのバージョンを出力します。ビルドが使うヘッダのバージョンは、これと違うことがあります。--with-openssl-srcを使うビルドは、渡したソースのヘッダを使います。macOSでは、configureがHomebrewのOpenSSLを/opt/homebrew/opt/opensslか/usr/local/opt/opensslで見つけます。ほかの場所にあるOpenSSL 3は、次の例のように、そのディレクトリをビルドに渡してください。export NGX_MRUBY_CFLAGS="-I$(brew --prefix openssl@3)/include"export NGX_MRUBY_LDFLAGS="-L$(brew --prefix openssl@3)/lib"iij/mruby-digestかmonochromegane/mruby-secure-randomを足した自前の
build_config.rbからは、その行を消してください。既定のgemが同じgemの名前を持ちます。 -
このリリースの
build_config.rbを使うなら、モジュールをビルドし直してください。同梱のmrubyも一緒にビルドします。詳しくは同梱のmrubyが3.3.0から4.1.0-rc2になるにあります。 -
自前の
build_config.rbを使うなら、コアのgemを選ぶ行を見つけてください。詳しくは自前のbuild_config.rbは、mruby 4.1のコアgemの変更に合わせる必要があるにあります。grep -nE 'gembox|mruby-print|hal-posix|mruby-task|mruby-encoding|mruby-sleep|mruby-env|mruby-process|regexp|ngx_mruby_core_gems' build_config.rbngx_mrubyのデフォルトのビルドが入れるコアのgemを残すには、このリリースの
build_config.rbからNGX_MRUBY_CORE_GEMSとngx_mruby_core_gemsをコピーし、そのファイルと同じように、conf.gembox 'full-core'の代わりにngx_mruby_core_gems(conf)を呼んでください。gemを減らすビルドでは、NGX_MRUBY_CORE_GEMS - %w[...]を渡します。一覧に無いgemを加えるには、コアのgemに従ってください。 -
新しくチェックアウトしたツリーやソースのアーカイブからのビルドは、サードパーティのmrbgemsを、
build_config.rb.lockが記録するコミットで取ってきます。詳しくはサードパーティのmrbgemをbuild_config.rb.lockが記録するコミットでビルドするにあります。mruby/buildを残しているツリーでは、ロックを変えたら、次のビルドの前にmruby/buildを消してください。消さないと、クローンに新しいコミットが無いときに、rakeがfatal: reference is not a treeで止まります。rm -rf mruby/buildgemを別のコミットでビルドするには、gemのコミットとbuild_config.rb.lockに従ってください。
-
デフォルトのビルドには、auto-sslのmrbgemと、それと一緒に入っていたクラスがありません。詳しくは既定のビルドからauto-sslのmrbgemと、それに伴うクラスが無くなるにあります。それらを使うスクリプトを探す手順は、スクリプトの節に書いてあります。
-
このリリースのどのビルドにもauto-sslのmrbgemはなく、mrubyのビルドは
NGX_MRUBY_AUTO_SSLをもう読みません。詳しくはauto-sslのmrbgemとNGX_MRUBY_AUTO_SSLが無くなるにあります。この変数は効かないので、ビルドの環境から外してください。Nginx::SSL::ACMEで証明書を取得しているサーバーは、アップグレードの前にnginxのngx_http_ 、つまりnginx-acmeに移るか、2.xを使い続けてください。次のコマンドで、それを使うビルドと設定を探します。acme_ module grep -rnE 'NGX_MRUBY_AUTO_SSL|auto-ssl|Nginx::SSL::ACME' /path/to/build/scripts /path/to/nginx/conf -
./configure --with-mruby-incdirを使うなら、ディレクトリの一覧に<mruby_root>/build/host/includeを加えてください。詳しくはC拡張:mruby.hをインクルードするソースに、生成されたヘッダが必要になるにあります。 -
自前やサードパーティのmrbgemsを使っているなら、C拡張とmrbgemsの節を見てください。
-
1つのコンテキストに2回書いたstreamのフックを、
nginx -tが断る:各stream {}のブロックとその中の各server {}で、mruby_streamとmruby_stream_codeを合わせて2つ以上書いていないかを探してください。各stream {}のブロックでは、mruby_stream_initとmruby_stream_init_code、mruby_stream_init_workerとmruby_stream_init_worker_code、mruby_stream_exit_workerとmruby_stream_exit_worker_codeのそれぞれについても、2つ以上書いていないかを探してください。2.xでコードが動いていたのは後のディレクティブなので、それを残し、ほかを消してください。3.0.0のモジュールのnginx -tは、2つ目のディレクティブとその行を示します。nginx: [emerg] "mruby_stream_code" directive is duplicated in /etc/nginx/nginx.conf:42stream {}のブロックに1つ、server {}に1つ書いたディレクティブは、これまでどおり使えます。そのserverは、自分のコードを動かします。ファイルを読めないstreamのディレクティブのmrb_string(...) load failedの行に合わせたアラートは、mrb_file(にも合うようにしてください。そのような行は、3.0.0では、HTTPのディレクティブと同じくmrb_file(PATH) open failedになります。 -
httpかserverのレベル、またはlocationに書いた出力フィルタが、その下のlocationで動く:フィルタのディレクティブを探し、grep -rnE 'mruby_output_(header|body)_filter' /etc/nginxそれぞれを書いたブロックを確かめてください。
http {}のブロックに書いたフィルタは、すべてのserverのすべてのlocationで動くようになります。server {}のブロックに書いたフィルタはそのserverのすべてのlocationで、locationに書いたフィルタは入れ子のlocationとそのifのブロックで動くようになります。ただし、同じ種類の自分のフィルタを書いたレベルでは、そのフィルタが動きます。静的なファイルやupstreamのレスポンスを含め、そこでのすべてのレスポンスでフィルタが動いてよいかを確かめ、一部のlocationだけで動かすフィルタは、それらのlocationに移してください。2.xでは、こうしたフィルタはこれらのlocationでは動かず、server {}のブロックに書いたフィルタだけが、どのlocationにも一致しないリクエストで動いていました。
ほとんどのエントリーは、検索できるメソッドの名前を挙げています。次のコマンドは、設定のスクリプトのファイルからそれらを探します。/path/to/scriptsは、*_handlerのディレクティブが指定するファイルのディレクトリに置き換えてください。
grep -rnE 'valid_encoding\?|allbits\?|anybits\?|nobits\?|remove_const|module_function|append_features|prepend_features|extend_object|singleton_method_added|\.(included|extended|prepended|inherited|method_added)\(|initialize_copy|respond_to_missing|respond_to\?|method_defined\?|method_missing|instance_methods|\.methods|iv_var|default_proc *=|FileTest|srand|Random\.new|Set\.new|Set\[|flatten_merge|RuntimeError|\.server *=|upstream_server *=|SystemStackError' /path/to/scriptsnginx.confのファイルにある*_codeのディレクティブのインラインのコードも、同じように検索してください。次の項目では、名前だけでは足りないところで何を探すかを書き、変更の例を示します。
-
Hash#inspectとHash#to_sの形式が変わる:値がHashかHashのArrayになるところでinspect、to_s、"#{...}"、%sを使うsprintfやformatを探してください。スクリプトやテストが比べる文字列の=>も探してください。h = {"q" => "x"}Nginx.rputs h.to_s # 2.x: {"q"=>"x"} 3.0.0: {"q" => "x"}Nginx.rputs JSON.generate(h) # {"q":"x"} on both -
Set#inspectとSet#to_sの形式が変わり、Set#flatten_mergeが無くなる:Setについても、同じように検索してください。set.to_a.join(",")は、どちらのバージョンでも同じ文字列を返します。上の検索は、flatten_mergeも見つけます。s.flatten_merge(t)は、s.merge(Set.new(t).flatten)に書き換えます。tがSetかArrayなら、この式はどちらのバージョンでも、2.xのs.flatten_merge(t)と同じSetを返します。s.merge(t.flatten)がそのSetを返すのは、tがSetのときだけです。tがArrayだと、Array#flattenは中のArrayを平坦化してSetを残し、flatten_mergeとは逆になります。t = [2, Set.new([3])]Set.new([1]).flatten_merge(t) # 2.x: the Set of 1, 2 and 3 3.0.0: NoMethodErrorSet.new([1]).merge(Set.new(t).flatten) # the Set of 1, 2 and 3 on bothSet.new([1]).merge(t.flatten) # the Set of 1, 2 and a Set that holds 3, on both -
NoMethodErrorのメッセージがレシーバのクラスを示す:rescue NoMethodErrorの近くのmessageと、スクリプトの中のundefined methodを探してください。e.message == "undefined method 'foo'" # 2.x: true 3.0.0: false (the message goes on with " for NilClass")メッセージを比べる代わりに、
NoMethodErrorそのものをrescueしてください。 -
privateとprotectedの制限が効く:self以外のレシーバで呼んでいるものを探してください。対象は、initialize、initialize_copy、respond_to_missing?、method_missing、トップレベルでdefで定義したメソッド、raise、sprintf、putsのようなKernelのメソッド、privateかprotectedの下のメソッドです。ただし、ハンドラのコードでは、トップレベルでdefで定義したメソッドはpublicのままなので、レシーバを付けた呼び出しを変える必要はありません。詳しくは#502の構想の1.4節にあります。Kernel.Integer(x)のようなKernel自身に対する呼び出しは、どちらのバージョンでも動きます。1.Integer("3")のように、Kernelのメソッドを別のオブジェクトに対して呼ぶと、例外が出ます。protectedのメソッドは、CRubyと同じく、同じクラスのメソッドの中からなら、そのクラスのオブジェクトをレシーバにして呼べます。上の検索はinstance_methodsとmethodsを見つけます。この2つはprivateのメソッドを含みません。そのような呼び出しの前にrespond_to?で確かめても役に立ちません。respond_to?は、privateのメソッドにもtrueを返します。class Routerdef call(r)pick(r) # no receiver: works on bothendprivatedef pick(r)r.uriendendRouter.new.pick(r) # 2.x: works 3.0.0: NoMethodErrorRouter.new.send(:pick, r) # works on both1.Integer("3") # 2.x: 3 3.0.0: NoMethodError (private method 'Integer' called for Integer)Kernel.Integer("3") # 3 on bothInteger("3") # 3 on both -
Module#remove_const、#private、#public、#protected、#module_functionとフックがprivateになる:上の検索でほとんど見つかります。クラスやモジュールに対して呼んだ.private(、.public(、.protected(も探してください。たとえば、Foo.remove_const(:X)はFoo.send(:remove_const, :X)に書き換えます。 -
append_features、prepend_features、extend_objectのオーバーライドが呼ばれなくなる:上の検索で見つかります。module Plugindef self.append_features(base) # 3.0.0: never called, and no errorbase.extend(ClassMethods)superendendmodule Plugindef self.included(base) # called on bothbase.extend(ClassMethods)endend -
allbits?、anybits?、nobits?がIntegerだけのメソッドになる:上の検索で見つかります。Floatのx.allbits?(1)はx.to_i.allbits?(1)に書き換えます。 -
FileTestがモジュールになる:上の検索で、FileTestが見つかります。書き換える必要があるのは、FileTest.exist?のようなメソッドの呼び出し以外の使い方だけになります。 -
メソッドの本体で定数に代入すると
SyntaxErrorになる:スクリプトをコンパイルすると、見つかります。結果を確かめるの節を見てください。def setupTable = {} # 3.0.0: SyntaxError when the script is compiledObject.const_set(:Table, {}) # works on bothend -
文字列の中の
"#@ivar"、"#@@cvar"、"#$global"が変数を展開する:ダブルクォートの文字列、ヒアドキュメント、バッククォートのコマンドの中の#@と#$を探してください。次の検索はコメントも見つけます。見つけた行を1行ずつ読んでください。grep -rnE '#[@$]' /path/to/scripts@id = 7Nginx.rputs "Ticket #@id" # 2.x: Ticket #@id 3.0.0: Ticket 7Nginx.rputs "Ticket \#@id" # Ticket #@id on bothNginx.rputs 'Ticket #@id' # Ticket #@id on both -
自分自身を持つ
Array、Hash、Structを比べられる:上の検索はSystemStackErrorを見つけます。書き換える必要があるのは、そうした比較の周りでこの例外をrescueするスクリプトだけです。 -
Floatの値にビット演算が無くなる:Floatになりうる値に使った
<<、>>、&、|、^、~を探してください。Floatになりうる値はto_fやFloat()の結果とFloatとの演算の結果です。2.xと同じ数を得る方法は、エントリーにあります。x = 1.5x << 1 # 2.x: 3 3.0.0: NoMethodError(x * 2).to_i # 3, the number of 2.x for x << 1x.to_i << 1 # 2, another number -
String#valid_encoding?が既定のビルドに無くなる:上の検索で見つかります。2.xのデフォルトのbuild_config.rbでは、このメソッドは、どの文字列にもtrueを返しました。そのため、次のような確認はリクエストを拒否したことがなく、消してもかまいません。Nginx.return Nginx::HTTP_BAD_REQUEST unless s.valid_encoding? -
シードを与えた
Randomが別の数を返す:上の検索でsrandとRandom.newが見つかります。シードを与えた乱数の生成器の数を期待するテストも探してください。 -
Hash#default_proc=がProcでないオブジェクトにTypeErrorを出す:上の検索で見つかります。h.default_proc = proc { |hash, key| hash[key] = [] }のように、Procを渡してください。 -
キーワード引数を受けるブロックに、キーワード引数を付けて
yieldすると動く:変えるものはありません。この場合に備えて書いたrescue ArgumentErrorには、もう到達しません。 -
ハンドラのコードで、ブロックや
forの本体の中のreturnがコードを終える:スクリプトで変えるものはありません。ハンドラのコードのトップレベルにあるブロックやforの本体の中のreturnは、もうLocalJumpErrorを起こしません。ハンドラは、コードがreturnの前に設定したレスポンスで答えます。2.xは500で答えていました。2.7.0は、contentハンドラがそれまでに書いた出力とともに200で答えていました。unexpected return (LocalJumpError)のログのアラートは、この場合にはもう出ません。 -
出力なしで終わるcontentハンドラが、500でなく、空のボディの200で応答する:ボディを書かずに終わることがある
mruby_content_handlerとmruby_content_handler_codeのハンドラを見てください。条件が成り立つときだけ書くハンドラ、""やnilになりうる値をNginx.rputsに渡すハンドラ、レスポンスのヘッダだけを設定するハンドラ、Nginx.return Nginx::HTTP_OKか、201と204以外の200から299のステータスで終わるハンドラです。3.0.0では、これらはContent-Length: 0とともにそのステータスで答えます。ステータスを設定していなければ200です。2.7.1では、500で答えていました。500に頼っていたハンドラは、意図するステータスを設定してください。body = Nginx::Request.new.headers_in["X-Answer"].to_sNginx.rputs body # body "": 2.7.1 answers 500 3.0.0 answers 200 with Content-Length: 0if body.empty?Nginx.return Nginx::HTTP_NOT_FOUND # 404 on bothelseNginx.rputs bodyend -
空のボディで終わる出力のボディフィルタが、接続を閉じずにレスポンスを送る:変えるものはありません。
Nginx::Filter#body=や#outputで""を設定するボディフィルタや、ボディの無いレスポンスのボディを空のままにするボディフィルタは、ステータスをContent-Length: 0とともに送ります。2.7.2までの2.xは、1バイトも送らずに接続を閉じていました。2.7.3も、このレスポンスを送ります。 -
Nginx::Varのアクセサが、ワーカーで最初に使われたときにNginx::Varのメソッドになる:上の検索でrespond_to?、method_defined?、instance_methods、methodsが見つかります。そのうち、Nginx::VarのインスタンスかNginx::Varそのものに対するものを見てください。変数についての答えは、そのワーカーが前にその名前にアクセスしたかどうかで変わるようになりました。代わりにexist?を使ってください。v = Nginx::Var.newv.respond_to?(:request_method) # 2.x: false 3.0.0: true after the first v.request_method in the workerv.exist?("request_method") # true on bothスクリプトが
ObjectやKernelに定義したメソッドのうち、スクリプトがv.NAMEで読む変数と同じ名前のものも探してください。たとえば、ハンドラのコードのトップレベルのdefで定義したメソッドです。ワーカーに変数のアクセサができると、v.NAMEはそのメソッドを呼ばずに変数を読みます。そのメソッドの名前を変えてください。検索はmethod_missingも見つけます。Nginx::Var#method_missingをラップするスクリプトは、アクセサができる名前について、最初のアクセスしか見ません。たとえば、Nginx::Varにprependしたモジュールのmethod_missingがsuperを呼ぶ場合です。ラッパーがしていたことは、変数を読むコードへ移してください。 -
Nginx::Connection、Nginx::Server、Nginx::Requestが、Nginx::Varを呼ばずに変数を読む:スクリプトがNginx::Varに定義したメソッドを探してください。class Nginx::Var、Nginx::Var.class_eval、define_methodによる定義と、上の検索で見つかるiv_varです。Nginx::Varのメソッドを変えても、Nginx::Connection#remote_ipやエントリーにあるほかのメソッドの戻り値は、もう変わりません。代わりに、Nginx::Connectionのような、そのメソッドを持つクラスにメソッドを定義してください。定義は、nginxが設定を読むときに1回だけ動くmruby_init_codeに書きます。ハンドラのコードは、同じmrb_stateの中でリクエストのたびに動きます。そのため、ハンドラのコードに書くと、2回目のalias_methodでnginx_remote_ipが新しいremote_ipのコピーになり、それが自分自身を呼ぶことになります。mruby_init_code 'class Nginx::Connectionalias_method :nginx_remote_ip, :remote_ipdef remote_ipNginx::Request.new.headers_in["X-Real-IP"] || nginx_remote_ip # works on bothendend'; -
Dirをmrubyのコアgemが定義するようになり、閉じたDirがRuntimeErrorでなくIOErrorを出す:上の検索で、RuntimeErrorが見つかります。そのうち、閉じることのあるDirか、Dirを閉じるブロックを付けたDir.openの例外をrescueしているものを見てください。d = Dir.open(path)d.closebegind.readrescue RuntimeError # 2.x: rescued 3.0.0: not rescued (IOError)endbegind.readrescue IOError, RuntimeError # rescued on bothend -
ENVをmrubyのコアgemが定義するようになり、ENV.to_hashが無くなり、ENVがEnumerableになる、Processをmrubyのコアgemが定義するようになり、Process.fork、Kernel#fork、Kernel#systemが無くなる、ハンドラの中のexitが、ワーカープロセスを終わらせずにSystemExitを出す、引数なしのsleepがArgumentErrorを出す、既定のビルドが、mruby-vedisのVedisとmruby-localmemcacheのCacheを含まなくなる:次のコマンドで、挙動の変わる呼び出しを探します。grep -rnE 'to_hash|fork|system|to_int|Status\.new|exit!|(^|[^_.])exit|sleep *($|[;)}])|Vedis|Cache\.new' /path/to/scriptsENV.to_hash # 3.0.0: NoMethodErrorENV.to_h # 3.0.0: the Hash 2.x: NoMethodErrorENV.keys.each_with_object({}) { |k, h| h[k] = ENV[k] } # the Hash on bothexit # 2.x: ends the worker process 3.0.0: SystemExit, the handler answers 500Nginx.return Nginx::HTTP_SERVICE_UNAVAILABLE # 503 on both; the code then runs to its endsleep # 2.x: waits until a signal comes 3.0.0: ArgumentErrorforkとsystemを使う処理は、ほかのプロセスをnginxの外で起動する形に変えてください。VedisとCacheのデータは、Redisか自分で用意したストアに置くか、build_config.rbのそのgemの行のコメントを外してください。 -
DigestとSecureRandomを、OpenSSL 3.0以降が要るngx_mrubyのgemが定義する:次のコマンドで、結果の変わる呼び出しを探します。見るのは、Digestのオブジェクトのdupとclone、digestかhexdigestを2回以上呼ぶHMACのオブジェクト、引数を渡すurlsafe_base64です。grep -rnE 'Digest::|\.dup|\.clone|urlsafe_base64|random_bytes' /path/to/scriptsd = Digest::SHA256.new.update("ab")d.dup.update("c").hexdigest # 2.x: the SHA-256 of "c" 3.0.0: the SHA-256 of "abc"Digest::SHA256.new.update("c").hexdigest # the SHA-256 of "c" on bothSecureRandom.urlsafe_base64(32).size # 2.x: 22 3.0.0: 43SecureRandom.urlsafe_base64.size # 22 on both -
Nginx::Upstream#server=とNginx::Stream::Connection#upstream_server=が、serverにできない文字列にArgumentErrorを出す:上の検索は、2つのsetterとRuntimeErrorを見つけます。そのうち、setterの例外をrescueする箇所を見てください。u = Nginx::Upstream.new "backend"beginu.server = "192.0.2.1:notaport"rescue RuntimeError # 2.x: rescued 3.0.0: not rescued (ArgumentError)endbeginu.server = "192.0.2.1:notaport"rescue ArgumentError, RuntimeError # rescued on bothend -
Nginx::Upstream#server=が、ホスト名を名前解決せずにArgumentErrorを出す:上の検索は、このsetterを見つけます。スクリプトがsetterに渡す値を見てください。リクエストやファイルから読む値も確かめてください。u.server = "localhost:8080" # 2.x: resolved while the worker waits 3.0.0: ArgumentErroru.server = "127.0.0.1:8080" # works on bothIPv4アドレスは4つの10進数で書いてください。
127.1も例外になります。nginxの動作中に変わらない名前は、upstream {}ブロックのserverの行に書き、setterを呼ばないでください。nginxは、この名前のすべてのアドレスを使います。アドレスが2つ以上あると、Nginx::Upstream.newはそのupstreamにRuntimeErrorを出すので、その呼び出しも削除するか、serverの行にIPアドレスを書いてください。解決できない名前があると、nginxは起動しません。 -
既定のビルドからauto-sslのmrbgemと、それに伴うクラスが無くなる:次のコマンドでデフォルトのビルドに無くなった定数と
Dirの2つのメソッドを探します。grep -rnE 'Nginx::SSL::ACME|Acme|HttpRequest|OpenSSL|PolarSSL|SimpleHttp|(^|[^:])HTTP::|Base64|Forwardable|FORWARDABLE|Tempfile|tmpdir' /path/to/scriptsBase64、Dir.tmpdir、Dir.mktmpdirには、デフォルトのビルドで使える代わりがあります。Base64.encode(s) # 3.0.0: NameError (uninitialized constant Base64)[s].pack('m0') # the same string on bothBase64.decode(b) # 3.0.0: NameErrorb.unpack1('m') # the same string on bothDir.tmpdir # 3.0.0: NoMethodErrorENV['TMPDIR'] || '/tmp' # works on bothDir.mktmpdirの代替は、auto-sslのmrbgemと、それと一緒に入っていたクラスにあります。ほかの定数に必要なgemはconf.gemで追加します。 -
Nginx::Async.sleepで待つaccessハンドラとpost_readハンドラが、待たないときと同じように終わる:mruby_access_handler*とmruby_post_read_handler*のコードでNginx::Async.sleepを探してください。satisfy anyでは、sleepの後に結果なしで終わるaccessハンドラが、リクエストを許可します。拒むべきハンドラは、sleepの後にステータスを返してください。Nginx::Async.sleep 100# 2.x: without a result, the request reached its content and the connection closed# 3.0.0: without a result, nginx allows the request under satisfy anyNginx.return Nginx::HTTP_FORBIDDEN unless allowed? # on both: denies under satisfy all; under satisfy any nginx tries the other access handlers -
出力を書くaccessハンドラとpost_readハンドラが、レスポンスの後にリクエストを終える:変えるものはありません。このハンドラは1回だけ応答し、nginxは接続を保ちます。2.xはフェーズを続けて接続を閉じていました。このハンドラが出していた
header already sentの行に対するログのアラートは、もう発生しません。 -
結果を設定しないハンドラが、前のハンドラの結果を引き継がない:すべてのリクエストで
Nginx.returnを呼ぶserver rewrite、rewrite、post_read、accessのハンドラを探してください。例えばmruby_server_rewrite_handler_code 'Nginx.return Nginx::DECLINED'です。出力もステータスも無く終わることのある後のcontentハンドラと、satisfy anyで結果なしで終わることのあるaccessハンドラは、この値を引き継がなくなります。先へ進むべきハンドラは、自分でその値を返してください。# mruby_content_handler_code, on a server whose server rewrite handler returns Nginx::DECLINEDNginx.rputs body if body # no body: 2.x went on to the static module 3.0.0 answers 200 with Content-Length: 0Nginx.return Nginx::DECLINED unless body # goes on to the static module on both -
Nginx::Async.sleepで待つmruby_setのハンドラが変数を設定し、リクエストが先へ進む:mruby_setとmruby_set_codeでNginx::Async.sleepを探してください。sleepの後にNginx.returnでリクエストを終えていたコードは、そのステータスを後のハンドラから返してください。例えば、変数を読むrewriteハンドラから返します。 -
結果なしで終わるrewriteハンドラとserver rewriteハンドラが、次のフェーズのハンドラへ進む:
Nginx.return無しかNginx.return Nginx::OKで終わることのあるmruby_rewrite_handler*とmruby_server_rewrite_handler*のハンドラを見てください。2.xでは、nginxはこのリクエストに応答せずに終えていました。3.0.0では、リクエストはlocationのcontentへ進みます。リクエストを終えるハンドラは、意図するステータスを返してください。# mruby_rewrite_handler_codeNginx::Var.new.set "backend", "a" # no result: 2.x sends no response 3.0.0 goes onNginx.return Nginx::HTTP_FORBIDDEN if deny # 403 on both -
Nginx::Async::HTTP.sub_requestがcontentハンドラで、Nginx::Async.sleepの後でも動く:mruby_content_handler*のコードで、sub_requestの周りのRuntimeErrorのrescueを探して削除してください。呼び出しはレスポンスを返します。Nginx::Async.sleep 100res = Nginx::Async::HTTP.sub_request "/backend" # 2.7.3: RuntimeError, 500 3.0.0: the responseNginx.rputs res.body -
Nginx::Async::HTTP.sub_requestで待つハンドラが、コードを1回だけ実行し、待たないときと同じように終わる:ほとんどのスクリプトでは、変えるものはありません。3.0.0では、sub_requestを呼ぶaccessハンドラとpost_readハンドラは、リクエストにつき1回だけ動きます。サブリクエストの後にコードがもう一度動くことに頼っていた処理は、サブリクエストのレスポンスを使える呼び出しの後に書いてください。 -
UDPのstreamのセッションがコードを1回だけ実行し、コードが待っている間に届いたデータグラムでは始め直さない:
listen ... udpのサーバーのコードでNginx::Stream::Async.sleepを探してください。3.0.0では、コードはセッションにつき1回だけ動き、sleepの間に届いたデータグラムでは始め直しません。 -
worker_shutdown_timeoutが切れたときに待っているstreamのセッションが、そこで終わる:変えるものはありません。worker_shutdown_timeoutがある設定で、タイムアウトが切れたときにまだsleepしているstreamのセッションは、sleepの後のコードを実行せずに終わります。 -
ローカルのURIへの
Nginx.redirectが、ハンドラが終わったときに効く:ハンドラで、パスを渡すNginx.redirectを探してください。3.0.0では、呼び出しの後のコードがリダイレクト先より先に動き、書いた出力と設定したステータスはクライアントへ送られません。そのコードが設定したレスポンスのヘッダと、変えたリクエストの引数は、リダイレクト先に届きます。Nginx.redirect "/backend"Nginx.rputs "fallback" # 2.x: sent with the answer of /backend 3.0.0: not sent, warn linereturn # leave the handler when the code after the call should not run -
引数の
to_sがString以外を返すと、Nginx.rputs、Nginx.echo、Nginx.redirect、Nginx::Filter#body=がTypeErrorを出す:これらのメソッドとNginx::Filter#outputに、Stringでない引数を渡す呼び出しを探してください。その引数は、String、nil、to_sがStringを返す値のどれかに替えてください。 -
mruby_setのハンドラではNginx::Async::HTTP.sub_requestがRuntimeErrorを出す:mruby_setとmruby_set_codeで、Nginx::Async::HTTP.sub_requestを探してください。サブリクエストを待てるrewriteかaccessのハンドラで呼び、Nginx::Var#setで変数を設定してください。 -
mruby_setの値をStringに変換できないと500で応答する:コードがString以外の値を返しうるmruby_setとmruby_set_codeを探し、Stringを返すようにしてください。 -
logハンドラでは、ローカルのURIへの
Nginx.redirectがRuntimeErrorを出す:mruby_log_handlerとmruby_log_handler_codeのコードで、パスを渡すNginx.redirectを探し、その呼び出しをrewrite、access、contentのどれかのハンドラへ移してください。 -
ハンドラが設定したステータスで出力を送り、
error_pageは効かない:ハンドラのコードで、Nginx.rputsかNginx.echoの前と後に呼ぶNginx.return、Nginx.send_header、Nginx.status_code=を探してください。そのハンドラのロケーションにあるerror_pageも探してください。3.0.0では出力をそのステータスで送り、そのステータスのerror_pageは効きません。# 2.x: nginx's 401 page, or the page of an error_page for 401 3.0.0: 401 with the JSONNginx.rputs '{"error":"no key"}'Nginx.return Nginx::HTTP_UNAUTHORIZEDNginx.rputsが無ければ、どちらのバージョンもnginxの401のページか、error_pageのページを返します。nginxのページやerror_pageに頼っていたハンドラは、出力を書かずにステータスを設定してください。出力の後に301、302、303、307、308を設定したとき、Locationは、スクリプトがNginx::Headers_outで設定した場合だけ付きます。出力の後の200未満のステータスでは500を返します。最初の出力の前に設定したステータスにも、3.0.0では同じ規則を当てます。2.xは出力を200で送りました。200で送るつもりのハンドラは、出力の後にNginx.return Nginx::HTTP_OKを呼び、ステータスを200に戻してください。Nginx::HTTP_CLOSE(444)では、出力の前でも後でも何も送らずに接続を閉じます。出力の後の444は2.xと同じです。2.xは、444の後に書いた出力を200で送りました。 -
ハンドラで効果の無いメソッドは、そのハンドラで
RuntimeErrorを出す:mruby_log_handler*、mruby_output_header_filter*、mruby_output_body_filter*、mruby_set、mruby_set_codeのコードで、下の一覧の「新しく例外を出す場所」にあたるメソッドを探してください。2.xではレスポンスに影響せずに戻ったこれらの呼び出しが、3.0.0では、メソッドとハンドラを名前で示すRuntimeErrorを出します。呼び出しを消すか、「動く場所」のハンドラへ移してください。フェーズのハンドラは、post_read、server rewrite、rewrite、access、contentのハンドラを指します。- リクエストを読む
Nginx::Requestのgetter、Nginx::Headers_in#[]、Nginx::Varの読み出し、Nginx::Connection、Nginx::Serverのgetter:動く場所は、リクエストのすべてのハンドラとフィルタです。新しく例外を出す場所はありません。 - リクエストを変える
uri=、args=、method=、request_line=、Nginx::Headers_in#[]=と#delete:動く場所は、mruby_setのハンドラとフェーズのハンドラです。新しく例外を出す場所は、logハンドラ、ヘッダフィルタ、ボディフィルタです。 - 変数に代入する
Nginx::Var#NAME=と#set:動く場所は、リクエストのすべてのハンドラとフィルタです。新しく例外を出す場所はありません。 - レスポンスのヘッダを変える
Nginx::Headers_out#[]=と#delete、Nginx.status_code=、ステータスを渡したNginx.returnとNginx.send_header、content_type=:動く場所は、logハンドラを除くリクエストのすべてのハンドラとフィルタで、nginxがレスポンスのヘッダを送るまでです。新しく例外を出す場所は、logハンドラと、nginxがレスポンスのヘッダを送った後に動くほかのハンドラです。 - 出力を書く
Nginx.rputsとNginx.echo:動く場所は、フェーズのハンドラとボディフィルタです。新しく例外を出す場所は、mruby_setのハンドラ、logハンドラ、ヘッダフィルタです。 - ボディフィルタのボディを扱う
Nginx::Filter#body、#body=、#output:動く場所は、ボディフィルタです。新しく例外を出すのは、ほかのハンドラの#bodyです。#body=と#outputは、前から例外を出していました。
access_logへ値を渡すlogハンドラは、logハンドラでも動くNginx::Varで変数に代入してください。# in mruby_log_handler_codeNginx::Request.new.headers_out["X-Cost"] = cost # 2.x: no effect 3.0.0: RuntimeErrorNginx::Var.new.cost = cost.to_s # both: access_log writes $cost - リクエストを読む
-
mruby_setのハンドラと出力フィルタでは、ローカルのURIへのNginx.redirectがRuntimeErrorを出す:mruby_set、mruby_set_code、mruby_output_header_filter*、mruby_output_body_filter*のコードで、パスを渡したNginx.redirectを探してください。2.xでは呼び出しの中でリダイレクト先のロケーションのハンドラが動きましたが、3.0.0では呼び出しがRuntimeErrorを出し、内部リダイレクトをしません。呼び出しは、rewriteかaccessのハンドラへ移してください。そこでは、ハンドラが終わったときにリダイレクトが効きます。# in mruby_set_code: 2.x: the redirect runs inside the call 3.0.0: RuntimeError, the variable is emptyNginx.redirect "/backend"# in mruby_rewrite_handler_code: the redirect takes effect when the handler ends, on 3.0.0Nginx.redirect "/backend" -
nginxが知らない変数と、スクリプトからの変更を許さない変数への代入が例外を出す:
Nginx::Varによる代入(v.<name> =とset)を探してください。2.xのサーバーのerror.logにある、ngx_mrb_var_set_vectorとngx_mrb_var_set_funcのis not found、not changeable、is not assingedというerrorの行も探してください。これらの行には、代入が届かなかった変数の名前が書いてあります。2.xでは、このような代入は行をログに書いてnilを返し、処理を続けました。3.0.0では、nginxが知らない名前への代入はNameErrorを出し、スクリプトからの変更をnginxが許さない変数と、nginxが値を持たない変数への代入はRuntimeErrorを出します。変数をsetかmruby_variableで宣言するか、Nginx::RequestとNginx::Headers_inのセッターでリクエストを変えてください。v = Nginx::Var.newv.backend_url = "http://10.0.0.2/" # no set or mruby_variable declares $backend_url: 2.x: nil and an error line 3.0.0: NameErrorv.uri = "/other" # 2.x: nil and an error line 3.0.0: RuntimeErrorNginx::Request.new.uri = "/other" # changes the URI on both
Dir.children、Dir#each_child、Dir.empty?と、Dirに対するEnumerableのメソッドは、2.xのスクリプトには新しいものです。最初の2つは.と..を含みません。詳しくは新機能にあります。
-
Exception#inspectの形式が変わり、error.logのmrb_run failedの行も変わる:ログのパーサとアラートのルールで、mrb_run failedの行に対するパターンと、行の最後にある括弧の中の例外のクラスを探してください。2.x: mrb_run failed: return 500 HTTP status code to client: error: boom (RuntimeError)3.0.0: mrb_run failed: return 500 HTTP status code to client: error: #<RuntimeError: boom>\(RuntimeError\)$のようなパターンは、#<RuntimeError:に書き換えます。 -
NoMethodErrorのメッセージがレシーバのクラスを示す:メッセージの後にfor <class>が続くので、undefined method 'foo'で終わるパターンはもう一致しなくなりました。 -
nginxが設定を読む間のメッセージのレベルが
noticeからinfoになる:ログのパーサ、アラートのルール、起動のスクリプトで、mechanism enabled、compile info、target variable、ngx_mruby NOTICEを探してください。nginxは、起動しても、もうこれらの行を書きません。nginx -tは、これらを[info]で起動時のログに書きます。起動時のログは-eで指定したファイルで、指定しなければnginxに組み込んだエラーログのパスです。デフォルトでは、プレフィックスの下のlogs/error.logです。nginxが起動時のログの行を端末にも出すのはwarn以上だけなので、nginx -tの出力にはこれらの行が出ません。2.x, start: [notice] ... ngx_mruby/<version> (mruby/3.3.0) mechanism enabled in ...3.0.0, start: no such line3.0.0, nginx -t: [info] ... ngx_mruby/<version> (mruby/4.1.0) mechanism enabled in ... (startup log only)3.0.0, nginx -t -e stderr: [info] ... ngx_mruby/<version> (mruby/4.1.0) mechanism enabled in ... (terminal)モジュールが読み込まれたことをこれらの行で確かめるには、
nginx -t -e stderrを実行してその出力を読むか、nginx -tの後に起動時のログを読んでください。nginx -t -e stderr 2>&1 | grep 'mechanism enabled' -
Nginx.module_versionとmechanism enabledの行が3.0.0を示す:スクリプトでNginx.module_versionを探し、ログのパーサとアラートのルールで、ngx_mruby/の後のバージョンに対するパターンを探してください。2.7.1のような2.xのバージョンとの比較や、ngx_mruby/2\.のようなパターンは、もう一致しません。3.0.0とそのプレリリースは3.0.0を示します。 -
構文エラーのメッセージがPrismのものになる:
unexpected end of fileのような、syntax errorの後の文面に対するパターンは、もう一致しません。SyntaxErrorと、ファイルの名前と行に一致させてください。2.x: file (eval) line 1: syntax error, unexpected end of file3.0.0: file (eval) line 1: syntax error, unexpected end-of-input; expected an expression after the operator -
出力なしで終わるcontentハンドラが、500でなく、空のボディの200で応答する:
response body is empty. return NGX_HTTP_INTERNAL_SERVER_ERRORに対するパターンは、メインのリクエストのcontentハンドラが出力なしで終わり、ステータスを設定していないか、nginxが自分では答えない200から299のステータスを設定しているときには、もう一致しません。200未満のステータスと、ほかのハンドラとサブリクエストで出力なしのNginx::HTTP_OKには、今も一致しています。 -
空のボディで終わる出力のボディフィルタが、接続を閉じずにレスポンスを送る:nginxがこれらのレスポンスを送るので、
zero size buf in writerのアラートは、もう出ません。 -
access_logが、mrubyのlogハンドラが設定した変数と、送ったステータスを書く:mruby_log_handlerとmruby_log_handler_codeのディレクティブを探し、そのコードがNginx::Varで代入する変数を探してください。代入はv.NAME = ...とv.set "NAME", ...の形です。次に、それらの変数を書くlog_formatの行を探してください。これらの行には、logハンドラが動く前の値でなく、logハンドラが代入した値が入るようになります。logハンドラが動く前の値を残したい行では、ロケーションでsetが作ったコピーを書いてください。setはlogのフェーズより前に動きます。set $tokens "-";set $tokens_before_log $tokens;アクセスログの行のステータスは、logハンドラが例外を出した後も、送ったステータスです。ngx_mrubyは、その例外の
mrb_run failedの行を、これまでどおりerror.logに書きます。
C拡張とmrbgems
Section titled “C拡張とmrbgems”次のコマンドは、gemのCのソースや、mrubyを組み込むプログラムのCのソースで、下のエントリーが扱う箇所を探します。
grep -rnE 'Data_Wrap_Struct|mrb_data_object_alloc|MRB_SET_INSTANCE_TT|MRB_ARGS_|mruby/ext/io\.h|mrb_alloca|mrb_open|allocf|MRB_NO_PRESYM' src/-
C拡張:
MRB_TT_DATAと宣言していないクラスのオブジェクトでは、Cのデータをラップできない:Data_Wrap_Structやmrb_data_object_allocがオブジェクトを作るクラスには、どれもmrb_define_classの後にこの宣言が要ります。struct RClass *c = mrb_define_class(mrb, "Uname", mrb->object_class);MRB_SET_INSTANCE_TT(c, MRB_TT_DATA); -
C拡張:mrubyが、Cのメソッドに渡す引数の数を引数仕様で検査する:各
mrb_define_methodの引数の仕様と、そのmrb_get_argsが読むものを、両方向で比べてください。MRB_ARGS_REQ(2)で定義し、mrb_get_args(mrb, "S", &s)で文字列を1つ読み、引数1つで呼ばれるメソッドは、ArgumentErrorを起こします。このメソッドは、MRB_ARGS_REQ(1)で定義してください。MRB_ARGS_REQ(1)で定義し、"o|o"を読み、引数2つで呼ばれるメソッドも例外を起こします。このメソッドはMRB_ARGS_ARG(1, 1)で定義してください。 -
C拡張:ヘッダと関数の名前が変わり、失敗したときの
mrb_open()の戻り値が変わる:例を示します。#include <mruby/io.h> /* was <mruby/ext/io.h> */void *buf = mrb_temp_alloc(mrb, size); /* was mrb_alloca(mrb, size) */mrb_state *mrb = mrb_open(); /* also in place of mrb_open_allocf(my_allocf, ud) */if (MRB_OPEN_FAILURE(mrb)) { /* ... */ } /* was: if (mrb == NULL) *//* a custom allocator, in place of mrb_default_allocf() or my_allocf */void *mrb_basic_alloc_func(void *ptr, size_t size) { /* ... */ } -
C拡張:
mruby.hをインクルードするソースに、生成されたヘッダが必要になる:そのようなソースをmrubyのビルドの外でコンパイルするところでは、-I<mruby>/includeの隣に-I<mruby>/build/host/includeを加えてください。
結果を確かめる
Section titled “結果を確かめる”-
すべてのスクリプトを、mruby 4.1.0-rc2の
mrbcでコンパイルします。このリリースをsh build.shかsh test.shでビルドした後なら、mruby/bin/mrbc -cでスクリプトの構文を確かめられます。mrbc -cはSyntax OKを出力するか、エラーの行を出力して終了ステータス1で終わります。メソッドの本体で定数に代入したときのエラーの行は、<file>:2:3: syntax error, dynamic constant assignmentです。for f in /path/to/scripts/*.rb; do mruby/bin/mrbc -c "$f" || echo "check: $f"; done -
スクリプトのうち
Nginxのクラスを呼ばない部分を、両方のバージョンのmrubyで実行します。mruby 4.0.0のエントリーは、2026年10月4日から10月14日の間に、この方法で測りました。同じRubyのスクリプトを2つのmrubyのバイナリで実行しました。1つはngx_mruby 2.xに同梱のmruby 3.3.0から、もう1つは、mruby 4.0.0からビルドしたものです。どちらもUbuntu 22.04とgcc 11を使うDockerのコンテナの中でビルドし、mrubyのdefaultのgemboxか、各バージョンのngx_mrubyのビルドのコアのgemを使いました。コアのgemは、3.3.0ではfull-coreとiij/mruby-dir、4.0.0ではNGX_MRUBY_CORE_GEMSです。mruby 4.1.0-rc2のエントリーは、2026年10月29日と10月31日に測りました。使ったのは、ngx_mrubyのhostのビルドが4.0.0と4.1.0-rc2で作ったmrubyコマンドと、mruby 3.3.0をdefaultのgemboxでビルドしたmrubyコマンドです。「ngx_mrubyのテストスイートでもこの変化が出ました」と書いたエントリーは、ngx_mruby自身のレスポンスかログの行も変わったものです。同じことをするには、各バージョンのmruby/ディレクトリを別々のディレクトリにコピーし、それぞれでrake MRUBY_CONFIG=defaultを実行して、両方のbin/mrubyでスクリプトを実行します。rakeはmruby/buildにビルドし、そこにはモジュールのビルドが使うmrubyがあります。そのため、このrakeをngx_mrubyのチェックアウトのmruby/で実行しないでください。 -
テスト用のサーバに、このリリースのモジュールと設定を入れて動かし、各ハンドラに届くリクエストを送ります。そして、
error.logで、NoMethodError、TypeError、ArgumentError、SyntaxErrorを含むmrb_run failedの行を探します。
次のものは同じ方法で確かめて変わっていなかったので、確かめる必要はありません。String#sizeと#lengthはバイトを数えます。mruby-encodingのgemはデフォルトのビルドに入っていません。詳しくはコアのgemにあります。ほかに、引数の数が違うときのArgumentError、Exception#message、Struct#inspect、Float#to_s、Integerの除算と剰余、mruby-sleepのKernel#sleepと#usleepも変わっていません。