Waitress¶
Waitress is meant to be a production-quality pure-Python WSGI server with very acceptable performance. It has no dependencies except ones which live in the Python standard library. It runs on CPython on Unix and Windows under Python 2.6+ and Python 3.2+. It is also known to run on PyPy 1.6.0 on UNIX. It supports HTTP/1.0 and HTTP/1.1.
Usage¶
Here’s normal usage of the server:
from waitress import serve
serve(wsgiapp, host='0.0.0.0', port=8080)
If you want to serve your application on all IP addresses, on port 8080, you
can omit the host
and port
arguments and just call serve
with the
WSGI app as a single argument:
from waitress import serve
serve(wsgiapp)
Press Ctrl-C (or Ctrl-Break on Windows) to exit the server.
If you want to serve your application through a UNIX domain socket (to serve
a downstream HTTP server/proxy, e.g. nginx, lighttpd, etc.), call serve
with the unix_socket
argument:
from waitress import serve
serve(wsgiapp, unix_socket='/path/to/unix.sock')
Needless to say, this configuration won’t work on Windows.
Exceptions generated by your application will be shown on the console by default. See Logging to change this.
There’s an entry point for PasteDeploy (egg:waitress#main
) that
lets you use Waitress’s WSGI gateway from a configuration file, e.g.:
[server:main]
use = egg:waitress#main
host = 127.0.0.1
port = 8080
The PasteDeploy syntax for UNIX domain sockets is analagous:
[server:main]
use = egg:waitress#main
unix_socket = /path/to/unix.sock
You can find more settings to tweak (arguments to waitress.serve
or
equivalent settings in PasteDeploy) in Arguments to waitress.serve.
Additionally, there is a command line runner called waitress-serve
, which
can be used in development and in situations where the likes of
PasteDeploy is not necessary:
waitress-serve --port=8041 myapp:wsgifunc
For more information on this, see waitress-serve.
Logging¶
waitress.serve
calls logging.basicConfig()
to set up logging to the
console when the server starts up. Assuming no other logging configuration
has already been done, this sets the logging default level to
logging.WARNING
. The Waitress logger will inherit the root logger’s
level information (it logs at level WARNING
or above).
Waitress sends its logging output (including application exception
renderings) to the Python logger object named waitress
. You can
influence the logger level and output stream using the normal Python
logging
module API. For example:
import logging
logger = logging.getLogger('waitress')
logger.setLevel(logging.INFO)
Within a PasteDeploy configuration file, you can use the normal Python
logging
module .ini
file format to change similar Waitress logging
options. For example:
[logger_waitress]
level = INFO
Using Behind a Reverse Proxy¶
Often people will set up “pure Python” web servers behind reverse proxies, especially if they need SSL support (Waitress does not natively support SSL). Even if you don’t need SSL support, it’s not uncommon to see Waitress and other pure-Python web servers set up to “live” behind a reverse proxy; these proxies often have lots of useful deployment knobs.
If you’re using Waitress behind a reverse proxy, you’ll almost always want
your reverse proxy to pass along the Host
header sent by the client to
Waitress, in either case, as it will be used by most applications to generate
correct URLs.
For example, when using Nginx as a reverse proxy, you might add the following
lines in a location
section:
proxy_set_header Host $host;
The Apache directive named ProxyPreserveHost
does something similar when
used as a reverse proxy.
Unfortunately, even if you pass the Host
header, the Host header does not
contain enough information to regenerate the original URL sent by the client.
For example, if your reverse proxy accepts HTTPS requests (and therefore URLs
which start with https://
), the URLs generated by your application when
used behind a reverse proxy served by Waitress might inappropriately be
http://foo
rather than https://foo
. To fix this, you’ll want to
change the wsgi.url_scheme
in the WSGI environment before it reaches your
application. You can do this in one of three ways:
You can pass a
url_scheme
configuration variable to thewaitress.serve
function.You can configure the proxy reverse server to pass a header,
X_FORWARDED_PROTO
, whose value will be set for that request as thewsgi.url_scheme
environment value. Note that you must also conigurewaitress.serve
by passing the IP address of that proxy as itstrusted_proxy
.You can use Paste’s
PrefixMiddleware
in conjunction with configuration settings on the reverse proxy server.
Using url_scheme
to set wsgi.url_scheme
¶
You can have the Waitress server use the https
url scheme by default.:
from waitress import serve
serve(wsgiapp, host='0.0.0.0', port=8080, url_scheme='https')
This works if all URLs generated by your application should use the https
scheme.
Passing the X_FORWARDED_PROTO
header to set wsgi.url_scheme
¶
If your proxy accepts both HTTP and HTTPS URLs, and you want your application
to generate the appropriate url based on the incoming scheme, also set up
your proxy to send a X-Forwarded-Proto
with the original URL scheme along
with each proxied request. For example, when using Nginx:
proxy_set_header X-Forwarded-Proto $scheme;
or via Apache:
RequestHeader set X-Forwarded-Proto https
Note
You must also configure the Waitress server’s trusted_proxy
to
contain the IP address of the proxy in order for this header to override
the default URL scheme.
Using url_prefix
to influence SCRIPT_NAME
and PATH_INFO
¶
You can have the Waitress server use a particular url prefix by default for all
URLs generated by downstream applications that take SCRIPT_NAME
into
account.:
from waitress import serve
serve(wsgiapp, host='0.0.0.0', port=8080, url_prefix='/foo')
Setting this to any value except the empty string will cause the WSGI
SCRIPT_NAME
value to be that value, minus any trailing slashes you add, and
it will cause the PATH_INFO
of any request which is prefixed with this
value to be stripped of the prefix. This is useful in proxying scenarios where
you wish to forward all traffic to a Waitress server but need URLs generated by
downstream applications to be prefixed with a particular path segment.
Using Paste’s PrefixMiddleware
to set wsgi.url_scheme
¶
If only some of the URLs generated by your application should use the
https
scheme (and some should use http
), you’ll need to use Paste’s
PrefixMiddleware
as well as change some configuration settings on your
proxy. To use PrefixMiddleware
, wrap your application before serving it
using Waitress:
from waitress import serve
from paste.deploy.config import PrefixMiddleware
app = PrefixMiddleware(app)
serve(app)
Once you wrap your application in the the PrefixMiddleware
, the
middleware will notice certain headers sent from your proxy and will change
the wsgi.url_scheme
and possibly other WSGI environment variables
appropriately.
Once your application is wrapped by the prefix middleware, you should
instruct your proxy server to send along the original Host
header from
the client to your Waitress server, as well as sending along a
X-Forwarded-Proto
header with the appropriate value for
wsgi.url_scheme
.
If your proxy accepts both HTTP and HTTPS URLs, and you want your application
to generate the appropriate url based on the incoming scheme, also set up
your proxy to send a X-Forwarded-Proto
with the original URL scheme along
with each proxied request. For example, when using Nginx:
proxy_set_header X-Forwarded-Proto $scheme;
It’s permitted to set an X-Forwarded-For
header too; the
PrefixMiddleware
uses this to adjust other environment variables (you’ll
have to read its docs to find out which ones, I don’t know what they are). For
the X-Forwarded-For
header:
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
Note that you can wrap your application in the PrefixMiddleware declaratively in a PasteDeploy configuration file too, if your web framework uses PasteDeploy-style configuration:
[app:myapp]
use = egg:mypackage#myapp
[filter:paste_prefix]
use = egg:PasteDeploy#prefix
[pipeline:main]
pipeline =
paste_prefix
myapp
[server:main]
use = egg:waitress#main
host = 127.0.0.1
port = 8080
Note that you can also set PATH_INFO
and SCRIPT_NAME
using
PrefixMiddleware too (its original purpose, really) instead of using Waitress’
url_prefix
adjustment. See the PasteDeploy docs for more information.
Extended Documentation¶
Change History¶
0.9.0 (2016-04-15)¶
Deprecations¶
Python 3.2 is no longer supported by Waitress.
Python 2.6 will no longer be supported by Waitress in future releases.
Security/Protections¶
Building on the changes made in pull request 117, add in checking for line feed/carriage return HTTP Response Splitting in the status line, as well as the key of a header. See https://github.com/Pylons/waitress/pull/124 and https://github.com/Pylons/waitress/issues/122.
Waitress will no longer accept headers or status lines with newline/carriage returns in them, thereby disallowing HTTP Response Splitting. See https://github.com/Pylons/waitress/issues/117 for more information, as well as https://www.owasp.org/index.php/HTTP_Response_Splitting.
Bugfixes¶
FileBasedBuffer and more important ReadOnlyFileBasedBuffer no longer report False when tested with bool(), instead always returning True, and becoming more iterator like. See: https://github.com/Pylons/waitress/pull/82 and https://github.com/Pylons/waitress/issues/76
Call prune() on the output buffer at the end of a request so that it doesn’t continue to grow without bounds. See https://github.com/Pylons/waitress/issues/111 for more information.
0.8.10 (2015-09-02)¶
Add support for Python 3.4, 3.5b2, and PyPy3.
Use a nonglobal asyncore socket map by default, trying to prevent conflicts with apps and libs that use the asyncore global socket map ala https://github.com/Pylons/waitress/issues/63. You can get the old use-global-socket-map behavior back by passing
asyncore.socket_map
to thecreate_server
function as themap
argument.Waitress violated PEP 3333 with respect to reraising an exception when
start_response
was called with anexc_info
argument. It would reraise the exception even if no data had been sent to the client. It now only reraises the exception if data has actually been sent to the client. See https://github.com/Pylons/waitress/pull/52 and https://github.com/Pylons/waitress/issues/51Add a
docs
section to tox.ini that, when run, ensures docs can be built.If an
application
value ofNone
is supplied to thecreate_server
constructor function, a ValueError is now raised eagerly instead of an error occuring during runtime. See https://github.com/Pylons/waitress/pull/60Fix parsing of multi-line (folded) headers. See https://github.com/Pylons/waitress/issues/53 and https://github.com/Pylons/waitress/pull/90
Switch from the low level Python thread/_thread module to the threading module.
Improved exception information should module import go awry.
0.8.9 (2014-05-16)¶
Fix tests under Windows. NB: to run tests under Windows, you cannot run “setup.py test” or “setup.py nosetests”. Instead you must run
python.exe -c "import nose; nose.main()"
. If you try to run the tests using the normal method under Windows, each subprocess created by the test suite will attempt to run the test suite again. See https://github.com/nose-devs/nose/issues/407 for more information.Give the WSGI app_iter generated when
wsgi.file_wrapper
is used (ReadOnlyFileBasedBuffer) aclose
method. Do not callclose
on an instance of such a class when it’s used as a WSGI app_iter, however. This is part of a fix which prevents a leakage of file descriptors; the other part of the fix was in WebOb (https://github.com/Pylons/webob/commit/951a41ce57bd853947f842028bccb500bd5237da).Allow trusted proxies to override
wsgi.url_scheme
via a request header,X_FORWARDED_PROTO
. Allows proxies which serve mixed HTTP / HTTPS requests to control signal which are served as HTTPS. See https://github.com/Pylons/waitress/pull/42.
0.8.8 (2013-11-30)¶
Fix some cases where the creation of extremely large output buffers (greater than 2GB, suspected to be buffers added via
wsgi.file_wrapper
) might cause an OverflowError on Python 2. See https://github.com/Pylons/waitress/issues/47.When the
url_prefix
adjustment starts with more than one slash, all slashes except one will be stripped from its beginning. This differs from older behavior where more than one leading slash would be preserved inurl_prefix
.If a client somehow manages to send an empty path, we no longer convert the empty path to a single slash in
PATH_INFO
. Instead, the path remains empty. According to RFC 2616 section “5.1.2 Request-URI”, the scenario of a client sending an empty path is actually not possible because the request URI portion cannot be empty.If the
url_prefix
adjustment matches the request path exactly, we now computeSCRIPT_NAME
andPATH_INFO
properly. Previously, if theurl_prefix
was/foo
and the path received from a client was/foo
, we would set bothSCRIPT_NAME
andPATH_INFO
to/foo
. This was incorrect. Now in such a case we setPATH_INFO
to the empty string and we setSCRIPT_NAME
to/foo
. Note that the change we made has no effect on paths that do not match theurl_prefix
exactly (such as/foo/bar
); these continue to operate as they did. See https://github.com/Pylons/waitress/issues/46Preserve header ordering of headers with the same name as per RFC 2616. See https://github.com/Pylons/waitress/pull/44
When waitress receives a
Transfer-Encoding: chunked
request, we no longer send theTRANSFER_ENCODING
nor theHTTP_TRANSFER_ENCODING
value to the application in the environment. Instead, we pop this header. Since we cope with chunked requests by buffering the data in the server, we also know when a chunked request has ended, and therefore we know the content length. We set the content-length header in the environment, such that applications effectively never know the original request was a T-E: chunked request; it will appear to them as if the request is a non-chunked request with an accurate content-length.Cope with the fact that the
Transfer-Encoding
value is case-insensitive.When the
--unix-socket-perms
option was used as an argument towaitress-serve
, aTypeError
would be raised. See https://github.com/Pylons/waitress/issues/50.
0.8.7 (2013-08-29)¶
The HTTP version of the response returned by waitress when it catches an exception will now match the HTTP request version.
Fix: CONNECTION header will be HTTP_CONNECTION and not CONNECTION_TYPE (see https://github.com/Pylons/waitress/issues/13)
0.8.6 (2013-08-12)¶
Do alternate type of checking for UNIX socket support, instead of checking for platform == windows.
Functional tests now use multiprocessing module instead of subprocess module, speeding up test suite and making concurrent execution more reliable.
Runner now appends the current working directory to
sys.path
to support running WSGI applications from a directory (i.e., not installed in a virtualenv).Add a
url_prefix
adjustment setting. You can use it by passingscript_name='/foo'
towaitress.serve
or you can use it in aPasteDeploy
ini file asscript_name = /foo
. This will cause the WSGISCRIPT_NAME
value to be the value passed minus any trailing slashes you add, and it will cause thePATH_INFO
of any request which is prefixed with this value to be stripped of the prefix. You can use this instead of PasteDeploy’sprefixmiddleware
to always prefix the path.
0.8.5 (2013-05-27)¶
Fix runner multisegment imports in some Python 2 revisions (see https://github.com/Pylons/waitress/pull/34).
For compatibility, WSGIServer is now an alias of TcpWSGIServer. The signature of BaseWSGIServer is now compatible with WSGIServer pre-0.8.4.
0.8.4 (2013-05-24)¶
Add a command-line runner called
waitress-serve
to allow Waitress to run WSGI applications without any addional machinery. This is essentially a thin wrapper around thewaitress.serve()
function.Allow parallel testing (e.g., under
detox
ornosetests --processes
) using PID-dependent port / socket for functest servers.Fix integer overflow errors on large buffers. Thanks to Marcin Kuzminski for the patch. See: https://github.com/Pylons/waitress/issues/22
Add support for listening on Unix domain sockets.
0.8.3 (2013-04-28)¶
Features¶
Add an
asyncore_loop_timeout
adjustment value, which controls thetimeout
value passed toasyncore.loop
; defaults to 1.
Bug Fixes¶
The default asyncore loop timeout is now 1 second. This prevents slow shutdown on Windows. See https://github.com/Pylons/waitress/issues/6 . This shouldn’t matter to anyone in particular, but it can be changed via the
asyncore_loop_timeout
adjustment (it used to previously default to 30 seconds).Don’t complain if there’s a response to a HEAD request that contains a Content-Length > 0. See https://github.com/Pylons/waitress/pull/7.
Fix bug in HTTP Expect/Continue support. See https://github.com/Pylons/waitress/issues/9 .
0.8.2 (2012-11-14)¶
Bug Fixes¶
http://corte.si/posts/code/pathod/pythonservers/index.html pointed out that sending a bad header resulted in an exception leading to a 500 response instead of the more proper 400 response without an exception.
Fix a race condition in the test suite.
Allow “ident” to be used as a keyword to
serve()
as per docs.Add py33 to tox.ini.
0.8.1 (2012-02-13)¶
Bug Fixes¶
A brown-bag bug prevented request concurrency. A slow request would block subsequent the responses of subsequent requests until the slow request’s response was fully generated. This was due to a “task lock” being declared as a class attribute rather than as an instance attribute on HTTPChannel. Also took the opportunity to move another lock named “outbuf lock” to the channel instance rather than the class. See https://github.com/Pylons/waitress/pull/1 .
0.8 (2012-01-31)¶
Features¶
Support the WSGI
wsgi.file_wrapper
protocol as per http://www.python.org/dev/peps/pep-0333/#optional-platform-specific-file-handling. Here’s a usage example:import os here = os.path.dirname(os.path.abspath(__file__)) def myapp(environ, start_response): f = open(os.path.join(here, 'myphoto.jpg'), 'rb') headers = [('Content-Type', 'image/jpeg')] start_response( '200 OK', headers ) return environ['wsgi.file_wrapper'](f, 32768)
The signature of the file wrapper constructor is
(filelike_object, block_size)
. Both arguments must be passed as positional (not keyword) arguments. The result of creating a file wrapper should be returned as theapp_iter
from a WSGI application.The object passed as
filelike_object
to the wrapper must be a file-like object which supports at least theread()
method, and theread()
method must support an optional size hint argument. It should support theseek()
andtell()
methods. If it does not, normal iteration over the filelike object using the provided block_size is used (and copying is done, negating any benefit of the file wrapper). It should support aclose()
method.The specified
block_size
argument to the file wrapper constructor will be used only when thefilelike_object
doesn’t supportseek
and/ortell
methods. Waitress needs to use normal iteration to serve the file in this degenerate case (as per the WSGI spec), and this block size will be used as the iteration chunk size. Theblock_size
argument is optional; if it is not passed, a default value``32768`` is used.Waitress will set a
Content-Length
header on the behalf of an application when a file wrapper with a sufficiently filelike object is used if the application hasn’t already set one.The machinery which handles a file wrapper currently doesn’t do anything particularly special using fancy system calls (it doesn’t use
sendfile
for example); using it currently just prevents the system from needing to copy data to a temporary buffer in order to send it to the client. No copying of data is done when a WSGI app returns a file wrapper that wraps a sufficiently filelike object. It may do something fancier in the future.
0.7 (2012-01-11)¶
Features¶
Default
send_bytes
value is now 18000 instead of 9000. The larger default value prevents asyncore from needing to execute select so many times to serve large files, speeding up file serving by about 15%-20% or so. This is probably only an optimization for LAN communications, and could slow things down across a WAN (due to higher TCP overhead), but we’re likely to be behind a reverse proxy on a LAN anyway if in production.Added an (undocumented) profiling feature to the
serve()
command.
0.6.1 (2012-01-08)¶
Bug Fixes¶
Remove performance-sapping call to
pull_trigger
in the channel’swrite_soon
method added mistakenly in 0.6.
0.6 (2012-01-07)¶
Bug Fixes¶
A logic error prevented the internal outbuf buffer of a channel from being flushed when the client could not accept the entire contents of the output buffer in a single succession of socket.send calls when the channel was in a “pending close” state. The socket in such a case would be closed prematurely, sometimes resulting in partially delivered content. This was discovered by a user using waitress behind an Nginx reverse proxy, which apparently is not always ready to receive data. The symptom was that he received “half” of a large CSS file (110K) while serving content via waitress behind the proxy.
0.5 (2012-01-03)¶
Bug Fixes¶
Fix PATH_INFO encoding/decoding on Python 3 (as per PEP 3333, tunnel bytes-in-unicode-as-latin-1-after-unquoting).
0.4 (2012-01-02)¶
Features¶
Added “design” document to docs.
Bug Fixes¶
Set default
connection_limit
back to 100 for benefit of maximal platform compatibility.Normalize setting of
last_activity
during send.Minor resource cleanups during tests.
Channel timeout cleanup was broken.
0.3 (2012-01-02)¶
Features¶
Dont hang a thread up trying to send data to slow clients.
Use self.logger to log socket errors instead of self.log_info (normalize).
Remove pointless handle_error method from channel.
Queue requests instead of tasks in a channel.
Bug Fixes¶
Expect: 100-continue responses were broken.
0.2 (2011-12-31)¶
Bug Fixes¶
Set up logging by calling logging.basicConfig() when
serve
is called (show tracebacks and other warnings to console by default).Disallow WSGI applications to set “hop-by-hop” headers (Connection, Transfer-Encoding, etc).
Don’t treat 304 status responses specially in HTTP/1.1 mode.
Remove out of date
interfaces.py
file.Normalize logging (all output is now sent to the
waitress
logger rather than in degenerate cases some output being sent directly to stderr).
Features¶
Support HTTP/1.1
Transfer-Encoding: chunked
responses.Slightly better docs about logging.
0.1 (2011-12-30)¶
Initial release.
Known Issues¶
Does not yet support IPv6 natively.
Does not support SSL natively.
Support and Development¶
The Pylons Project web site is the main online source of Waitress support and development information.
To report bugs, use the issue tracker.
If you’ve got questions that aren’t answered by this documentation, contact the Pylons-devel maillist or join the #pyramid IRC channel.
Browse and check out tagged and trunk versions of Waitress via
the Waitress GitHub repository.
To check out the trunk via git
, use this command:
git clone git@github.com:Pylons/waitress.git
To find out how to become a contributor to Waitress, please see the contributor’s section of the documentation.
Why?¶
At the time of the release of Waitress, there are already many pure-Python WSGI servers. Why would we need another?
Waitress is meant to be useful to web framework authors who require broad
platform support. It’s neither the fastest nor the fanciest WSGI server
available but using it helps eliminate the N-by-M documentation burden
(e.g. production vs. deployment, Windows vs. Unix, Python 3 vs. Python 2,
PyPy vs. CPython) and resulting user confusion imposed by spotty platform
support of the current (2012-ish) crop of WSGI servers. For example,
gunicorn
is great, but doesn’t run on Windows. paste.httpserver
is
perfectly serviceable, but doesn’t run under Python 3 and has no dedicated
tests suite that would allow someone who did a Python 3 port to know it
worked after a port was completed. wsgiref
works fine under most any
Python, but it’s a little slow and it’s not recommended for production use as
it’s single-threaded and has not been audited for security issues.
At the time of this writing, some existing WSGI servers already claim wide platform support and have serviceable test suites. The CherryPy WSGI server, for example, targets Python 2 and Python 3 and it can run on UNIX or Windows. However, it is not distributed separately from its eponymous web framework, and requiring a non-CherryPy web framework to depend on the CherryPy web framework distribution simply for its server component is awkward. The test suite of the CherryPy server also depends on the CherryPy web framework, so even if we forked its server component into a separate distribution, we would have still needed to backfill for all of its tests. The CherryPy team has started work on Cheroot, which should solve this problem, however.
Waitress is a fork of the WSGI-related components which existed in
zope.server
. zope.server
had passable framework-independent test
coverage out of the box, and a good bit more coverage was added during the
fork. zope.server
has existed in one form or another since about 2001,
and has seen production usage since then, so Waitress is not exactly
“another” server, it’s more a repackaging of an old one that was already
known to work fairly well.