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


-- | Provides a common protocol for communication between web applications
--   and web servers.
--   
--   API docs and the README are available at
--   <a>http://www.stackage.org/package/wai</a>.
@package wai
@version 3.2.4


-- | 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 -> IO ByteString -> Vault -> RequestBodyLength -> Maybe ByteString -> Maybe ByteString -> 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.
--   
--   Middlewares and routing tools should not modify this raw value, as it
--   may be used for such things as creating redirect destinations by
--   applications. Instead, if you are writing a middleware or routing
--   framework, modify the <tt>pathInfo</tt> instead. This is the approach
--   taken by systems like Yesod subsites.
--   
--   <i>Note</i>: At the time of writing this documentation, there is at
--   least one system (<tt>Network.Wai.UrlMap</tt> from <tt>wai-extra</tt>)
--   that does not follow the above recommendation. Therefore, it is
--   recommended that you test the behavior of your application when using
--   <tt>rawPathInfo</tt> and any form of library that might modify the
--   <tt>Request</tt>.
[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 headers (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, <a>isSecure</a> will be
--   <a>False</a>, 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

-- | Get the next chunk of the body. Returns <a>empty</a> when the body is
--   fully consumed. Since 3.2.2, this is deprecated in favor of
--   <a>getRequestBodyChunk</a>.

-- | <i>Deprecated: requestBody's name is misleading because it only gets a
--   partial chunk of the body. Use getRequestBodyChunk instead when
--   getting the field, and setRequestBodyChunks when setting the
--   field.</i>
[requestBody] :: Request -> 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.
[requestBodyLength] :: Request -> RequestBodyLength

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

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

-- | The value of the Referer header in a HTTP request.
[requestHeaderReferer] :: Request -> Maybe ByteString

-- | The value of the User-Agent header in a HTTP request.
[requestHeaderUserAgent] :: Request -> Maybe ByteString

-- | Get the next chunk of the body. Returns <a>empty</a> when the body is
--   fully consumed.
getRequestBodyChunk :: Request -> IO ByteString

-- | Set the <a>requestBody</a> attribute on a request without triggering a
--   deprecation warning.
--   
--   The supplied IO action should return the next chunk of the body each
--   time it is called and <a>empty</a> when it has been fully consumed.
setRequestBodyChunks :: IO ByteString -> Request -> Request
data Response
ResponseFile :: Status -> ResponseHeaders -> FilePath -> Maybe FilePart -> Response
ResponseBuilder :: Status -> ResponseHeaders -> Builder -> Response
ResponseStream :: Status -> ResponseHeaders -> StreamingBody -> Response
ResponseRaw :: (IO ByteString -> (ByteString -> IO ()) -> IO ()) -> Response -> Response

-- | Represents a streaming HTTP response body. It's a function of two
--   parameters; the first parameter provides a means of sending another
--   chunk of data, and the second parameter provides a means of flushing
--   the data to the client.
type StreamingBody = Builder -> IO () -> IO () -> IO ()

-- | The size of the request body. In the case of chunked bodies, the size
--   will not be known.
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

-- | A special datatype to indicate that the WAI handler has received the
--   response. This is to avoid the need for Rank2Types in the definition
--   of Application.
--   
--   It is <i>highly</i> advised that only WAI handlers import and use the
--   data constructor for this data type.
data ResponseReceived
ResponseReceived :: ResponseReceived
instance GHC.Internal.Show.Show Network.Wai.Internal.FilePart
instance GHC.Internal.Show.Show Network.Wai.Internal.Request
instance GHC.Internal.Show.Show Network.Wai.Internal.RequestBodyLength


-- | 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 uses a streaming interface for
--   request and response bodies, paired with bytestring's <a>Builder</a>
--   type. The advantages of a streaming API 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>
--   </ul>
module Network.Wai

-- | The WAI application.
--   
--   Note that, since WAI 3.0, this type is structured in continuation
--   passing style to allow for proper safe resource handling. This was
--   handled in the past via other means (e.g., <tt>ResourceT</tt>). As a
--   demonstration:
--   
--   <pre>
--   app :: Application
--   app req respond = bracket_
--       (putStrLn "Allocating scarce resource")
--       (putStrLn "Cleaning up")
--       (respond $ responseLBS status200 [] "Hello World")
--   </pre>
type Application = Request -> Response -> IO ResponseReceived -> IO ResponseReceived

-- | A <tt>Middleware</tt> is a component that sits between the server and
--   application.
--   
--   It can modify both the <a>Request</a> and <a>Response</a>, to provide
--   simple transformations that are required for all (or most of) your web
--   server’s routes.
--   
--   <h1>Users of middleware</h1>
--   
--   If you are trying to apply one or more <a>Middleware</a>s to your
--   <a>Application</a>, just call them as functions.
--   
--   For example, if you have <tt>corsMiddleware</tt> and
--   <tt>authorizationMiddleware</tt>, and you want to authorize first, you
--   can do:
--   
--   <pre>
--   let allMiddleware app = authorizationMiddleware (corsMiddleware app)
--   </pre>
--   
--   to get a new <a>Middleware</a>, which first authorizes, then sets,
--   CORS headers. The “outer” middleware is called first.
--   
--   You can also chain them via <a>(.)</a>:
--   
--   <pre>
--   let allMiddleware =
--           authorizationMiddleware
--         . corsMiddleware
--         . … more middleware here …
--   </pre>
--   
--   Then, once you have an <tt>app :: Application</tt>, you can wrap it in
--   your middleware:
--   
--   <pre>
--   let myApp = allMiddleware app :: Application
--   </pre>
--   
--   and run it as usual:
--   
--   <pre>
--   Warp.run port myApp
--   </pre>
--   
--   <h1>Authors of middleware</h1>
--   
--   When fully expanded, <a>Middleware</a> has the type signature:
--   
--   <pre>
--   (Request -&gt; (Response -&gt; IO ResponseReceived) -&gt; IO ResponseReceived) -&gt; Request -&gt; (Response -&gt; IO ResponseReceived) -&gt; IO ResponseReceived
--   </pre>
--   
--   or if we shorten to <tt>type Respond = Response -&gt; IO
--   ResponseReceived</tt>:
--   
--   <pre>
--   (Request -&gt; Respond -&gt; IO ResponseReceived) -&gt; Request -&gt; Respond -&gt; IO ResponseReceived
--   </pre>
--   
--   so a middleware definition takes 3 arguments, an inner application, a
--   request and a response callback.
--   
--   Compare with the type of a simple <a>Application</a>:
--   
--   <pre>
--   Request -&gt; Respond -&gt; IO ResponseReceived
--   </pre>
--   
--   It takes the <a>Request</a> and <tt>Respond</tt>, but not the extra
--   application.
--   
--   Said differently, a middleware has the power of a normal
--   <a>Application</a> — it can inspect the <a>Request</a> and return a
--   <a>Response</a> — but it can (and in many cases it <i>should</i>) also
--   call the <a>Application</a> which was passed to it.
--   
--   <h2>Modifying the <a>Request</a></h2>
--   
--   A lot of middleware just looks at the request and does something based
--   on its values.
--   
--   For example, the <tt>authorizationMiddleware</tt> from above could
--   look at the <tt>Authorization</tt> HTTP header and run <a>JWT</a>
--   verification logic against the database.
--   
--   <pre>
--   authorizationMiddleware app req respond = do
--     case verifyJWT (<a>requestHeaders</a> req) of
--       InvalidJWT err -&gt; respond (invalidJWTResponse err)
--       ValidJWT -&gt; app req respond
--   </pre>
--   
--   Notice how the inner app is called when the validation was successful.
--   If it was not, we can respond e.g. with <a>HTTP 401 Unauthorized</a>,
--   by constructing a <a>Response</a> with <a>responseLBS</a> and passing
--   it to <tt>respond</tt>.
--   
--   <h2>Passing arguments to and from your <a>Middleware</a></h2>
--   
--   Middleware must often be configurable. Let’s say you have a type
--   <tt>JWTSettings</tt> that you want to be passed to the middleware.
--   Simply pass an extra argument to your middleware. Then your middleware
--   type turns into:
--   
--   <pre>
--   authorizationMiddleware :: JWTSettings -&gt; Application -&gt; Request -&gt; Respond -&gt; IO ResponseReceived
--   authorizationMiddleware jwtSettings req respond =
--     case verifyJWT jwtSettings (<a>requestHeaders</a> req) of
--       InvalidJWT err -&gt; respond (invalidJWTResponse err)
--       ValidJWT -&gt; app req respond
--   </pre>
--   
--   or alternatively:
--   
--   <pre>
--   authorizationMiddleware :: JWTSettings -&gt; Middleware
--   </pre>
--   
--   Perhaps less intuitively, you can also <i>pass on</i> data from
--   middleware to the wrapped <a>Application</a>:
--   
--   <pre>
--   authorizationMiddleware :: JWTSettings -&gt; (JWT -&gt; Application) -&gt; Request -&gt; Respond -&gt; IO ResponseReceived
--   authorizationMiddleware jwtSettings req respond =
--     case verifyJWT jwtSettings (<a>requestHeaders</a> req) of
--       InvalidJWT err -&gt; respond (invalidJWTResponse err)
--       ValidJWT jwt -&gt; app jwt req respond
--   </pre>
--   
--   although then, chaining different middleware has to take this extra
--   argument into account:
--   
--   <pre>
--   let finalApp =
--         authorizationMiddleware
--           (\jwt -&gt; corsMiddleware
--              (… more middleware here …
--                (app jwt)))
--   </pre>
--   
--   <h2>Modifying the <a>Response</a></h2>
--   
--   <a>Middleware</a> can also modify the <a>Response</a> that is returned
--   by the inner application.
--   
--   This is done by taking the <tt>respond</tt> callback, using it to
--   define a new <tt>respond'</tt>, and passing this new <tt>respond'</tt>
--   to the <tt>app</tt>:
--   
--   <pre>
--   gzipMiddleware app req respond = do
--     let respond' resp = do
--           resp' &lt;- gzipResponseBody resp
--           respond resp'
--     app req respond'
--   </pre>
--   
--   However, modifying the response (especially the response body) is not
--   trivial, so in order to get a sense of how to do it (dealing with the
--   type of <a>responseToStream</a>), it’s best to look at an example, for
--   example <a>the GZIP middleware of wai-extra</a>.
type Middleware = Application -> Application

-- | A special datatype to indicate that the WAI handler has received the
--   response. This is to avoid the need for Rank2Types in the definition
--   of Application.
--   
--   It is <i>highly</i> advised that only WAI handlers import and use the
--   data constructor for this data type.
data ResponseReceived

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

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

-- | The size of the request body. In the case of chunked bodies, the size
--   will not be known.
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.
--   
--   Middlewares and routing tools should not modify this raw value, as it
--   may be used for such things as creating redirect destinations by
--   applications. Instead, if you are writing a middleware or routing
--   framework, modify the <tt>pathInfo</tt> instead. This is the approach
--   taken by systems like Yesod subsites.
--   
--   <i>Note</i>: At the time of writing this documentation, there is at
--   least one system (<tt>Network.Wai.UrlMap</tt> from <tt>wai-extra</tt>)
--   that does not follow the above recommendation. Therefore, it is
--   recommended that you test the behavior of your application when using
--   <tt>rawPathInfo</tt> and any form of library that might modify the
--   <tt>Request</tt>.
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 headers (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, <a>isSecure</a> will be
--   <a>False</a>, 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

-- | Get the next chunk of the body. Returns <a>empty</a> when the body is
--   fully consumed.
getRequestBodyChunk :: Request -> IO ByteString

-- | Get the next chunk of the body. Returns <a>empty</a> when the body is
--   fully consumed. Since 3.2.2, this is deprecated in favor of
--   <a>getRequestBodyChunk</a>.

-- | <i>Deprecated: requestBody's name is misleading because it only gets a
--   partial chunk of the body. Use getRequestBodyChunk instead when
--   getting the field, and setRequestBodyChunks when setting the
--   field.</i>
requestBody :: Request -> 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.
requestBodyLength :: Request -> RequestBodyLength

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

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

-- | The value of the Referer header in a HTTP request.
requestHeaderReferer :: Request -> Maybe ByteString

-- | The value of the User-Agent header in a HTTP request.
requestHeaderUserAgent :: Request -> Maybe ByteString

-- | Get the request body as a lazy ByteString. However, do <i>not</i> use
--   any lazy I/O, instead reading the entire body into memory strictly.
--   
--   Note: Since this function consumes the request body, future calls to
--   it will return the empty string.
strictRequestBody :: Request -> IO ByteString

-- | Synonym for <a>strictRequestBody</a>. This function name is meant to
--   signal the non-idempotent nature of <a>strictRequestBody</a>.
consumeRequestBodyStrict :: Request -> IO 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.
--   
--   Note: Since this function consumes the request body, future calls to
--   it will return the empty string.
lazyRequestBody :: Request -> IO ByteString

-- | Synonym for <a>lazyRequestBody</a>. This function name is meant to
--   signal the non-idempotent nature of <a>lazyRequestBody</a>.
consumeRequestBodyLazy :: Request -> IO ByteString

-- | Set the <a>requestBody</a> attribute on a request without triggering a
--   deprecation warning.
--   
--   The supplied IO action should return the next chunk of the body each
--   time it is called and <a>empty</a> when it has been fully consumed.
setRequestBodyChunks :: IO ByteString -> Request -> Request

-- | Apply the provided function to the request header list of the
--   <a>Request</a>.
mapRequestHeaders :: (RequestHeaders -> RequestHeaders) -> Request -> Request
data Response

-- | Represents a streaming HTTP response body. It's a function of two
--   parameters; the first parameter provides a means of sending another
--   chunk of data, and the second parameter provides a means of flushing
--   the data to the client.
type StreamingBody = Builder -> IO () -> IO () -> IO ()

-- | 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

-- | 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 an insert operation is used to
--   avoid copying.
--   
--   Q3. Doesn't this prevent us from creating comet-style servers, since
--   data will be cached?
--   
--   A3. You can force a 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 stream of values.
--   
--   In order to allocate resources in an exception-safe manner, you can
--   use the <tt>bracket</tt> pattern outside of the call to
--   <tt>responseStream</tt>. As a trivial example:
--   
--   <pre>
--   app :: Application
--   app req respond = bracket_
--       (putStrLn "Allocating scarce resource")
--       (putStrLn "Cleaning up")
--       $ respond $ responseStream status200 [] $ \write flush -&gt; do
--           write $ byteString "Hello\n"
--           flush
--           write $ byteString "World\n"
--   </pre>
--   
--   Note that in some cases you can use <tt>bracket</tt> from inside
--   <tt>responseStream</tt> as well. However, placing the call on the
--   outside allows your status value and response headers to depend on the
--   scarce resource.
responseStream :: Status -> ResponseHeaders -> StreamingBody -> 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.
responseRaw :: (IO ByteString -> (ByteString -> IO ()) -> IO ()) -> Response -> Response

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

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

-- | Converting the body information in <a>Response</a> to a
--   <a>StreamingBody</a>.
responseToStream :: Response -> (Status, ResponseHeaders, (StreamingBody -> IO a) -> IO a)

-- | Apply the provided function to the response header list of the
--   Response.
mapResponseHeaders :: (ResponseHeaders -> ResponseHeaders) -> Response -> Response

-- | Apply the provided function to the response status of the Response.
mapResponseStatus :: (Status -> Status) -> Response -> Response

-- | Conditionally apply a <a>Middleware</a>
ifRequest :: (Request -> Bool) -> Middleware -> Middleware

-- | Apply a function that modifies a request as a <a>Middleware</a>
modifyRequest :: (Request -> Request) -> Middleware

-- | Apply a function that modifies a response as a <a>Middleware</a>
modifyResponse :: (Response -> Response) -> Middleware
