Merge branch 'release/mod_wsgi-6.0.2'

Author: GrahamDumpleton

docs/configuration-directives/WSGIDaemonProcess.rst

@@ -769,20 +769,69 @@ Options which can be supplied to the ``WSGIDaemonProcess`` directive are:
 .. _response-buffer-size:
 
 **response-buffer-size=nnn**
-    Defines the maximum number of bytes that will be buffered for a
-    response in the Apache child processes when proxying the response body
-    from the WSGI application. The default size is 65536 bytes. Be careful
-    increasing this to provide extra buffering of responses as it
-    contributes to the runtime memory size of the Apache child processes.
+    Acts as a coarse upper bound, in bytes, on how much response content is
+    passed down the output filter chain without a flush when proxying a
+    response body from the WSGI application. If this many bytes are passed
+    without a flush occurring for another reason, a flush is forced. The
+    default is 8388608 bytes (8 MB), and if specified the value must be at
+    least 65536 bytes.
+
+    Its only purpose is to bound a downstream output filter that buffers
+    response data without draining it, capping such buffering to roughly
+    this many bytes per request. The Apache core output filter already
+    bounds normal in-memory buffering of the response in the Apache child
+    processes, so the default is set high and the guard does not affect
+    normal operation. Setting it low forces frequent flushes that can
+    interfere with a downstream pacing or batching output filter such as
+    ``mod_ratelimit`` (see ``response-flush-delay``), so it should only be
+    reduced if you specifically need to cap such a filter.
 
 .. _response-socket-timeout:
 
 **response-socket-timeout=nnn**
     Defines the maximum number of seconds allowed to pass before timing out
-    on a write operation back to the HTTP client when the response buffer
-    has filled and data is being forcibly flushed. Defaults to 0 seconds
-    indicating that it will default to the value of the ``socket-timeout``
-    option.
+    on a write operation back to the HTTP client when transferring the
+    response body. Defaults to 0 seconds indicating that it will default to
+    the value of the ``socket-timeout`` option.
+
+.. _response-flush-delay:
+
+**response-flush-delay=nnn**
+    Defines, in **milliseconds**, how long mod_wsgi will wait for further
+    response data to arrive from the daemon process before flushing the
+    data already read out to the HTTP client. Defaults to 5 milliseconds.
+
+    When proxying a response back from a daemon process, mod_wsgi reads the
+    data as it becomes available and would otherwise flush to the client
+    every time the daemon socket momentarily ran dry. During a bulk
+    transfer that emptying is usually just an artefact of timing, and
+    flushing on it defeats a downstream output filter that paces or batches
+    data, most notably ``mod_ratelimit`` (whose ``RATE_LIMIT`` filter is
+    forced to emit a short write on every flush and so throttles the
+    response far below the configured rate). Waiting a brief period for
+    more data lets mod_wsgi coalesce it into larger writes so such a filter
+    can do its job, while a genuinely idle application still has its partial
+    output flushed within the delay so streaming responses remain
+    responsive.
+
+    The default of 5 milliseconds is comfortably longer than the time it
+    takes the local daemon process to produce more data during an active
+    transfer, so it does not affect throughput, while bounding any extra
+    latency added to a paused streaming response to that same small value.
+
+    Setting the value to 0 disables the wait, so data is flushed on any
+    momentary stall. This is generally not recommended. In particular, do
+    not set it to 0 when a downstream pacing or batching output filter such
+    as ``mod_ratelimit`` is in use: doing so reintroduces a flush on every
+    momentary stall, which prevents such a filter from accumulating
+    full-size writes and can throttle responses far below the configured
+    rate. A value of 0 is only appropriate for latency-sensitive streaming
+    where no such filter is present and even a few milliseconds of flush
+    delay must be avoided.
+
+    Note that, unlike the various ``*-timeout`` options which are expressed
+    in seconds, this option is expressed in milliseconds because the useful
+    values are far smaller than one second.
 
 .. _server-metrics:
 

docs/configuration-directives/WSGISlowRequests.rst

