|
| 1 | +============= |
| 2 | +Version 4.4.0 |
| 3 | +============= |
| 4 | + |
| 5 | +Version 4.4.0 of mod_wsgi can be obtained from: |
| 6 | + |
| 7 | + https://codeload.github.com/GrahamDumpleton/mod_wsgi/tar.gz/4.4.0 |
| 8 | + |
| 9 | +Known Issues |
| 10 | +------------ |
| 11 | + |
| 12 | +1. The makefiles for building mod_wsgi on Windows are currently broken and |
| 13 | +need updating. As most new changes relate to mod_wsgi daemon mode, which is |
| 14 | +not supported under Windows, you should keep using the last available |
| 15 | +binary for version 3.X on Windows instead. |
| 16 | + |
| 17 | +Bugs Fixed |
| 18 | +---------- |
| 19 | + |
| 20 | +1. When an exception occurs during the yielding of data from a generator |
| 21 | +returned from the WSGI application, and chunked transfer encoding was used |
| 22 | +on the response, then a '0' chunk would be errornously added at the end of |
| 23 | +the response content even though the response was likely incomplete. The |
| 24 | +result would be that clents wouldn't be able to properly detect that the |
| 25 | +response was truncated due to an error. This issue is now fixed for when |
| 26 | +embedded mode is being used. Fixing it for daemon mode is a bit trickier. |
| 27 | + |
| 28 | +2. Response headers returned from the WSGI application running in daemon |
| 29 | +mode were being wrongly attached to the internal Apache data structure for |
| 30 | +``err_headers_out`` instead of ``headers_out``. This meant that the |
| 31 | +``Header`` directive of the ``mod_headers`` module, with its default |
| 32 | +condition of only checking ``onsuccess`` headers would not work as |
| 33 | +expected. |
| 34 | + |
| 35 | +In order to be able to check for or modify the response headers one would |
| 36 | +have had to use the ``Header`` directive with the ``always`` condition and |
| 37 | +if also working with an embedded WSGI application, also define a parallel |
| 38 | +``Header`` directive but with the ``onsuccess`` condition. |
| 39 | + |
| 40 | +For daemon mode, response headers will now be correctly associated with |
| 41 | +``headers_out`` and the ``onsuccess`` condition of the ``Header`` directive. |
| 42 | +The only exception to this in either embedded or daemon mode now is that |
| 43 | +of the ``WWW-Authenticate`` header, which remains associated with |
| 44 | +``err_headers_out`` so that the header will survive an internal redirect |
| 45 | +such as to an ``ErrorDocument``. |
| 46 | + |
| 47 | +3. When optional support for chunked requests was enabled, it was only |
| 48 | +working properly for embedded mode. The feature now also works properly for |
| 49 | +daemon mode. |
| 50 | + |
| 51 | +The directive to enable support for chunked request content is |
| 52 | +``WSGIChunkedRequest``. The command line option when using mod_wsgi express |
| 53 | +is ``--chunked-request``. |
| 54 | + |
| 55 | +This is an optional feature, as the WSGI specification is arguably broken |
| 56 | +in not catering properly for mutating input filters or chunked request |
| 57 | +content. Support for chunked request content could be enabled by default, |
| 58 | +but then WSGI applications which don't simply read all available content |
| 59 | +and instead rely entirely on ``CONTENT_LENGTH``, would likely see a chunked |
| 60 | +request as having no content at all, as it would interpret the lack of |
| 61 | +the ``CONTENT_LENGTH`` as meaning the length of the content is zero. |
| 62 | + |
| 63 | +An attempt to get the WSGI specification ammended to be more sensible and |
| 64 | +allow what is a growing requirement to support chunked request content was |
| 65 | +ignored. Thus support is optional. You will need to enable this if you wish |
| 66 | +to rely on features of any WSGI framework that take the more sensible |
| 67 | +approach of ignoring ``CONTENT_LENGTH`` as a true indicator of content |
| 68 | +length. One such WSGI framework which provides some support for chunked |
| 69 | +request content is Flask/Werkzeug. Check its documentation or the code for |
| 70 | +Flask/Werkzeug to to see if any additional ``SetEnv`` directive may be |
| 71 | +required to enable the support in Flask/Werkzeug. |
| 72 | + |
| 73 | +4. Fixed a potential request content data corruption issue when running a |
| 74 | +WSGI application in daemon mode. The bug in the code is quite obvious, yet |
| 75 | +unable to trigger it on older mod_wsgi versions. It was though triggering |
| 76 | +quite easily in the current release on MacOS X, prior to it being fixed, |
| 77 | +due to the changes made to support chunked request content for daemon |
| 78 | +processes. |
| 79 | + |
| 80 | +Suspect it is still a latent bug in older mod_wsgi versions, but the |
| 81 | +conditions under which it would trigger must have been harder to induce. |
| 82 | +The lack of reported problems may have been aided by virtue of Linux UNIX |
| 83 | +socket buffer size being quite large, in comparison to MacOS X, and so |
| 84 | +harder to create a condition where not all data could be written onto the |
| 85 | +UNIX socket in one call. Yet, when buffer sizes for the UNIX socket on |
| 86 | +MacOS X were increased, it was still possible to induce the bug. |
| 87 | + |
| 88 | +5. When the ``--working-directory`` option for ``mod_wsgi-express`` was |
| 89 | +given a relative path name, that wasn't being translated to an absolute |
| 90 | +path name when substituting the ``home`` option of ``WSGIDaemonProcess`` |
| 91 | +causing server startup to fail. |
| 92 | + |
| 93 | +6. When using ``--debug-mode`` of ``mod_wsgi-express`` the working |
| 94 | +directory for the application was not being added to ``sys.path``. This |
| 95 | +meant that if the WSGI script was referenced from a different directory, |
| 96 | +any module imports for other modules in that directory would fail. |
| 97 | + |
| 98 | +Features Changed |
| 99 | +---------------- |
| 100 | + |
| 101 | +1. Until recently, a failed attempt to change the working directory for a |
| 102 | +daemon process to the user the process runs as would be ignored. Now it |
| 103 | +will cause a hard failure that will prevent the daemon process from |
| 104 | +starting. This would cause issues where the user, usually the default |
| 105 | +Apache user, has not valid home directory. Now what will happens is that |
| 106 | +any attempt will only be made to change the working directory to the home |
| 107 | +directory of the user the daemon process runs as, if the 'user' option had |
| 108 | +been explicitly set to define the user and the user is different to the |
| 109 | +user that Apache child worker processes run as. In other words, is |
| 110 | +different to the default Apache user. |
| 111 | + |
| 112 | +2. The support for the ``wdb`` debugger was removed. Decided that it wasn't |
| 113 | +mainstream enough and not ideal that still required a separate service and |
| 114 | +port to handle debugging sessions. |
| 115 | + |
| 116 | +New Features |
| 117 | +------------ |
| 118 | + |
| 119 | +1. Added new feature to ``mod_wsgi-express`` implementing timeouts on the |
| 120 | +reading of the request, including headers, and the request body. This |
| 121 | +feature uses the Apache module ``mod_reqtimeout`` to implement the feature. |
| 122 | + |
| 123 | +By default a read timeout on the initial request including headers of 15 |
| 124 | +seconds is used. This can dynamically increase up to a maximum of 30 |
| 125 | +seconds if the request data is received at a minimum required rate. |
| 126 | + |
| 127 | +By default a read timeout on the request body of 15 seconds is used. This |
| 128 | +can dynamically increase if the request data is received at a minimum |
| 129 | +required rate. |
| 130 | + |
| 131 | +The options to override the defaults are ``--header-timeout``, |
| 132 | +``--header-max-timeout``, ``--header-min-rate``, ``--body-timeout``, |
| 133 | +``--body-max-timeout`` and ``--body-min-rate``. For a more detailed |
| 134 | +explaination of this feature, consult the documentation for the Apache |
| 135 | +``mod_reqtimeout`` module. |
| 136 | + |
| 137 | +2. Added a new ``%{HOST}`` label that can be used when specifying the |
| 138 | +application group (Python sub interpreter context) to run the WSGI |
| 139 | +application in, via the ``WSGIApplicationGroup`` directive, or the |
| 140 | +``application-group`` option to ``WSGIScriptAlias``. |
| 141 | + |
| 142 | +This new label will result in an application group being used with a name |
| 143 | +that corresponds to the name of the site as identified by the HTTP request |
| 144 | +``Host`` header. Where the accepting port number is other than 80 or 443, |
| 145 | +then the name of the application group will be suffixed with the port |
| 146 | +number separated by a colon. |
| 147 | + |
| 148 | +Note that extreme care must be exercised when using this new label to |
| 149 | +specify the application group. This is because the HTTP request ``Host`` |
| 150 | +header is under the control of the user of the site. |
| 151 | + |
| 152 | +As such, it should only be used in conjunction with a configuration which |
| 153 | +adequately blocks access to anything but the expected hosts. |
| 154 | + |
| 155 | +For example, it would be dangerous to use this inside of a ``VirtualHost`` |
| 156 | +where the ``ServerAlias`` directive is used with a wildcard. This is |
| 157 | +because a user could pick arbitrary host names matching the wildcard and so |
| 158 | +force a new sub interpreter context to be created each time and so blow out |
| 159 | +memory usage. |
| 160 | + |
| 161 | +Similarly, caution should be exercised with ``mod_vhost_alias``, with any |
| 162 | +configuration forbidding any host which doesn't specifically match some |
| 163 | +specified resource such as a directory. |
| 164 | + |
| 165 | +Finally, this should probably never be used when not using either |
| 166 | +``VirtualHost`` or ``mod_vhost_alias`` as in that case the server is likely |
| 167 | +going to accept any ``Host`` header value without exclusions. |
| 168 | + |
| 169 | +3. Allow ``%{RESOURCE}``, ``%{SERVER}`` and ``%{HOST}`` labels to be used |
| 170 | +with the ``WSGIProcessGroup`` directive, or the ``process-group`` option of |
| 171 | +the ``WSGIScriptAlias`` directive. |
| 172 | + |
| 173 | +For this to work, it is still necessary to have setup an appropriate |
| 174 | +mod_wsgi daemon process group using the ``WSGIDaemonProcess`` directive, |
| 175 | +with name that will match the expanded value for the respective labels. |
| 176 | +If there is no matching mod_wsgi daemon process group specified, then |
| 177 | +a generic HTTP 500 internal server error response would be returned and |
| 178 | +the reason, lack of matching mod_wsgi daemon process group, being logged in |
| 179 | +the Apache error log. |
| 180 | + |
| 181 | +4. Error messages and exceptions raised when there is a failure to read |
| 182 | +request content, or write back a response now provide the internal error |
| 183 | +indication from Apache as to why. For the ``IOError`` exceptions which are |
| 184 | +raised, that the exception originates within Apache/mod_wsgi is now flagged |
| 185 | +in the description associated with the exception. |
| 186 | + |
| 187 | +5. When using mod_wsgi daemon mode and there is a timeout when reading |
| 188 | +request content in order to proxy it to the daemon process, a 408 request |
| 189 | +timeout HTTP response is now returned where as previously a generic 500 |
| 190 | +internal server error HTTP response was returned. |
| 191 | + |
| 192 | +Note that this doesn't mean that the WSGI application wasn't actually run. |
| 193 | +The WSGI application in the daemon process would have run as soon as the |
| 194 | +headers had been received. |
| 195 | + |
| 196 | +If the WSGI application had actually attempted to read the request content, |
| 197 | +it should also have eventually received an exception of type ``IOError`` |
| 198 | +when accessing ``wsgi.input`` to read the request content, due to a |
| 199 | +timeout or due to the proxy connection being closed before all request |
| 200 | +content was able to be read. |
| 201 | + |
| 202 | +If the WSGI application wasn't expecting any request content and had |
| 203 | +ignored it, even though some was present, it would still have run to |
| 204 | +completion and generated a response, but because the Apache child worker |
| 205 | +process was blocked waiting for content, when the timeout occurred the |
| 206 | +client would get the 408 HTTP response rather than the actual response |
| 207 | +generated by the WSGI application. |
| 208 | + |
| 209 | +6. Added the ``--log-to-terminal`` option to ``mod_wsgi-express`` to allow |
| 210 | +the error log output to be directed to standard error for the controlling |
| 211 | +terminal, and the access log output, if enabled, to be directed to standard |
| 212 | +output. Similarly, the startup log output, if enabled, will be sent to |
| 213 | +standard error also. |
| 214 | + |
| 215 | +This should not be used in conjunction with ``--setup-only`` option when |
| 216 | +using the generated ``apachectl`` script, unless the ``-DFOREGROUND`` |
| 217 | +option is also being supplied to ``apachectl`` at the time it is run with |
| 218 | +the ``start`` command. |
| 219 | + |
| 220 | +7. Added the ``--access-log-format`` option to ``mod_wsgi-express``. By |
| 221 | +default if the access log is enabled, entries will follow the 'common' log |
| 222 | +format as typically used by Apache. You have two options of how you can use |
| 223 | +the ``--access-log-format``. The first is to give it the argument |
| 224 | +'combined', which will then cause it to use this alternate log format |
| 225 | +which is again often used with Apache. The other is to specify the log |
| 226 | +format string yourself. |
| 227 | + |
| 228 | +The format string can contain format string components as would be used |
| 229 | +with the ``LogFormat`` directive. For example, to specify the equivalent to |
| 230 | +the 'common' log format, you could use:: |
| 231 | + |
| 232 | + --access-log-format "%h %l %u %t \"%r\" %>s %b" |
| 233 | + |
| 234 | +This 'common' log format is identified via a nickname in the same way |
| 235 | +'combined' is, so if you did have to specify it explicitly for some reason, |
| 236 | +you could just have instead used:: |
| 237 | + |
| 238 | + --access-log-format common |
| 239 | + |
| 240 | +8. Added the ``--newrelic-config-file`` and ``--newrelic-environment`` |
| 241 | +options to ``mod_wsgi-express``. This allows these to be set using command |
| 242 | +line options rather than requiring the New Relic environment variables. |
| 243 | +Importantly, when the options are used, the values will be embedded in the |
| 244 | +generated files if using ``--setup-only``. Thus they will still be set when |
| 245 | +later using the ``apachectl`` control script to start the server. |
| 246 | + |
| 247 | +Note that when these options are used, they will cause the equivalent New |
| 248 | +Relic environment variable for that option to be ignored, both if running |
| 249 | +the server immediately, or if using ``--setup-only`` and running the server |
| 250 | +later using ``apachectl``. |
| 251 | + |
| 252 | +9. Added the ``--enable-debugger`` option to ``mod_wsgi-express``. When |
| 253 | +specified and at the same time the ``--debug-mode`` option is specified, |
| 254 | +then when an exception is raised from the initial execution of the WSGI |
| 255 | +application, when consuming the response iterable, or when calling any |
| 256 | +``close()`` method of the response iterable, then post mortem debugging of |
| 257 | +the exception will be triggered. Post mortem debugging is performed using |
| 258 | +the Python debugger (pdb). |
| 259 | + |
| 260 | +10. Added the ``--enable-coverage`` option to ``mod_wsgi-express``. When |
| 261 | +specified and at the same time the ``--debug-mode`` option is specified, |
| 262 | +then coverage analysis is enabled. When the server is exited, then the HTML |
| 263 | +reports will be output to the ``htmlcov`` directory under the server |
| 264 | +working directory, or the directory specified using the |
| 265 | +``--coverage-directory`` option. The ``coverage`` module must be installed |
| 266 | +for this feature to work. |
| 267 | + |
| 268 | +11. Added the ``--enable-profiler`` option to ``mod_wsgi-express``. When |
| 269 | +specified and at the same time the ``--debug-mode`` option is specified, |
| 270 | +then coverage analysis is enabled. When the server is exited, then the |
| 271 | +profiler data will be output to the ``pstats.dat`` file under the server |
| 272 | +working directory, or the file specified using the ``profiler-output-file`` |
| 273 | +option. |
| 274 | + |
| 275 | +12. Added the ``--python-path`` option to ``mod_wsgi-express`` to specify |
| 276 | +additional directories that should be added to the Python module search path. |
| 277 | + |
| 278 | +Note that these directories will not be processed for ``.pth`` files. If |
| 279 | +processing of ``.pth`` files is required, then the ``PYTHONPATH`` environment |
| 280 | +variable should be set and exported in a script file referred to using the |
| 281 | +``--envvars-script`` option. |
0 commit comments