The http module aims to implement a fully-functional and extensible HyperText Transfer Protocol (web) server, compliant with HTTP version 1.1.
server.channel.add ( "http", profile_name : String )
The http stream manages an HTTP connection. Depending on the protocol version supported by the client, it may create multiple message streams to handle each request as it is received. The message stream connects the appropriate response stream to generate the response.
The http module includes support for:
- HTTPS - HTTP over a secure connection (requires the ssl module).
- Persistent connections - Allowing multiple HTTP transactions to be sent and received over a single TCP connection. This cuts down on latency since a connection isn't required for every single element request.
- Pipelining - Allowing multiple HTTP requests to be sent without waiting for the response. This also reduces latency since the client can queue up a series of requests for resources it knows are required, reducing the amount of round-trips to the server.
- Chunked transfer encoding - Allowing pages generated on-the-fly to start streaming to the client, without having to wait for the entire page to be rendered.
- Sessions - These can be managed automatically via secure IDs saved in HTTP Cookies, allowing state for a user to be persisted between HTTP requests.
- Range requests - Allowing sections of a large file to be downloaded (useful for restarting a download if interrupted).
- HTTP basic authentication - For authenticating users at the HTTP level if required.
The following diagram shows the structure of the HTTP module:
Hosts and the Host Mapper
The first stage in handling an HTTP request is to determine what host is should be mapped to. The http module allows multiple hosts to be configured, allowing many different web sites to be served up by the same sever. The host to which the request should be directed is determined by examining the request URI and the "Host:" HTTP header, if present.
This host name is then matched with one of the configured hosts by the Host Mapper. If no match can be found, then an error response is generated. It is possible to avoid this and match any host name using a wildcard match of "*" in the host mapper. It is also possible to match any subdomain, e.g. "*.sconemad.com" would match "jam.sconemad.com" and "cheese.sconemad.com". Note that, from a caching point of view, it is generally better to use redirects than have multiple URLs mapping to the same entity in this way.
Profiles and DocRoots
You may have noticed the profile_name parameter in the router chain configuration above. This is passed through from the router chain, and can be used to select different files to be served depending on the method of connection, for example, on diferent TCP/IP ports. A common use for this is to serve a different set of files for insecure (http) and secure (https) connections.
Any module can be used to generate an HTTP response, but modules for which this is their primary purpose should be defined as sub-modules of the http module.
The following HTTP sub-modules are available:
Streams the requested file back to the client.
If a directory is requested, generates a directory index or redirects to default page.
Return an error response page.
In addition to the standard module interface, it also has the following:
|idle_timeout||Int||The connection idle timeout in seconds|
|hosts||HostMapper object||The Host Mapper|
|realms||AuthRealmManager object||The Authorization Realm Manager|
|sessions||SessionManager object||The Session Manager|
- set_idle_timeout ( timeout : Int )
- Set the idle timeout for connections to this module. The timeout value should be specified in seconds.