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 Request object is constructed. This object is passed to a Router 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 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 ResponseWriter 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 Handlers.