This document is not meant for people writing web applications (although it might be useful for writing such documentation), but rather, for those hacking on twisted.web itself.
Low-level web
This lowest level is designed to have multiple implementations. The implementation merely needs to provide a
iweb.IChanRequest
interface. User applications should not generally have to touch this level at all. There are currently two: HTTP and CGI. Another implementation for interfacing with e.g. ModPython might be nifty. On the other hand, if you want to interface with Apache, the best way is probably to just use its mod_proxy.
Standard HTTP server (http.py
)
The standard low-level HTTP server infrastructure is comprised of three layers: the
http.HTTPFactory
,
http.HTTPChannel
, and
http.ChannelRequest
.
HTTPFactory
This object doesn't have much on it -- it's a protocol ServerFactory that creates a
HTTPChannel
object for each incoming request. It also holds some variables to fiddle with:
timeOut
and
maxPipeline
. The user-level server.Site object is a subclass of this. (TODO: I don't think server.Site shouldn't inherit from this, as it means you can't have a Site on a CGI easily...)
HTTPChannel
This object handles the very lowest level parsing: it separates the incoming stream into multiple requests, and creates a ChannelRequest to do the parsing of that request. Its implementation is closely tied to the implementation of ChannelRequest -- there is no well-defined interface.
HTTPChannelRequest
The
HTTPChannelRequest
object encompasses the state and parsing functions for one HTTP request. It is responsible for all the low-level connection oriented behavior of the HTTP request. Thus, it takes care of keep-alive, de-chunking, etc., and only passes the non-connection headers up to the user-level Request object. It has a well-defined interface (
iweb.IChanRequest
). See
iweb.IChanRequestCallbacks
for the methods it requires on the Request object.
CGI server (cgichannel.py
)
This server mode can only handle a single request per process. But, other than that, the idea is to support the standard twisted.web interface. Thus, the
CGIChannelRequest
object provides the same interface (
iweb.IChanRequest
) as the standard HTTP server and you can build a standard app on top of it.
Slightly higher low-level web (http.py
)
Request
The
http.Request
object implements the somewhat higher-level protocol bits without dictating any policy about how to process requests. If you want a different resource-traversal API than the standard, you should be able to subclass this object and implement it. For the default implementation of all the higher-level API, see
server.Request
This class has all the incoming data state. The raw data from the first line: method, unparsed uri, and client protocol, the incoming headers, and the incoming data stream. There is a single method: .writeResponse(response), to write back an IResponse object.
Response
The
http.Response
object is a self-contained representation of the desired response to a given request. The interface is fairly simple. You provide three pieces of information: response code (e.g. 200), the headers (http_headers.Headers object), and an outgoing data stream (implementor of stream.IStream).
Header object (http_header.py
)
Parsing and generating correct HTTP headers is not always as trivial as you might like. The goal here is to have the framework parse and generate the headers for you, from a structured representation.
The only public interface in this module is "Header". It has methods
getHeader
/
setHeader
which deal with parsed representations, as well as methods
getRawHeaders
/
setRawHeaders
which deal with unparsed representations. Headers are automatically converted between the two representations on demand, using the machinery in the rest of the file. There's also
removeHeader
and
hasHeader
, to fill out the set.
Here's a list of the HTTP headers and their expected parsed formats:
General headers
- Cache-Control: TODO
- Connection: TODO
- Date: integer seconds since Epoch
- Pragma: TODO
- Trailer: TODO
- Transfer-Encoding: list of string transfer-encodings
- Upgrade: TODO
- Via: TODO
- Warning: TODO
Request headers
- Accept: dictionary of MimeType->int qvalue.
- Accept-Charset: dictionary of string charset->int qvalue
- Accept-Encoding: dictionary of string encoding->int qvalue
- Accept-Language: dictionary of string language->int qvalue
- Authorization: TODO
- Expect: dictionary of expect feature->tuple (value, (param, paramvalue)*)
- From: string
- Host: string
- If-Match: list of ('*' or ETag instance)
- If-Modified-Since: integer seconds since Epoch.
- If-None-Match: list of ('*' or ETag instance)
- If-Range: Etag instance or integer seconds since Epoch
- If-Unmodified-Since: integer seconds since Epoch
- Max-Forwards: integer
- Proxy-Authorization: TODO
- Range: tuple (rangetype, (int start or None, int end or None))
- Referer: string
- TE: dictionary of string TE->int qvalue
- User-Agent: string
Response headers
- Accept-Ranges: list of range type strings
- Age: integer
- ETag: ETag instance
- Location: string
- Proxy-Authenticate: TODO
- Retry-After: integer seconds since Epoch
- Server: string
- Set-Cookie: list of Cookie instances
- Set-Cookie2: list of Cookie instances
- Vary: list of string header names
- WWW-Authenticate: TODO
Entity headers
- Allow: list of case-sensitive method strings
- Content-Encoding: list of string content-encodings
- Content-Language: list of string content languages
- Content-Length: integer length
- Content-Location: string
- Content-MD5: (decoded base64) string
- Content-Range: tuple of (rangetype, start, end, realLength)
- Content-Type: MimeType
- Expires: integer seconds since Epoch
- Last-Modified: integer seconds since Epoch
Stream objects (stream.py
)
See the docstring in stream.py.