ngx_mruby v2.7.5
Behavior changes: read before upgrading
Section titled “Behavior changes: read before upgrading”A rewrite or access handler that returns Nginx::DECLINED after Nginx::Async.sleep no longer makes a later handler answer 500 (#740)
Section titled “A rewrite or access handler that returns Nginx::DECLINED after Nginx::Async.sleep no longer makes a later handler answer 500 (#740)”- Before: when a rewrite handler (
mruby_rewrite_handler,mruby_rewrite_handler_code) or an access handler (mruby_access_handler,mruby_access_handler_code) returnedNginx::DECLINEDwithNginx.returnafterNginx::Async.sleep, the request went on to the next phase with its status set to 500. A later mruby handler of the request that set no status and wrote no output then answered 500: for example an access handler after the rewrite handler, also in a location that serves a static file, or a content handler without output after the access handler. Without such a later mruby handler, nginx answered as usual, because its own handlers set their status: a static file was served with 200. - Now: the request goes on to the next phase as it does when the handler declines without a sleep, and a later mruby handler that sets no status answers as it does then, not with 500: after a rewrite handler, the content handler answers with its output, and nginx serves the static file of the location with 200.
- Why it changed:
- The defect: the code that resumes a handler after its sleep set the status of the request to 500 for every result other than
Nginx::OK, also forNginx::DECLINED, with which the request goes on. This was reported by mail. - Why the old behavior could not be kept: a handler declines to let the later handlers answer; the 500 that it left made them answer an error that no handler had set.
- What the documentation promised: Nginx::
Async of 2.7.4 said that the sleep is supported in rewrite and access handlers, and said nothing about a status after it.#sleep
- The defect: the code that resumes a handler after its sleep set the status of the request to 500 for every result other than
- Affected: rewrite and access handlers that call
Nginx::Async.sleepand then returnNginx::DECLINED, in locations where a later mruby handler of the request sets no status and writes no output. - What to do: nothing. A configuration that relied on the 500 returns that status from a handler with
Nginx.return.
A HEAD response with an output body filter keeps its connection available (#752)
Section titled “A HEAD response with an output body filter keeps its connection available (#752)”- Before: a HEAD request to a location with
mruby_output_body_filterormruby_output_body_filter_code, whose response had a known content length, received its response headers, but nginx then closed the connection even when the headers advertised keep-alive. A following GET on that connection received no response. This occurred with both empty and nonempty replacement bodies. - Now: for those responses, after the HEAD headers are sent successfully, the filter sends no body bytes and leaves an otherwise reusable connection available for the next request. GET responses, other header-only responses and header-filter errors keep their behavior.
- Why it changed:
- The defect: the body-filter finalizer returned
NGX_ERRORafter a successful header-only response. nginx treated that return as an output error and closed the connection. The review of #574 recorded the HEAD case, and the review of #628 confirmed it with a following GET. - Why the old behavior could not be kept: a successfully sent HEAD response did not represent an output error, and closing the connection prevented the next request advertised by keep-alive.
- What the documentation promised: Nginx::
Filter described replacement bodies and their content length, but did not describe a HEAD connection-close exception.#body=
- The defect: the body-filter finalizer returned
- Affected: HEAD responses with a known content length that are finalized by an mruby output body filter, when the connection can otherwise be kept alive.
- What to do: nothing. To close a connection deliberately, configure nginx’s keep-alive policy rather than relying on this filter error.
A UDP session keeps its pending stream handler when more datagrams arrive
Section titled “A UDP session keeps its pending stream handler when more datagrams arrive”Security advisory: GHSA-wx6w-gpg3-cmc3.
- Before: each datagram received from the same client while a UDP stream handler slept started the code again and replaced the pending sleep timer. Only the most recently started code resumed after that timer; later datagrams moved the wait’s deadline.
- Now: later datagrams leave the waiting handler and its current deadline in place. Its code resumes once for each sleep it requested. The first datagram remains available to the next phase. As before, payloads of later datagrams received during the wait are discarded, not queued or replayed to
proxy_pass. After the code finishes and the session reachesproxy_pass, nginx forwards subsequent datagrams normally in that session.worker_shutdown_timeoutends a UDP session that is still waiting. - Why it changed:
- The defect: receiving another datagram replaced the pending invocation instead of letting that invocation complete its code after the sleep.
- Why the old behavior could not be kept: the code after the earlier sleep did not run, and its deadline depended on later datagrams rather than the requested delay. A session’s access handler cannot provide processing once for every datagram by starting overlapping waits.
- What the documentation promised: Nginx::
Stream:: explicitly said each UDP datagram during a sleep ran the code again. This release changes that documented behavior.Async #sleep in 2.7.4
- Affected: UDP servers whose
mruby_streamormruby_stream_codehandler callsNginx::Stream::Async.sleep, when another datagram of the same session arrives before the wait finishes. - What to do: use the stream handler for session-level decisions. Move processing that must run for every datagram to the upstream application. If every payload must arrive there, avoid sleeping in the UDP handler or arrange retransmission in the application protocol; payloads received during the wait are not replayed.
New features
Section titled “New features”None.
None.
Build and test changes
Section titled “Build and test changes”-
UDP stream wait coverage: bounded same-session datagrams, consecutive sleeps, exact binary payloads through a UDP echo upstream, a later exchange on the same proxy session, and worker shutdown while a session waits. The independent instance uses ports 12393-12396; the main case uses 12392.
-
CI: a pull request to
masterruns no job ofsite-v2.yml, which built the 2.x pages of the site with the pull request’sdocs/. Its author checks the 2.x pages locally: the relative links of the Markdown files withcheck_links.pyofnext, and the 2.x pages built from the pull request withNGX_MRUBY_V2_TREE=DIR npm run check:ciinsite/ofnext.site-v2.ymlruns only on “Run workflow”. Every push tomasterstill startssite.ymlonnextthroughsite-dispatch.yml, which builds and checks/v2/from the newmasterbefore it deploys the site. When the base of a pull request moves, CI runs again only when both the pull request and the new commits of the base change the code or the tests (condition 2 of “Review and merge” in AGENTS.md; “The 2.x pages of the site” in docs/test/README.md) (#739) -
New test case:
test/t/cases/async_rewrite_declined.rb, with the server oftest/conf/conf.d/82-async-rewrite-declined.confon port 18187 (#740) -
New regression case:
test/t/cases/head_body_filter.rbsends HEAD and then GET on one TCP connection, covering both output origins, an empty replacement and ordinary HEAD/GET controls (#752).
Upgrading
Section titled “Upgrading”- No directive was added, renamed or removed. Rebuild the module with this release the way you built 2.7.4, 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.
-
A rewrite or access handler that returns
Nginx::DECLINEDafterNginx::Async.sleep: nothing. A configuration that relied on the 500 returns that status from a handler withNginx.return. -
A UDP stream handler that calls
Nginx::Stream::Async.sleep: use it for session-level decisions, and move processing required for every datagram to the upstream application. If every payload must arrive there, avoid the sleep or arrange retransmission in the application protocol; payloads received during the wait are not replayed. -
HEAD responses with an mruby output body filter: nothing. To close a connection deliberately, configure nginx’s keep-alive policy rather than relying on this filter error.