-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Web Application Interface.
--   
--   Provides a common protocol for communication between web applications
--   and web servers.
@package wai
@version 2.1.0


-- | Internal constructors and helper functions. Note that no guarantees
--   are given for stability of these interfaces.
module Network.Wai.Internal

-- | Information on the request sent by the client. This abstracts away the
--   details of the underlying implementation.
data Request
Request :: Method -> HttpVersion -> ByteString -> ByteString -> RequestHeaders -> Bool -> SockAddr -> [Text] -> Query -> Source IO ByteString -> Vault -> RequestBodyLength -> Maybe ByteString -> Maybe ByteString -> Request

-- | Request method such as GET.
requestMethod :: Request -> Method

-- | HTTP version such as 1.1.
httpVersion :: Request -> HttpVersion

-- | Extra path information sent by the client. The meaning varies slightly
--   depending on backend; in a standalone server setting, this is most
--   likely all information after the domain name. In a CGI application,
--   this would be the information following the path to the CGI executable
--   itself. Do not modify this raw value- modify pathInfo instead.
rawPathInfo :: Request -> ByteString

-- | If no query string was specified, this should be empty. This value
--   <i>will</i> include the leading question mark. Do not modify this raw
--   value- modify queryString instead.
rawQueryString :: Request -> ByteString

-- | A list of header (a pair of key and value) in an HTTP request.
requestHeaders :: Request -> RequestHeaders

-- | Was this request made over an SSL connection?
--   
--   Note that this value will <i>not</i> tell you if the client originally
--   made this request over SSL, but rather whether the current connection
--   is SSL. The distinction lies with reverse proxies. In many cases, the
--   client will connect to a load balancer over SSL, but connect to the
--   WAI handler without SSL. In such a case, <tt>isSecure</tt> will be
--   <tt>False</tt>, but from a user perspective, there is a secure
--   connection.
isSecure :: Request -> Bool

-- | The client's host information.
remoteHost :: Request -> SockAddr

-- | Path info in individual pieces- the url without a hostname/port and
--   without a query string, split on forward slashes,
pathInfo :: Request -> [Text]

-- | Parsed query string information
queryString :: Request -> Query

-- | A request body provided as <tt>Source</tt>.
requestBody :: Request -> Source IO ByteString

-- | A location for arbitrary data to be shared by applications and
--   middleware.
vault :: Request -> Vault

-- | The size of the request body. In the case of a chunked request body,
--   this may be unknown.
--   
--   Since 1.4.0
requestBodyLength :: Request -> RequestBodyLength

-- | The value of the Host header in a HTTP request.
--   
--   Since 2.0.0
requestHeaderHost :: Request -> Maybe ByteString

-- | The value of the Range header in a HTTP request.
--   
--   Since 2.0.0
requestHeaderRange :: Request -> Maybe ByteString

-- | The strange structure of the third field or ResponseSource is to allow
--   for exception-safe resource allocation. As an example:
--   
--   <pre>
--   app :: Application
--   app _ = return $ ResponseSource status200 [] $ \f -&gt; bracket
--       (putStrLn "Allocation" &gt;&gt; return 5)
--       (\i -&gt; putStrLn $ "Cleaning up: " ++ show i)
--       (\_ -&gt; f $ do
--           yield $ Chunk $ fromByteString "Hello "
--           yield $ Chunk $ fromByteString "World!")
--   </pre>
data Response
ResponseFile :: Status -> ResponseHeaders -> FilePath -> (Maybe FilePart) -> Response
ResponseBuilder :: Status -> ResponseHeaders -> Builder -> Response
ResponseSource :: Status -> ResponseHeaders -> (forall b. WithSource IO (Flush Builder) b) -> Response
ResponseRaw :: (forall b. WithRawApp b) -> Response -> Response
type RawApp = Source IO ByteString -> Sink ByteString IO () -> IO ()
type WithRawApp b = (RawApp -> IO b) -> IO b

-- | Auxiliary type for <a>ResponseSource</a>.
type WithSource m a b = (Source m a -> m b) -> m b

-- | The size of the request body. In the case of chunked bodies, the size
--   will not be known.
--   
--   Since 1.4.0
data RequestBodyLength
ChunkedBody :: RequestBodyLength
KnownLength :: Word64 -> RequestBodyLength

-- | Information on which part to be sent. Sophisticated application
--   handles Range (and If-Range) then create <a>FilePart</a>.
data FilePart
FilePart :: Integer -> Integer -> Integer -> FilePart
filePartOffset :: FilePart -> Integer
filePartByteCount :: FilePart -> Integer
filePartFileSize :: FilePart -> Integer
instance Typeable Request
instance Typeable Response
instance Show FilePart


