Skip to content
These are 2.x maintenance-branch docs. Latest release tag: v2.7.12. Check the version targeted by each example. For development, read the 3.x documentation.

ngx_mruby v2.7.9

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)

Section titled “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)

Section titled “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.

None.

  • Nginx::Upstream#server, #server=, #keepalive_cache, #keepalive_cache= and Nginx::Stream::Connection#upstream_server and #upstream_server= raise ArgumentError on an object whose initialize raised, that came from allocate, or that dup or clone made. Before, they returned nil or read through a NULL pointer and ended the worker process (#816, #819)
  • Nginx::Upstream.new and Nginx::Stream::Connection.new free the memory of the new object’s context when they raise for an upstream with more than one server. Before, each such call left that memory allocated until the worker exited (#816)
  • New test case: test/t/cases/upstream_uninitialized.rb, with the server of test/conf/conf.d/97-upstream-uninitialized.conf on port 18093 and the stream server of test/conf/conf.d/stream/53-upstream-uninitialized.conf on port 12397 (#816)
  • test/t/cases/upstream_uninitialized.rb also calls the upstream methods on copies made with dup and clone of an object that .new returned, on the HTTP and stream servers of the existing cases, checks that they raise ArgumentError, and checks that the original object keeps its upstream (#819)
  • The server of test/conf/conf.d/96-argument-types.conf, which test/t/cases/argument_types.rb tests, moved from port 18200 to 18092, the port it has on next. A new test case takes a port that is free on both master and next, from 18080 to 18199 for HTTP and from 12345 to 12399 for stream; AGENTS.md and docs/test/README.md say so (#819)
  • worker_connections of the test nginx (test/conf/nginx.conf) is 1024 instead of 200, the value of next. nginx counts each listening socket as one of the worker’s connections. The test nginx of master listens on 89 sockets (87 TCP and 2 UDP) and passes with 200; that of next listens on 125, and under valgrind the connections that test/t/cases/_wait_for_listen.rb opens to each port at the start used up the rest of the 200. With the same value, the line no longer differs between the branches (#819)
  • test/t/cases/module_and_request.rb checks that MODULE_VERSION in src/http/ngx_http_mruby_module.h is the newest version among the files docs/releases/vX.Y.Z.md, compared as numbers. The pull request that creates the release file of a new version sets MODULE_VERSION to that version in the same pull request; otherwise the suite fails (#822)
  • No directive was added, renamed or removed. Rebuild the module with this release the way you built 2.7.8, and replace the binary or the dynamic module as usual. Nginx.module_version returns 2.7.9.

Check these before upgrading. Each line is the “What to do” of its entry above.

  • Scripts that keep using an Nginx::Upstream or Nginx::Stream::Connection object after its initialize raised, or that use a copy made with dup or clone: create the object with .new, and do not use it when the call raises; create a second object with .new instead of a copy.
  • Scripts and monitoring that compare Nginx.module_version, or the line of error.log that starts with ngx_mruby/ and contains mechanism enabled, with 2.7.1: compare with 2.7.9, or with the version of the release that you run; tell 2.7.2 to 2.7.8 apart by the release tag or the commit, not by this value.