| 1 |
:mod:`wsgi` -- WSGI server |
| 2 |
=========================== |
| 3 |
|
| 4 |
The wsgi module provides a simple and easy way to start an event-driven |
| 5 |
`WSGI <http://wsgi.org/wsgi/>`_ server. This can serve as an embedded |
| 6 |
web server in an application, or as the basis for a more full-featured web |
| 7 |
server package. One such package is `Spawning <http://pypi.python.org/pypi/Spawning/>`_. |
| 8 |
|
| 9 |
To launch a wsgi server, simply create a socket and call :func:`eventlet.wsgi.server` with it:: |
| 10 |
|
| 11 |
from eventlet import wsgi |
| 12 |
import eventlet |
| 13 |
|
| 14 |
def hello_world(env, start_response): |
| 15 |
start_response('200 OK', [('Content-Type', 'text/plain')]) |
| 16 |
return ['Hello, World!\r\n'] |
| 17 |
|
| 18 |
wsgi.server(eventlet.listen(('', 8090)), hello_world) |
| 19 |
|
| 20 |
|
| 21 |
You can find a slightly more elaborate version of this code in the file |
| 22 |
``examples/wsgi.py``. |
| 23 |
|
| 24 |
.. automodule:: eventlet.wsgi |
| 25 |
:members: |
| 26 |
|
| 27 |
.. _wsgi_ssl: |
| 28 |
|
| 29 |
SSL |
| 30 |
--- |
| 31 |
|
| 32 |
Creating a secure server is only slightly more involved than the base example. All that's needed is to pass an SSL-wrapped socket to the :func:`~eventlet.wsgi.server` method:: |
| 33 |
|
| 34 |
wsgi.server(eventlet.wrap_ssl(eventlet.listen(('', 8090)), |
| 35 |
certfile='cert.crt', |
| 36 |
keyfile='private.key', |
| 37 |
server_side=True), |
| 38 |
hello_world) |
| 39 |
|
| 40 |
Applications can detect whether they are inside a secure server by the value of the ``env['wsgi.url_scheme']`` environment variable. |
| 41 |
|
| 42 |
|
| 43 |
Non-Standard Extension to Support Post Hooks |
| 44 |
-------------------------------------------- |
| 45 |
Eventlet's WSGI server supports a non-standard extension to the WSGI |
| 46 |
specification where :samp:`env['eventlet.posthooks']` contains an array of |
| 47 |
`post hooks` that will be called after fully sending a response. Each post hook |
| 48 |
is a tuple of :samp:`(func, args, kwargs)` and the `func` will be called with |
| 49 |
the WSGI environment dictionary, followed by the `args` and then the `kwargs` |
| 50 |
in the post hook. |
| 51 |
|
| 52 |
For example:: |
| 53 |
|
| 54 |
from eventlet import wsgi |
| 55 |
import eventlet |
| 56 |
|
| 57 |
def hook(env, arg1, arg2, kwarg3=None, kwarg4=None): |
| 58 |
print('Hook called: %s %s %s %s %s' % (env, arg1, arg2, kwarg3, kwarg4)) |
| 59 |
|
| 60 |
def hello_world(env, start_response): |
| 61 |
env['eventlet.posthooks'].append( |
| 62 |
(hook, ('arg1', 'arg2'), {'kwarg3': 3, 'kwarg4': 4})) |
| 63 |
start_response('200 OK', [('Content-Type', 'text/plain')]) |
| 64 |
return ['Hello, World!\r\n'] |
| 65 |
|
| 66 |
wsgi.server(eventlet.listen(('', 8090)), hello_world) |
| 67 |
|
| 68 |
The above code will print the WSGI environment and the other passed function |
| 69 |
arguments for every request processed. |
| 70 |
|
| 71 |
Post hooks are useful when code needs to be executed after a response has been |
| 72 |
fully sent to the client (or when the client disconnects early). One example is |
| 73 |
for more accurate logging of bandwidth used, as client disconnects use less |
| 74 |
bandwidth than the actual Content-Length. |
| 75 |
|
| 76 |
|
| 77 |
"100 Continue" Response Headers |
| 78 |
------------------------------- |
| 79 |
|
| 80 |
Eventlet's WSGI server supports sending (optional) headers with HTTP "100 Continue" |
| 81 |
provisional responses. This is useful in such cases where a WSGI server expects |
| 82 |
to complete a PUT request as a single HTTP request/response pair, and also wants to |
| 83 |
communicate back to client as part of the same HTTP transaction. An example is |
| 84 |
where the HTTP server wants to pass hints back to the client about characteristics |
| 85 |
of data payload it can accept. As an example, an HTTP server may pass a hint in a |
| 86 |
header the accompanying "100 Continue" response to the client indicating it can or |
| 87 |
cannot accept encrypted data payloads, and thus client can make the encrypted vs |
| 88 |
unencrypted decision before starting to send the data). |
| 89 |
|
| 90 |
This works well for WSGI servers as the WSGI specification mandates HTTP |
| 91 |
expect/continue mechanism (PEP333). |
| 92 |
|
| 93 |
To define the "100 Continue" response headers, one may call |
| 94 |
:func:`set_hundred_continue_response_header` on :samp:`env['wsgi.input']` |
| 95 |
as shown in the following example:: |
| 96 |
|
| 97 |
from eventlet import wsgi |
| 98 |
import eventlet |
| 99 |
|
| 100 |
def wsgi_app(env, start_response): |
| 101 |
# Define "100 Continue" response headers |
| 102 |
env['wsgi.input'].set_hundred_continue_response_headers( |
| 103 |
[('Hundred-Continue-Header-1', 'H1'), |
| 104 |
('Hundred-Continue-Header-k', 'Hk')]) |
| 105 |
# The following read() causes "100 Continue" response to |
| 106 |
# the client. Headers 'Hundred-Continue-Header-1' and |
| 107 |
# 'Hundred-Continue-Header-K' are sent with the response |
| 108 |
# following the "HTTP/1.1 100 Continue\r\n" status line |
| 109 |
text = env['wsgi.input'].read() |
| 110 |
start_response('200 OK', [('Content-Length', str(len(text)))]) |
| 111 |
return [text] |
| 112 |
|
| 113 |
You can find a more elaborate example in the file: |
| 114 |
``tests/wsgi_test.py``, :func:`test_024a_expect_100_continue_with_headers`. |
| 115 |
|
| 116 |
|
| 117 |
Per HTTP RFC 7231 (http://tools.ietf.org/html/rfc7231#section-6.2) a client is |
| 118 |
required to be able to process one or more 100 continue responses. A sample |
| 119 |
use case might be a user protocol where the server may want to use a 100-continue |
| 120 |
response to indicate to a client that it is working on a request and the |
| 121 |
client should not timeout. |
| 122 |
|
| 123 |
To support multiple 100-continue responses, evenlet wsgi module exports |
| 124 |
the API :func:`send_hundred_continue_response`. |
| 125 |
|
| 126 |
Sample use cases for chunked and non-chunked HTTP scenarios are included |
| 127 |
in the wsgi test case ``tests/wsgi_test.py``, |
| 128 |
:func:`test_024b_expect_100_continue_with_headers_multiple_chunked` and |
| 129 |
:func:`test_024c_expect_100_continue_with_headers_multiple_nonchunked`. |
| 130 |
|