-- | This module defines a generic web application interface. It is a
--   common protocol between web servers and web applications.
--   
--   The overriding design principles here are performance and generality.
--   To address performance, this library is built on top of the conduit
--   and blaze-builder packages. The advantages of conduits over lazy IO
--   have been debated elsewhere and so will not be addressed here.
--   However, helper functions like <a>responseLBS</a> allow you to
--   continue using lazy IO if you so desire.
--   
--   Generality is achieved by removing many variables commonly found in
--   similar projects that are not universal to all servers. The goal is
--   that the <a>Request</a> object contains only data which is meaningful
--   in all circumstances.
--   
--   Please remember when using this package that, while your application
--   may compile without a hitch against many different servers, there are
--   other considerations to be taken when moving to a new backend. For
--   example, if you transfer from a CGI application to a FastCGI one, you
--   might suddenly find you have a memory leak. Conversely, a FastCGI
--   application would be well served to preload all templates from disk
--   when first starting; this would kill the performance of a CGI
--   application.
--   
--   This package purposely provides very little functionality. You can
--   find various middlewares, backends and utilities on Hackage. Some of
--   the most commonly used include:
--   
--   <ul>
--   <li><i>warp</i> <a>http://hackage.haskell.org/package/warp</a></li>
--   <li><i>wai-extra</i>
--   <a>http://hackage.haskell.org/package/wai-extra</a></li>
--   <li><i>wai-test</i>
--   <a>http://hackage.haskell.org/package/wai-test</a></li>
--   </ul>
module Network.Wai

-- | The WAI application.
type Application = Request -> IO Response

-- | 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.
--   
--   As an example of an alternate type for middleware, suppose you write a
--   function to load up session information. The session information is
--   simply a string map [(String, String)]. A logical type signature for
--   this middleware might be:
--   
--   <pre>
--   loadSession :: ([(String, String)] -&gt; Application) -&gt; Application
--   </pre>
--   
--   Here, instead of taking a standard <a>Application</a> as its first
--   argument, the middleware takes a function which consumes the session
--   information as well.
type Middleware = Application -> Application

-- | Information on the request sent by the client. This abstracts away the
--   details of the underlying implementation.
data Request

-- | A default, blank request.
--   
--   Since 2.0.0
defaultRequest :: Request

-- | The size of the request body. In the case of chunked bodies, the size
--   will not be known.
--   
--   Since 1.4.0
data RequestBodyLength
ChunkedBody :: RequestBodyLength
KnownLength :: Word64 -> RequestBodyLength

-- | Request method such as GET.
requestMethod :: Request -> Method

-- | HTTP version such as 1.1.
httpVersion :: Request -> HttpVersion

-- | Extra path information sent by the client. The meaning varies slightly
--   depending on backend; in a standalone server setting, this is most
--   likely all information after the domain name. In a CGI application,
--   this would be the information following the path to the CGI executable
--   itself. Do not modify this raw value- modify pathInfo instead.
rawPathInfo :: Request -> ByteString

-- | If no query string was specified, this should be empty. This value
--   <i>will</i> include the leading question mark. Do not modify this raw
--   value- modify queryString instead.
rawQueryString :: Request -> ByteString

-- | A list of header (a pair of key and value) in an HTTP request.
requestHeaders :: Request -> RequestHeaders

-- | Was this request made over an SSL connection?
--   
--   Note that this value will <i>not</i> tell you if the client originally
--   made this request over SSL, but rather whether the current connection
--   is SSL. The distinction lies with reverse proxies. In many cases, the
--   client will connect to a load balancer over SSL, but connect to the
--   WAI handler without SSL. In such a case, <tt>isSecure</tt> will be
--   <tt>False</tt>, but from a user perspective, there is a secure
--   connection.
isSecure :: Request -> Bool

-- | The client's host information.
remoteHost :: Request -> SockAddr

-- | Path info in individual pieces- the url without a hostname/port and
--   without a query string, split on forward slashes,
pathInfo :: Request -> [Text]

-- | Parsed query string information
queryString :: Request -> Query

-- | A request body provided as <tt>Source</tt>.
requestBody :: Request -> Source IO ByteString

-- | A location for arbitrary data to be shared by applications and
--   middleware.
vault :: Request -> Vault

-- | The size of the request body. In the case of a chunked request body,
--   this may be unknown.
--   
--   Since 1.4.0
requestBodyLength :: Request -> RequestBodyLength

