@@ -6,20 +6,20 @@ This module defines a generic web application interface. It is a common
66protocol between web servers and web applications.
77
88The overriding design principles here are performance, generality and type
9−safety. To address performance, this library is built on 'Enumerator's for the
10−request and response bodies. The advantages of this approach over lazy IO has
11−been debated elsewhere.
9+safety. To address performance, this library is built on 'Source' for the
10+request body and 'Enumerator' for the response bodies. The advantages of this
11+approach over lazy IO have been debated elsewhere.
1212
13−Nonetheless, many people find 'Enumerator's difficult to work with. For that
14−reason, this library includes the "Network.Wai.Enumerator" module to provide
15−more familiar abstractions, including lazy IO.
13+Nonetheless, many people find these data structures difficult to work with. For
14+that reason, this library includes the "Network.Wai.Enumerator" module to
15+provide more familiar abstractions, including lazy IO.
1616
1717Generality is achieved by removing many variables commonly found in similar
1818projects that are not universal to all servers. The goal is that the 'Request'
1919object contains only data which is meaningful in all circumstances.
2020
2121Unlike other approaches, this package declares many data types to assist in
22−type safety. This feels more in the general Haskell spirit.
22+type safety. This feels more inline with the general Haskell spirit.
2323
2424A final note: please remember when using this package that, while your
2525application my compile without a hitch against many different servers, there
@@ -56,8 +56,9 @@ module Network.Wai
5656 , Status (..)
5757 , statusCode
5858 , statusMessage
59− -- * Enumerator
59+ -- ** Source
6060 , Source (..)
61+ -- * Enumerator
6162 , Enumerator (..)
6263 -- * WAI interface
6364 , Request (..)
@@ -310,6 +311,18 @@ statusMessage Status405 = B8.pack "Method Not Allowed"
310311statusMessage Status500 = B8.pack "Internal Server Error"
311312statusMessage (Status _ m) = m
312313
314+-- | This is a source for 'B.ByteString's. It is composed of two pieces: a
315+-- state variable, and a function to produce the output. The type of the state
316+-- variable is completely unknown to the user; some examples might be an 'Int'
317+-- for the remaining length of the content, or a list of 'B.ByteString's from
318+-- which to generate content.
319+--
320+-- The function accepts that state variable as its first argument. If input has
321+-- been fully consumed, it returns 'Nothing'; otherwise, it returns the next
322+-- piece of data and the next state.
323+--
324+-- Be certain not to reuse a state variable! It might work fine with some
325+-- implementations of 'Source', while causing bugs with others.
313326data Source = forall a. Source a (a -> IO (Maybe (B.ByteString, a)))
314327
315328-- | An enumerator is a data producer. It takes two arguments: a function to
@@ -337,10 +350,6 @@ data Source = forall a. Source a (a -> IO (Maybe (B.ByteString, a)))
337350-- 'Either' value; a 'Right' means the enumerator ran to completion, while a
338351-- 'Left' indicates early termination was requested by the iteratee.
339352--
340−-- 'Enumerator's are used twice in the WAI: once in the 'Request' datatype to
341−-- access the request body, and once in the 'Response' datatype for the
342−-- application to return the body of the response.
343−--
344353-- 'Enumerator's are not required to be resumable. That is to say, the
345354-- 'Enumerator' may only be called once. While this requirement puts a bit of a
346355-- strain on the caller in some situations, it saves a large amount of
@@ -378,14 +387,17 @@ data Response = Response
378387 , responseHeaders :: [(ResponseHeader, B.ByteString)]
379388 -- | A common optimization is to use the sendfile system call when sending
380389 -- files from the disk. This datatype facilitates this optimization; if
381− -- 'Left' is returns, the server will send the file from the disk by whatever
382− -- means it wishes. If 'Right', it will call the 'Enumerator'.
390+ -- 'Left' is returned, the server will send the file from the disk by
391+ -- whatever means it wishes. If 'Right', it will call the 'Enumerator'.
383392 , responseBody :: Either FilePath Enumerator
384393 }
385394
386395type Application = Request -> IO Response
387396
388−-- | Middleware is a component that sits between the server and application. It can do such tasks as GZIP encoding or response caching. What follows is the general definition of middleware, though a middleware author should feel free to modify this.
397+-- | Middleware is a component that sits between the server and application. It
398+-- can do such tasks as GZIP encoding or response caching. What follows is the
399+-- general definition of middleware, though a middleware author should feel
400+-- free to modify this.
389401--
390402-- As an example of an alternate type for middleware, suppose you write a
391403-- function to load up session information. The session information is simply a