introduction.rst (2049B)
1 Introduction 2 ============ 3 4 wptserve has been designed with the specific goal of making a server 5 that is suitable for writing tests for the web platform. This means 6 that it cannot use common abstractions over HTTP such as WSGI, since 7 these assume that the goal is to generate a well-formed HTTP 8 response. Testcases, however, often require precise control of the 9 exact bytes sent over the wire and their timing. The full list of 10 design goals for the server are: 11 12 * Suitable to run on individual test machines and over the public internet. 13 14 * Support plain TCP and SSL servers. 15 16 * Serve static files with the minimum of configuration. 17 18 * Allow headers to be overwritten on a per-file and per-directory 19 basis. 20 21 * Full customisation of headers sent (e.g. altering or omitting 22 "mandatory" headers). 23 24 * Simple per-client state. 25 26 * Complex logic in tests, up to precise control over the individual 27 bytes sent and the timing of sending them. 28 29 Request Handling 30 ---------------- 31 32 At the high level, the design of the server is based around similar 33 concepts to those found in common web frameworks like Django, Pyramid 34 or Flask. In particular the lifecycle of a typical request will be 35 familiar to users of these systems. Incoming requests are parsed and a 36 :doc:`Request <request>` object is constructed. This object is passed 37 to a :ref:`Router <router.Interface>` instance, which is 38 responsible for mapping the request method and path to a handler 39 function. This handler is passed two arguments; the request object and 40 a :doc:`Response <response>` object. In cases where only simple 41 responses are required, the handler function may fill in the 42 properties of the response object and the server will take care of 43 constructing the response. However each Response also contains a 44 :ref:`ResponseWriter <response.Interface>` which can be 45 used to directly control the TCP socket. 46 47 By default there are several built-in handler functions that provide a 48 higher level API than direct manipulation of the Response 49 object. These are documented in :doc:`handlers`.