@@ -27,6 +27,10 @@ Setting ``WSGISlowRequests`` without ``WSGITelemetryService`` is
 not treated as a configuration error: the per-request bookkeeping
 runs and the records are constructed, but nothing reads them.
 
+Note that, like the telemetry reporter it feeds, this directive is
+not available on Windows. See :doc:`WSGITelemetryService` for
+details.
+
 Each slow-request record carries:
 
 * The originating process PID and worker thread ID.

docs/configuration-directives/WSGITelemetryOptions.rst

@@ -16,6 +16,10 @@ This is a server-wide directive: it may only appear at the top
 level of the Apache configuration, outside any ``<VirtualHost>``
 block.
 
+Note that, like the telemetry reporter it configures, this directive
+is not available on Windows. See :doc:`WSGITelemetryService` for
+details.
+
 Syntax follows the Apache ``Options`` directive convention. Two
 argument forms are supported, and may not be mixed within one
 line:

docs/configuration-directives/WSGITelemetryService.rst

@@ -39,6 +39,14 @@ configuration line enables the reporter for the entire Apache
 instance, covering every daemon process group and every
 embedded-mode Apache child.
 
+Note that the telemetry reporter, and so the ``WSGITelemetryService``,
+:doc:`WSGISlowRequests` and :doc:`WSGITelemetryOptions` directives, are
+not available on Windows. The reporter delivers its datagrams over a
+UNIX ``SOCK_DGRAM`` socket, which Windows does not provide, so the
+feature is not built there and these directives are not registered.
+Using one of them on Windows is reported by Apache as an unknown
+directive.
+
 Arguments
 ---------
 

docs/error-reference.rst

@@ -5413,3 +5413,36 @@ WSGI0209 — Unable to publish 'process_signal' event for interpreter
    subscribers should be defensive about missed signals (idempotent
    reload, polling-based fallback) since signals are not
    refcounted and a dropped delivery is not redelivered.
+
+.. _WSGI0210:
+
+WSGI0210 — Embedded mode of mod_wsgi cannot be used as Python was not initialised
+---------------------------------------------------------------------------------
+
+:Severity: ERR
+:Source: ``src/server/mod_wsgi.c``
+
+:Logged message:
+   ``Embedded mode of mod_wsgi cannot be used as Python was not
+   initialised in this process.``
+
+:Cause:
+   A request reached the embedded-mode code path and embedded mode
+   was permitted, but no Python interpreter is available in this
+   Apache child process, so the per-thread state needed to run the
+   handler does not exist. This normally means the child was never
+   asked to initialise Python (for example a daemon-only
+   configuration), or initialisation was attempted but failed (see
+   :ref:`WSGI0001`).
+
+:Outcome:
+   The request returns ``500 Internal Server Error``. The check
+   exists so this condition is reported rather than crashing the
+   process by dereferencing the uninitialised per-thread state.
+
+:Operator action:
+   Route the request to a ``WSGIDaemonProcess`` via
+   ``WSGIProcessGroup``, or ensure embedded mode is configured so
+   Python is initialised in the Apache child processes. If
+   :ref:`WSGI0001` was logged at child start up, resolve that
+   initialisation failure first.

docs/index.rst

@@ -86,6 +86,7 @@ Where to start
    :maxdepth: 1
 
    troubleshooting
+   known-issues
    finding-help
    reporting-bugs
    contributing

docs/known-issues.rst

