@@ -7,22 +7,32 @@ This module defines a generic web application interface. It is a common
77protocol between web servers and web applications.
88
99The overriding design principles here are performance and generality . To
10−address performance, this library is built on top of the enumerator package.
11−The advantages of this approach over lazy IO have been debated elsewhere.
12−However, helper functions like 'responseLBS' allow you to continue using lazy
13−IO if you so desire.
10+address performance, this library is built on top of the enumerator and
11+blaze-builder packages. The advantages of enumerators over lazy IO have been
12+debated elsewhere and so will not be addressed here. However, helper functions
13+like 'responseLBS' allow you to continue using lazy IO if you so desire.
1414
1515Generality is achieved by removing many variables commonly found in similar
1616projects that are not universal to all servers. The goal is that the 'Request'
1717object contains only data which is meaningful in all circumstances.
1818
19−A final note: please remember when using this package that, while your
20−application may compile without a hitch against many different servers, there
21−are other considerations to be taken when moving to a new backend. For example,
22−if you transfer from a CGI application to a FastCGI one, you might suddenly
23−find you have a memory leak. Conversely, a FastCGI application would be
24−well served to preload all templates from disk when first starting; this
25−would kill the performance of a CGI application.
19+Please remember when using this package that, while your application may
20+compile without a hitch against many different servers, there are other
21+considerations to be taken when moving to a new backend. For example, if you
22+transfer from a CGI application to a FastCGI one, you might suddenly find you
23+have a memory leak. Conversely, a FastCGI application would be well served to
24+preload all templates from disk when first starting; this would kill the
25+performance of a CGI application.
26+
27+This package purposely provides very little functionality. You can find various
28+middlewares, backends and utilities on Hackage. Some of the most commonly used
29+include:
30+
31+[warp] <http://hackage.haskell.org/package/warp>
32+
33+[wai-extra] <http://hackage.haskell.org/package/wai-extra>
34+
35+[wai-test] <http://hackage.haskell.org/package/wai-test>
2636
2737-}
2838module Network.Wai
@@ -61,9 +71,17 @@ data Request = Request
6171 -- all information after the domain name. In a CGI application, this would be
6272 -- the information following the path to the CGI executable itself.
6373 , rawPathInfo :: B.ByteString
64− -- | If no query string was specified, this should be empty.
74+ -- | If no query string was specified, this should be empty. This value
75+ -- /will/ include the leading question mark.
6576 , rawQueryString :: B.ByteString
77+ -- | Generally the host requested by the user via the Host request header.
78+ -- Backends are free to provide alternative values as necessary. This value
79+ -- should not be used to construct URLs.
6680 , serverName :: B.ByteString
81+ -- | The listening port that the server received this request on. It is
82+ -- possible for a server to listen on a non-numeric port (i.e., Unix named
83+ -- socket), in which case this value will be arbitrary. Like 'serverName',
84+ -- this value should not be used in URL construction.
6785 , serverPort :: Int
6886 , requestHeaders :: H.RequestHeaders
6987 -- | Was this request made over an SSL connection?