Version 4.4.0¶
Version 4.4.0 of mod_wsgi can be obtained from:
Known Issues¶
1. The makefiles for building mod_wsgi on Windows are currently broken and need updating. As most new changes relate to mod_wsgi daemon mode, which is not supported under Windows, you should keep using the last available binary for version 3.X on Windows instead.
Bugs Fixed¶
1. When an exception occurs during the yielding of data from a generator returned from the WSGI application, and chunked transfer encoding was used on the response, then a ‘0’ chunk would be errornously added at the end of the response content even though the response was likely incomplete. The result would be that clents wouldn’t be able to properly detect that the response was truncated due to an error. This issue is now fixed for when embedded mode is being used. Fixing it for daemon mode is a bit trickier.
2. Response headers returned from the WSGI application running in daemon
mode were being wrongly attached to the internal Apache data structure for
err_headers_out instead of headers_out. This meant that the
Header directive of the mod_headers module, with its default
condition of only checking onsuccess headers would not work as
expected.
In order to be able to check for or modify the response headers one would
have had to use the Header directive with the always condition and
if also working with an embedded WSGI application, also define a parallel
Header directive but with the onsuccess condition.
For daemon mode, response headers will now be correctly associated with
headers_out and the onsuccess condition of the Header directive.
The only exception to this in either embedded or daemon mode now is that
of the WWW-Authenticate header, which remains associated with
err_headers_out so that the header will survive an internal redirect
such as to an ErrorDocument.
3. When optional support for chunked requests was enabled, it was only working properly for embedded mode. The feature now also works properly for daemon mode.
The directive to enable support for chunked request content is
WSGIChunkedRequest. The command line option when using mod_wsgi express
is --chunked-request.
This is an optional feature, as the WSGI specification is arguably broken
in not catering properly for mutating input filters or chunked request
content. Support for chunked request content could be enabled by default,
but then WSGI applications which don’t simply read all available content
and instead rely entirely on CONTENT_LENGTH, would likely see a chunked
request as having no content at all, as it would interpret the lack of
the CONTENT_LENGTH as meaning the length of the content is zero.
An attempt to get the WSGI specification ammended to be more sensible and
allow what is a growing requirement to support chunked request content was
ignored. Thus support is optional. You will need to enable this if you wish
to rely on features of any WSGI framework that take the more sensible
approach of ignoring CONTENT_LENGTH as a true indicator of content
length. One such WSGI framework which provides some support for chunked
request content is Flask/Werkzeug. Check its documentation or the code for
Flask/Werkzeug to to see if any additional SetEnv directive may be
required to enable the support in Flask/Werkzeug.
4. Fixed a potential request content data corruption issue when running a WSGI application in daemon mode. The bug in the code is quite obvious, yet unable to trigger it on older mod_wsgi versions. It was though triggering quite easily in the current release on MacOS X, prior to it being fixed, due to the changes made to support chunked request content for daemon processes.
Suspect it is still a latent bug in older mod_wsgi versions, but the conditions under which it would trigger must have been harder to induce. The lack of reported problems may have been aided by virtue of Linux UNIX socket buffer size being quite large, in comparison to MacOS X, and so harder to create a condition where not all data could be written onto the UNIX socket in one call. Yet, when buffer sizes for the UNIX socket on MacOS X were increased, it was still possible to induce the bug.
5. When the --working-directory option for mod_wsgi-express was
given a relative path name, that wasn’t being translated to an absolute
path name when substituting the home option of WSGIDaemonProcess
causing server startup to fail.
6. When using --debug-mode of mod_wsgi-express the working
directory for the application was not being added to sys.path. This
meant that if the WSGI script was referenced from a different directory,
any module imports for other modules in that directory would fail.
Features Changed¶
1. Until recently, a failed attempt to change the working directory for a daemon process to the user the process runs as would be ignored. Now it will cause a hard failure that will prevent the daemon process from starting. This would cause issues where the user, usually the default Apache user, has not valid home directory. Now what will happens is that any attempt will only be made to change the working directory to the home directory of the user the daemon process runs as, if the ‘user’ option had been explicitly set to define the user and the user is different to the user that Apache child worker processes run as. In other words, is different to the default Apache user.
2. The support for the wdb debugger was removed. Decided that it wasn’t
mainstream enough and not ideal that still required a separate service and
port to handle debugging sessions.
New Features¶
1. Added new feature to mod_wsgi-express implementing timeouts on the
reading of the request, including headers, and the request body. This
feature uses the Apache module mod_reqtimeout to implement the feature.
By default a read timeout on the initial request including headers of 15 seconds is used. This can dynamically increase up to a maximum of 30 seconds if the request data is received at a minimum required rate.
By default a read timeout on the request body of 15 seconds is used. This can dynamically increase if the request data is received at a minimum required rate.
The options to override the defaults are --header-timeout,
--header-max-timeout, --header-min-rate, --body-timeout,
--body-max-timeout and --body-min-rate. For a more detailed
explaination of this feature, consult the documentation for the Apache
mod_reqtimeout module.
2. Added a new %{HOST} label that can be used when specifying the
application group (Python sub interpreter context) to run the WSGI
application in, via the WSGIApplicationGroup directive, or the
application-group option to WSGIScriptAlias.
This new label will result in an application group being used with a name
that corresponds to the name of the site as identified by the HTTP request
Host header. Where the accepting port number is other than 80 or 443,
then the name of the application group will be suffixed with the port
number separated by a colon.
Note that extreme care must be exercised when using this new label to
specify the application group. This is because the HTTP request Host
header is under the control of the user of the site.
As such, it should only be used in conjunction with a configuration which adequately blocks access to anything but the expected hosts.
For example, it would be dangerous to use this inside of a VirtualHost
where the ServerAlias directive is used with a wildcard. This is
because a user could pick arbitrary host names matching the wildcard and so
force a new sub interpreter context to be created each time and so blow out
memory usage.
Similarly, caution should be exercised with mod_vhost_alias, with any
configuration forbidding any host which doesn’t specifically match some
specified resource such as a directory.
Finally, this should probably never be used when not using either
VirtualHost or mod_vhost_alias as in that case the server is likely
going to accept any Host header value without exclusions.
3. Allow %{RESOURCE}, %{SERVER} and %{HOST} labels to be used
with the WSGIProcessGroup directive, or the process-group option of
the WSGIScriptAlias directive.
For this to work, it is still necessary to have setup an appropriate
mod_wsgi daemon process group using the WSGIDaemonProcess directive,
with name that will match the expanded value for the respective labels.
If there is no matching mod_wsgi daemon process group specified, then
a generic HTTP 500 internal server error response would be returned and
the reason, lack of matching mod_wsgi daemon process group, being logged in
the Apache error log.
4. Error messages and exceptions raised when there is a failure to read
request content, or write back a response now provide the internal error
indication from Apache as to why. For the IOError exceptions which are
raised, that the exception originates within Apache/mod_wsgi is now flagged
in the description associated with the exception.
5. When using mod_wsgi daemon mode and there is a timeout when reading request content in order to proxy it to the daemon process, a 408 request timeout HTTP response is now returned where as previously a generic 500 internal server error HTTP response was returned.
Note that this doesn’t mean that the WSGI application wasn’t actually run. The WSGI application in the daemon process would have run as soon as the headers had been received.
If the WSGI application had actually attempted to read the request content,
it should also have eventually received an exception of type IOError
when accessing wsgi.input to read the request content, due to a
timeout or due to the proxy connection being closed before all request
content was able to be read.
If the WSGI application wasn’t expecting any request content and had ignored it, even though some was present, it would still have run to completion and generated a response, but because the Apache child worker process was blocked waiting for content, when the timeout occurred the client would get the 408 HTTP response rather than the actual response generated by the WSGI application.
6. Added the --log-to-terminal option to mod_wsgi-express to allow
the error log output to be directed to standard error for the controlling
terminal, and the access log output, if enabled, to be directed to standard
output. Similarly, the startup log output, if enabled, will be sent to
standard error also.
This should not be used in conjunction with --setup-only option when
using the generated apachectl script, unless the -DFOREGROUND
option is also being supplied to apachectl at the time it is run with
the start command.
7. Added the --access-log-format option to mod_wsgi-express. By
default if the access log is enabled, entries will follow the ‘common’ log
format as typically used by Apache. You have two options of how you can use
the --access-log-format. The first is to give it the argument
‘combined’, which will then cause it to use this alternate log format
which is again often used with Apache. The other is to specify the log
format string yourself.
The format string can contain format string components as would be used
with the LogFormat directive. For example, to specify the equivalent to
the ‘common’ log format, you could use:
--access-log-format "%h %l %u %t \"%r\" %>s %b"
This ‘common’ log format is identified via a nickname in the same way ‘combined’ is, so if you did have to specify it explicitly for some reason, you could just have instead used:
--access-log-format common
8. Added the --newrelic-config-file and --newrelic-environment
options to mod_wsgi-express. This allows these to be set using command
line options rather than requiring the New Relic environment variables.
Importantly, when the options are used, the values will be embedded in the
generated files if using --setup-only. Thus they will still be set when
later using the apachectl control script to start the server.
Note that when these options are used, they will cause the equivalent New
Relic environment variable for that option to be ignored, both if running
the server immediately, or if using --setup-only and running the server
later using apachectl.
9. Added the --enable-debugger option to mod_wsgi-express. When
specified and at the same time the --debug-mode option is specified,
then when an exception is raised from the initial execution of the WSGI
application, when consuming the response iterable, or when calling any
close() method of the response iterable, then post mortem debugging of
the exception will be triggered. Post mortem debugging is performed using
the Python debugger (pdb).
10. Added the --enable-coverage option to mod_wsgi-express. When
specified and at the same time the --debug-mode option is specified,
then coverage analysis is enabled. When the server is exited, then the HTML
reports will be output to the htmlcov directory under the server
working directory, or the directory specified using the
--coverage-directory option. The coverage module must be installed
for this feature to work.
11. Added the --enable-profiler option to mod_wsgi-express. When
specified and at the same time the --debug-mode option is specified,
then coverage analysis is enabled. When the server is exited, then the
profiler data will be output to the pstats.dat file under the server
working directory, or the file specified using the --profiler-output-file
option.
12. Added the --python-path option to mod_wsgi-express to specify
additional directories that should be added to the Python module search path.
Note that these directories will not be processed for .pth files. If
processing of .pth files is required, then the PYTHONPATH environment
variable should be set and exported in a script file referred to using the
--envvars-script option.