@@ -0,0 +1,80 @@
+============
+Known Issues
+============
+
+This page lists known issues in mod_wsgi itself: confirmed defects and
+accepted limitations in the module, as opposed to problems in your
+Apache configuration or your WSGI application. If you are still working
+out *where* a problem lives, start with :doc:`troubleshooting`; the
+guides it links to cover installation, configuration, and application
+problems, which are far more common than bugs in mod_wsgi.
+
+An issue is listed here when the behaviour is understood, there is
+nothing a user can do to make mod_wsgi behave differently beyond the
+noted workaround, and a full fix is either not yet available or not
+considered worthwhile. Each entry records the symptom, which mode of
+operation is affected, the underlying cause, any workaround, and the
+current status with a link to the tracking issue.
+
+If you are hitting something that is not listed here and not explained
+by :doc:`troubleshooting`, see :doc:`reporting-bugs`.
+
+.. _known-issue-chunked-truncation:
+
+Truncated chunked responses are not signalled to the client in daemon mode
+--------------------------------------------------------------------------
+
+**Symptom**
+
+A WSGI application streams a response with no ``Content-Length`` header,
+so it is sent to the client using ``Transfer-Encoding: chunked``. If the
+response is then cut short partway through, the client still receives a
+syntactically complete chunked response, terminated with the final
+``0`` chunk, and cannot tell that the body was truncated. The response
+is cut short when either:
+
+* the application raises an unhandled exception while iterating the
+  response, or
+* the daemon process handling the request dies mid-response (for
+  example, it is killed, crashes, or hits a resource limit).
+
+**Affected mode**
+
+Daemon mode only. In embedded mode this was addressed in version 4.4.0:
+when a chunked response is interrupted by an application exception,
+mod_wsgi suppresses the terminating ``0`` chunk so the client sees an
+unterminated response and can detect the truncation. Responses that do
+carry a ``Content-Length`` are not affected in either mode, because a
+client can already detect a short read against the declared length.
+
+**Cause**
+
+In daemon mode the response is produced in the daemon process and
+proxied back to the Apache child process over a socket, with the chunked
+framing toward the client applied by the Apache child. The response leg
+between daemon and child is an unframed byte stream whose end is
+signalled only by the socket closing, so a clean completion, an
+application exception, and an outright crash all look identical to the
+Apache child. The child then terminates the chunked response toward the
+client normally. The embedded-mode fix does not carry over because it
+acts in the daemon process, on a different request, from where the
+client-facing chunked framing is applied.
+
+**Workaround**
+
+Where it matters that a client can detect a truncated response, have the
+application set a ``Content-Length`` header so the response is not sent
+chunked; a client can then detect a short read against the declared
+length. This is only possible when the response length is known in
+advance.
+
+**Status**
+
+Open. A fix would require framing the daemon-to-child response leg so the
+Apache child can distinguish a truncated response from a clean one and
+withhold the terminating ``0`` chunk. The value of such a fix is limited
+in any case: chunked transfer encoding is hop by hop, so an intermediary
+proxy may dechunk and re-chunk the response and append its own
+terminating chunk, which would erase the truncation signal before it
+reaches the client. Tracked as
+`issue #42 <https://github.com/GrahamDumpleton/mod_wsgi/issues/42>`__.

docs/release-notes.rst

@@ -8,6 +8,7 @@ mod_wsgi. See :doc:`project-status` for the version support policy.
 .. toctree::
    :maxdepth: 2
 
+   release-notes/version-6.0.2
    release-notes/version-6.0.1
    release-notes/version-6.0.0
 

docs/release-notes/version-6.0.2.rst

