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.