-- | The value of the Host header in a HTTP request.
--   
--   Since 2.0.0
requestHeaderHost :: Request -> Maybe ByteString

-- | The value of the Range header in a HTTP request.
--   
--   Since 2.0.0
requestHeaderRange :: Request -> Maybe ByteString

-- | Get the request body as a lazy ByteString. This uses lazy I/O under
--   the surface, and therefore all typical warnings regarding lazy I/O
--   apply.
--   
--   Since 1.4.1
lazyRequestBody :: Request -> IO ByteString

-- | The strange structure of the third field or ResponseSource is to allow
--   for exception-safe resource allocation. As an example:
--   
--   <pre>
--   app :: Application
--   app _ = return $ ResponseSource status200 [] $ \f -&gt; bracket
--       (putStrLn "Allocation" &gt;&gt; return 5)
--       (\i -&gt; putStrLn $ "Cleaning up: " ++ show i)
--       (\_ -&gt; f $ do
--           yield $ Chunk $ fromByteString "Hello "
--           yield $ Chunk $ fromByteString "World!")
--   </pre>
data Response

-- | Information on which part to be sent. Sophisticated application
--   handles Range (and If-Range) then create <a>FilePart</a>.
data FilePart
FilePart :: Integer -> Integer -> Integer -> FilePart
filePartOffset :: FilePart -> Integer
filePartByteCount :: FilePart -> Integer
filePartFileSize :: FilePart -> Integer

-- | Auxiliary type for <a>ResponseSource</a>.
type WithSource m a b = (Source m a -> m b) -> m b

-- | Creating <a>Response</a> from a file.
responseFile :: Status -> ResponseHeaders -> FilePath -> Maybe FilePart -> Response

-- | Creating <a>Response</a> from <a>Builder</a>.
--   
--   Some questions and answers about the usage of <a>Builder</a> here:
--   
--   Q1. Shouldn't it be at the user's discretion to use Builders
--   internally and then create a stream of ByteStrings?
--   
--   A1. That would be less efficient, as we wouldn't get cheap
--   concatenation with the response headers.
--   
--   Q2. Isn't it really inefficient to convert from ByteString to Builder,
--   and then right back to ByteString?
--   
--   A2. No. If the ByteStrings are small, then they will be copied into a
--   larger buffer, which should be a performance gain overall (less system
--   calls). If they are already large, then blaze-builder uses an
--   InsertByteString instruction to avoid copying.
--   
--   Q3. Doesn't this prevent us from creating comet-style servers, since
--   data will be cached?
--   
--   A3. You can force blaze-builder to output a ByteString before it is an
--   optimal size by sending a flush command.
responseBuilder :: Status -> ResponseHeaders -> Builder -> Response

-- | Creating <a>Response</a> from <a>ByteString</a>. This is a wrapper for
--   <a>responseBuilder</a>.
responseLBS :: Status -> ResponseHeaders -> ByteString -> Response

-- | Creating <a>Response</a> from <a>Source</a>.
responseSource :: Status -> ResponseHeaders -> Source IO (Flush Builder) -> Response

-- | Creating <a>Response</a> with allocated resource safely released.
--   
--   <ul>
--   <li>The first argument is an action to allocate resource.</li>
--   <li>The second argument is a function to release the resource.</li>
--   <li>The third argument is a function to create
--   (<a>Status</a>,<a>ResponseHeaders</a>,<a>Source</a> <a>IO</a>
--   (<a>Flush</a> <a>Builder</a>)) from the resource.</li>
--   </ul>
responseSourceBracket :: IO a -> (a -> IO ()) -> (a -> IO (Status, ResponseHeaders, Source IO (Flush Builder))) -> IO Response

-- | Create a response for a raw application. This is useful for "upgrade"
--   situations such as WebSockets, where an application requests for the
--   server to grant it raw network access.
--   
--   This function requires a backup response to be provided, for the case
--   where the handler in question does not support such upgrading (e.g.,
--   CGI apps).
--   
--   In the event that you read from the request body before returning a
--   <tt>responseRaw</tt>, behavior is undefined.
--   
--   Since 2.1.0
responseRaw :: (Source IO ByteString -> Sink ByteString IO () -> IO ()) -> Response -> Response

-- | Accessing <a>Status</a> in <a>Response</a>.
responseStatus :: Response -> Status

-- | Accessing <a>Status</a> in <a>Response</a>.
responseHeaders :: Response -> ResponseHeaders

-- | Converting the body information in <a>Response</a> to <tt>Source</tt>.
responseToSource :: Response -> (Status, ResponseHeaders, WithSource IO (Flush Builder) b)