@@ -0,0 +1,80 @@
+=============
+Version 6.0.2
+=============
+
+Features Changed
+----------------
+
+* The way mod_wsgi proxies a response body back from a daemon process to
+  the HTTP client has been reworked so that it no longer interferes with
+  downstream output filters that pace or batch data, most notably
+  ``mod_ratelimit``. Previously mod_wsgi forced a flush both every time the
+  daemon socket momentarily ran dry and after each ``response-buffer-size``
+  worth of data had been passed on. Both kinds of flush forced the
+  ``mod_ratelimit`` ``RATE_LIMIT`` filter to emit a short write and so
+  throttled daemon mode responses far below the configured rate. As
+  mod_wsgi requires Apache 2.4, whose core output filter already bounds how
+  much response data is buffered in the Apache child processes, these
+  forced flushes are no longer needed to limit memory use and have been
+  removed. mod_wsgi now passes response data straight on, so a pacing
+  filter receives full-size writes and works correctly, while a genuinely
+  idle application still has its partial output flushed promptly so
+  streaming responses remain responsive.
+
+  The visible effect of the previous behaviour varied with the version of
+  Apache in use. With some versions of mod_ratelimit the forced flushes
+  effectively let the response through at close to full speed, so a
+  configured rate limit had little effect; with others they caused the
+  rate limit to be applied far too aggressively, throttling the response
+  well below the configured rate. In neither case could the rate limit be
+  honoured accurately for a daemon mode response, which it now is.
+
+  Two options on the :doc:`../configuration-directives/WSGIDaemonProcess`
+  directive control this behaviour:
+
+  - The new ``response-flush-delay`` option (default 5 milliseconds) sets
+    how long mod_wsgi waits for more response data before flushing when the
+    daemon socket runs dry, so a transient stall during an active transfer
+    does not trigger a flush while a genuinely paused application still has
+    its output flushed within that delay. Setting it to 0 flushes on any
+    stall and is not recommended when a pacing filter such as
+    ``mod_ratelimit`` is in use, as it can throttle responses far below the
+    configured rate.
+
+  - The ``response-buffer-size`` option has changed meaning. It is now a
+    coarse runaway guard that forces a flush only once this many bytes have
+    been passed downstream without one, in order to bound a downstream
+    filter that buffers without draining. Its default has been raised from
+    65536 bytes to 8388608 bytes (8 MB) accordingly; normal bounding of
+    response memory use is handled by the Apache core output filter.
+
+Bugs Fixed
+----------
+
+* Building the Windows ``mod_wsgi`` extension failed at the link stage with
+  a ``LNK2005`` multiply defined symbol error for ``PyInit_mod_wsgi``, and a
+  fatal ``LNK1169``. When the single ``mod_wsgi.c`` source file was split
+  into the separate ``wsgi_*.c`` files in version 6.0.0, the real
+  ``PyInit_mod_wsgi`` module init function moved into ``wsgi_module.c`` as
+  an unconditional definition, but an older Windows-only stub of the same
+  function was left behind in ``mod_wsgi.c``. On non-Windows builds the stub
+  was excluded by ``#if defined(_WIN32)`` so only one definition was
+  compiled, but on Windows both were compiled and the linker rejected the
+  duplicate. The obsolete stub has been removed so ``wsgi_module.c`` is the
+  sole provider of ``PyInit_mod_wsgi`` on all platforms.
+
+* Setting ``WSGIRestrictEmbedded Off`` after it had previously been set
+  to ``On`` could crash the Apache child process when an embedded mode
+  request was subsequently received. ``WSGIRestrictEmbedded On`` not only
+  blocks embedded mode requests but, as an optimisation, also suppresses
+  initialisation of Python in the Apache child processes when nothing
+  else requires it. Switching it back ``Off`` re-enabled embedded mode
+  request handling but did not undo that suppression, so the request
+  reached the embedded mode code path in a child where Python, and the
+  per-thread state it depends on, had never been initialised, causing a
+  crash. ``WSGIRestrictEmbedded Off`` now marks Python as required in the
+  Apache child processes, consistent with the other directives that need
+  it, so embedded mode works as expected. As an additional safeguard, an
+  embedded mode request that reaches a child with no initialised Python
+  interpreter is now rejected with a ``500 Internal Server Error`` and
+  logged as :ref:`WSGI0210` rather than crashing the process.

docs/reporting-bugs.rst

@@ -10,7 +10,9 @@ the GitHub issue tracker:
 A substantial fraction of bug reports against mod_wsgi turn out to
 be misconfiguration, application errors, or problems in third-party
 packages rather than mod_wsgi bugs. Before filing a bug report,
-work through :doc:`troubleshooting`.
+work through :doc:`troubleshooting`. If the behaviour does look like
+a defect or limitation in mod_wsgi itself, check :doc:`known-issues`
+first, as it may already be recorded there along with any workaround.
 
 For general questions, or if you want to discuss whether something
 is actually a bug before filing it, see :doc:`finding-help`.