| Introduction |
| ============ |
| |
| wptserve has been designed with the specific goal of making a server |
| that is suitable for writing tests for the web platform. This means |
| that it cannot use common abstractions over HTTP such as WSGI, since |
| these assume that the goal is to generate a well-formed HTTP |
| response. Testcases, however, often require precise control of the |
| exact bytes sent over the wire and their timing. The full list of |
| design goals for the server are: |
| |
| * Suitable to run on individual test machines and over the public internet. |
| |
| * Support plain TCP and SSL servers. |
| |
| * Serve static files with the minimum of configuration. |
| |
| * Allow headers to be overwritten on a per-file and per-directory |
| basis. |
| |
| * Full customisation of headers sent (e.g. altering or omitting |
| "mandatory" headers). |
| |
| * Simple per-client state. |
| |
| * Complex logic in tests, up to precise control over the individual |
| bytes sent and the timing of sending them. |
| |
| Request Handling |
| ---------------- |
| |
| At the high level, the design of the server is based around similar |
| concepts to those found in common web frameworks like Django, Pyramid |
| or Flask. In particular the lifecycle of a typical request will be |
| familiar to users of these systems. Incoming requests are parsed and a |
| :doc:`Request <request>` object is constructed. This object is passed |
| to a :ref:`Router <router.Interface>` instance, which is |
| responsible for mapping the request method and path to a handler |
| function. This handler is passed two arguments; the request object and |
| a :doc:`Response <response>` object. In cases where only simple |
| responses are required, the handler function may fill in the |
| properties of the response object and the server will take care of |
| constructing the response. However each Response also contains a |
| :ref:`ResponseWriter <response.Interface>` which can be |
| used to directly control the TCP socket. |
| |
| By default there are several built-in handler functions that provide a |
| higher level API than direct manipulation of the Response |
| object. These are documented in :doc:`handlers`. |
| |
| |
