@@ -35,9 +35,11 @@ include:
3535
3636-}
3737module Network.Wai
38− ( -- * WAI interface
39− -- ** Request
38+ (
39+ -- * Request
4040 Request
41+ , defaultRequest
42+ -- ** Request accessors
4143 , requestMethod
4244 , httpVersion
4345 , rawPathInfo
@@ -50,23 +52,22 @@ module Network.Wai
5052 , requestBody
5153 , vault
5254 , requestBodyLength
53− -- ** Response
55+ -- * Response
5456 , Response
57+ -- ** Response composers
5558 , responseFile
5659 , responseBuilder
5760 , responseSource
5861 , responseLBS
59− -- ** Other types
62+ -- * Response accessors
63+ , responseToSource
64+ , responseStatus
65+ -- * Other types
6066 , Application
6167 , Middleware
6268 , FilePart (..)
6369 , RequestBodyLength (..)
6470 , WithSource
65− -- ** Helper functions
66− , responseToSource
67− , responseStatus
68− -- ** Defaults
69− , defaultRequest
7071 ) where
7172
7273import Blaze.ByteString.Builder (Builder, fromLazyByteString)
@@ -83,12 +84,37 @@ import Network.Socket (SockAddr (SockAddrInet))
8384import Network.Wai.Internal
8485import qualified System.IO as IO
8586
87+-- | Creating 'Response' from a file.
8688responseFile :: H.Status -> H.ResponseHeaders -> FilePath -> Maybe FilePart -> Response
8789responseFile = ResponseFile
8890
91+-- | Creating 'Response' from 'Builder'.
92+--
93+-- Some questions and answers about the usage of 'Builder' here:
94+--
95+-- Q1. Shouldn't it be at the user's discretion to use Builders internally and
96+-- then create a stream of ByteStrings?
97+--
98+-- A1. That would be less efficient, as we wouldn't get cheap concatenation
99+-- with the response headers.
100+--
101+-- Q2. Isn't it really inefficient to convert from ByteString to Builder, and
102+-- then right back to ByteString?
103+--
104+-- A2. No. If the ByteStrings are small, then they will be copied into a larger
105+-- buffer, which should be a performance gain overall (less system calls). If
106+-- they are already large, then blaze-builder uses an InsertByteString
107+-- instruction to avoid copying.
108+--
109+-- Q3. Doesn't this prevent us from creating comet-style servers, since data
110+-- will be cached?
111+--
112+-- A3. You can force blaze-builder to output a ByteString before it is an
113+-- optimal size by sending a flush command.
89114responseBuilder :: H.Status -> H.ResponseHeaders -> Builder -> Response
90115responseBuilder = ResponseBuilder
91116
117+-- | Creating 'Response' from 'C.Source'.
92118responseSource :: H.Status -> H.ResponseHeaders -> C.Source IO (C.Flush Builder) -> Response
93119responseSource st hs src = ResponseSource st hs ($ src)
94120
@@ -113,9 +139,12 @@ sourceFilePart :: IO.Handle -> FilePart -> C.Source IO B.ByteString
113139sourceFilePart handle (FilePart offset count _) =
114140 CB.sourceHandleRange handle (Just offset) (Just count)
115141
142+-- | Creating 'Response' from 'L.ByteString'. This is a wrapper for
143+-- 'responseBuilder'.
116144responseLBS :: H.Status -> H.ResponseHeaders -> L.ByteString -> Response
117145responseLBS s h = ResponseBuilder s h . fromLazyByteString
118146
147+-- | The WAI application.
119148type Application = Request -> IO Response
120149
121150-- | Middleware is a component that sits between the server and application. It