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


-- | Web Application Interface.
--   
--   API docs and the README are available at
--   <a>http://www.stackage.org/package/wai</a>.
@package wai
@version 3.0.5.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 -> 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.
--   
--   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.
[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.
--   
--   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
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.
--   
--   Since 3.0.0
type StreamingBody = (Builder -> IO ()) -> IO () -> IO ()

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

-- | 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.
--   
--   Since 3.0.0
data ResponseReceived
ResponseReceived :: ResponseReceived

-- | Look up the size of a file in <a>Right</a> or the <a>IOException</a>
--   in <a>Left</a>.
tryGetFileSize :: FilePath -> IO (Either IOException Integer)

-- | "Content-Range".
hContentRange :: HeaderName

-- | "Accept-Ranges".
hAcceptRanges :: HeaderName

-- | <tt>contentRangeHeader beg end total</tt> constructs a Content-Range
--   <a>Header</a> for the range specified.
contentRangeHeader :: Integer -> Integer -> Integer -> Header

-- | Given the full size of a file and optionally a Range header value,
--   determine the range to serve by parsing the range header and obeying
--   it, or serving the whole file if it's absent or malformed.
chooseFilePart :: Integer -> Maybe ByteString -> FilePart

-- | Adjust the given <a>Status</a> and <a>ResponseHeaders</a> based on the
--   given <a>FilePart</a>. This means replacing the status with 206 if the
--   response is partial, and adding the Content-Length and Accept-Ranges
--   (always) and Content-Range (if appropriate) headers.
adjustForFilePart :: Status -> ResponseHeaders -> FilePart -> (Status, ResponseHeaders)

-- | Parse the value of a Range header into a <a>ByteRanges</a>.
parseByteRanges :: ByteString -> Maybe ByteRanges
instance GHC.Show.Show Network.Wai.Internal.FilePart
instance GHC.Show.Show Network.Wai.Internal.RequestBodyLength
instance GHC.Show.Show Network.Wai.Internal.Request


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

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

-- | 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.
--   
--   Since 3.0.0
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.
--   
--   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.
--   
--   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.
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.
--   
--   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. However, do <i>not</i> use
--   any lazy I/O, instead reading the entire body into memory strictly.
--   
--   Since 3.0.1
strictRequestBody :: 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.
--   
--   Since 1.4.1
lazyRequestBody :: Request -> IO ByteString
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.
--   
--   Since 3.0.0
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 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 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 $ fromByteString "Hello\n"
--           flush
--           write $ fromByteString "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.
--   
--   Since 3.0.0
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.
--   
--   Since 2.1.0
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

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

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


-- | An HTTP/2-aware variant of the <a>Application</a> type. Compared to
--   the original, this exposes the new functionality of server push and
--   trailers, allows stream fragments to be sent in the form of file
--   ranges, and allows the stream body to produce a value to be used in
--   constructing the trailers. Existing <tt>Applications</tt> can be
--   faithfully upgraded to HTTP/2 with <a>promoteApplication</a> or served
--   transparently over both protocols with the normal Warp <a>run</a>
--   family of functions.
--   
--   An <a>HTTP2Application</a> takes a <a>Request</a> and a
--   <a>PushFunc</a> and produces a <a>Responder</a> that will push any
--   associated resources and send the response body. The response is
--   always a stream of <a>Builder</a>s and file chunks. Equivalents of the
--   <a>responseBuilder</a> family of functions are provided for creating
--   <a>Responder</a>s conveniently.
--   
--   Pushed streams are handled by an IO action that triggers a server
--   push. It returns <tt>True</tt> if the <tt>PUSH_PROMISE</tt> frame was
--   sent, <tt>False</tt> if not. Note this means it will still return
--   <tt>True</tt> if the client reset or ignored the stream. This gives
--   handlers the freedom to implement their own heuristics for whether to
--   actually push a resource, while also allowing middleware and
--   frameworks to trigger server pushes automatically.
module Network.Wai.HTTP2

-- | The HTTP/2-aware equivalent of <a>Application</a>.
type HTTP2Application = Request -> PushFunc -> Responder

-- | The result of an <a>HTTP2Application</a>; or, alternately, an
--   application that's independent of the request. This is a
--   continuation-passing style function that first provides a response by
--   calling the given respond function, then returns the request's
--   <a>Trailers</a>.
--   
--   The respond function is similar to the one in <a>Application</a>, but
--   it only takes a streaming body, the status and headers are curried,
--   and it also produces trailers for the stream.
newtype Responder
Responder :: (forall s. RespondFunc s -> IO s) -> Responder
[runResponder] :: Responder -> forall s. RespondFunc s -> IO s

-- | Given to <tt>Responders</tt>; provide a status, headers, and a stream
--   body, and we'll give you a token proving you called the
--   <a>RespondFunc</a>.
type RespondFunc s = Status -> ResponseHeaders -> Body -> IO s

-- | The streaming body of a response. Equivalent to <a>StreamingBody</a>
--   except that it can also write file ranges and return the stream's
--   trailers.
type Body = (Chunk -> IO ()) -> IO () -> IO Trailers

-- | Part of a streaming response -- either a <a>Builder</a> or a range of
--   a file.
data Chunk
FileChunk :: FilePath -> FilePart -> Chunk
BuilderChunk :: Builder -> Chunk

-- | Headers sent after the end of a data stream, as defined by section
--   4.1.2 of the HTTP/1.1 spec (RFC 7230), and section 8.1 of the HTTP/2
--   spec.
type Trailers = [Header]

-- | A function given to an <a>HTTP2Application</a> to initiate a
--   server-pushed stream. Its argument is the same as the result of an
--   <a>HTTP2Application</a>, so you can either implement the response
--   inline, or call your own application to create the response.
--   
--   The result is <a>True</a> if the <tt>PUSH_PROMISE</tt> frame will be
--   sent, or <a>False</a> if it will not. This can happen if server push
--   is disabled, the concurrency limit of server-initiated streams is
--   reached, or the associated stream has already been closed.
--   
--   This function shall ensure that stream data provided after it returns
--   will be sent after the <tt>PUSH_PROMISE</tt> frame, so that servers
--   can implement the requirement that any pushed stream for a resource be
--   initiated before sending DATA frames that reference it.
type PushFunc = PushPromise -> Responder -> IO Bool

-- | The synthesized request and headers of a pushed stream.
data PushPromise
PushPromise :: Method -> ByteString -> ByteString -> ByteString -> RequestHeaders -> PushPromise
[promisedMethod] :: PushPromise -> Method
[promisedPath] :: PushPromise -> ByteString
[promisedAuthority] :: PushPromise -> ByteString
[promisedScheme] :: PushPromise -> ByteString
[promisedHeader] :: PushPromise -> RequestHeaders

-- | Create the <a>RequestHeaders</a> corresponding to the given
--   <a>PushPromise</a>.
--   
--   This is primarily useful for WAI handlers like Warp, and application
--   implementers are unlikely to use it directly.
promiseHeaders :: PushPromise -> RequestHeaders

-- | Promote a normal WAI <a>Application</a> to an <a>HTTP2Application</a>
--   by ignoring the HTTP/2-specific features.
promoteApplication :: Application -> HTTP2Application

-- | Construct a <a>Responder</a> that will just call the
--   <a>RespondFunc</a> with the given arguments.
respond :: Status -> ResponseHeaders -> Body -> Responder

-- | Fold the <a>ContT</a> into the contained <a>Responder</a>.
respondCont :: (forall r. ContT r IO Responder) -> Responder

-- | Fold the <a>IO</a> into the contained <a>Responder</a>.
respondIO :: IO Responder -> Responder

-- | Serve the requested range of the specified file (based on the Range
--   header), using the given <a>Status</a> and <a>ResponseHeaders</a> as a
--   base. If the file is not accessible, the status will be replaced with
--   404 and a default not-found message will be served. If a partial file
--   is requested, the status will be replaced with 206 and the
--   Content-Range header will be added. The Content-Length header will
--   always be added.
respondFile :: Status -> ResponseHeaders -> FilePath -> RequestHeaders -> Responder

-- | Respond with a single range of a file, adding the Accept-Ranges,
--   Content-Length and Content-Range headers and changing the status to
--   206 as appropriate.
--   
--   If you want the range to be inferred automatically from the Range
--   header, use <a>respondFile</a> instead. On the other hand, if you want
--   to avoid the automatic header and status adjustments, use
--   <a>respond</a> and <a>streamFilePart</a> directly.
respondFilePart :: Status -> ResponseHeaders -> FilePath -> FilePart -> Responder

-- | Respond with a minimal 404 page with the given headers.
respondNotFound :: ResponseHeaders -> Responder

-- | Fold the given bracketing action into a <a>Responder</a>. Note the
--   first argument is isomorphic to <tt>Codensity IO a</tt> or <tt>forall
--   s. ContT s IO a</tt>, and is the type of a partially-applied
--   <a>bracket</a> or <tt>with</tt>-style function.
--   
--   <pre>
--   respondWith (bracket acquire release) $
--       \x -&gt; respondNotFound [("x", show x)]
--   </pre>
--   
--   is equivalent to
--   
--   <pre>
--   Responder $ \k -&gt; bracket acquire release $
--       \x -&gt; runResponder (respondNotFound [("x", show x)] k
--   </pre>
--   
--   This is morally equivalent to (<a>&gt;&gt;=</a>) on <tt>Codensity</tt>
--   <a>IO</a>.
respondWith :: (forall s. (a -> IO s) -> IO s) -> (a -> Responder) -> Responder

-- | Create a response body consisting of a single range of a file. Does
--   not set Content-Length or Content-Range headers. For that, use
--   <a>respondFilePart</a> or <a>respondFile</a>.
streamFilePart :: FilePath -> FilePart -> Body

-- | Create a response body consisting of a single builder.
streamBuilder :: Builder -> Body

-- | Create a response body of a stream of <a>Builder</a>s.
streamSimple :: StreamingBody -> Body
instance GHC.Show.Show Network.Wai.HTTP2.RespondNeverCalled
instance GHC.Exception.Exception Network.Wai.HTTP2.RespondNeverCalled
