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


-- | A fast, light-weight web server for WAI applications.
--   
--   HTTP/1.0, HTTP/1.1 and HTTP/2 are supported. For HTTP/2, Warp supports
--   direct and ALPN (in TLS) but not upgrade. API docs and the README are
--   available at <a>http://www.stackage.org/package/warp</a>.
@package warp
@version 3.2.21

module Network.Wai.Handler.Warp.Internal

-- | Various Warp server settings. This is purposely kept as an abstract
--   data type so that new settings can be added without breaking backwards
--   compatibility. In order to create a <a>Settings</a> value, use
--   <a>defaultSettings</a> and the various 'set' functions to modify
--   individual fields. For example:
--   
--   <pre>
--   setTimeout 20 defaultSettings
--   </pre>
data Settings
Settings :: Port -> HostPreference -> (Maybe Request -> SomeException -> IO ()) -> (SomeException -> Response) -> (SockAddr -> IO Bool) -> (SockAddr -> IO ()) -> Int -> Maybe Manager -> Int -> Int -> IO () -> (((forall a. IO a -> IO a) -> IO ()) -> IO ()) -> Bool -> (IO () -> IO ()) -> ByteString -> Maybe Int -> ProxyProtocol -> Int -> Bool -> (Request -> Status -> Maybe Integer -> IO ()) -> (Request -> ByteString -> Integer -> IO ()) -> Maybe Int -> Settings

-- | Port to listen on. Default value: 3000
[settingsPort] :: Settings -> Port

-- | Default value: HostIPv4
[settingsHost] :: Settings -> HostPreference

-- | What to do with exceptions thrown by either the application or server.
--   Default: ignore server-generated exceptions (see
--   <a>InvalidRequest</a>) and print application-generated applications to
--   stderr.
[settingsOnException] :: Settings -> Maybe Request -> SomeException -> IO ()

-- | A function to create <a>Response</a> when an exception occurs.
--   
--   Default: 500, text/plain, "Something went wrong"
--   
--   Since 2.0.3
[settingsOnExceptionResponse] :: Settings -> SomeException -> Response

-- | What to do when a connection is open. When <a>False</a> is returned,
--   the connection is closed immediately. Otherwise, the connection is
--   going on. Default: always returns <a>True</a>.
[settingsOnOpen] :: Settings -> SockAddr -> IO Bool

-- | What to do when a connection is close. Default: do nothing.
[settingsOnClose] :: Settings -> SockAddr -> IO ()

-- | Timeout value in seconds. Default value: 30
[settingsTimeout] :: Settings -> Int

-- | Use an existing timeout manager instead of spawning a new one. If
--   used, <a>settingsTimeout</a> is ignored. Default is <a>Nothing</a>
[settingsManager] :: Settings -> Maybe Manager

-- | Cache duration time of file descriptors in seconds. 0 means that the
--   cache mechanism is not used. Default value: 0
[settingsFdCacheDuration] :: Settings -> Int

-- | Cache duration time of file information in seconds. 0 means that the
--   cache mechanism is not used. Default value: 0
[settingsFileInfoCacheDuration] :: Settings -> Int

-- | Code to run after the listening socket is ready but before entering
--   the main event loop. Useful for signaling to tests that they can start
--   running, or to drop permissions after binding to a restricted port.
--   
--   Default: do nothing.
--   
--   Since 1.3.6
[settingsBeforeMainLoop] :: Settings -> IO ()

-- | Code to fork a new thread to accept a connection.
--   
--   This may be useful if you need OS bound threads, or if you wish to
--   develop an alternative threading model.
--   
--   Default: void . forkIOWithUnmask
--   
--   Since 3.0.4
[settingsFork] :: Settings -> ((forall a. IO a -> IO a) -> IO ()) -> IO ()

-- | Perform no parsing on the rawPathInfo.
--   
--   This is useful for writing HTTP proxies.
--   
--   Default: False
--   
--   Since 2.0.3
[settingsNoParsePath] :: Settings -> Bool
[settingsInstallShutdownHandler] :: Settings -> IO () -> IO ()

-- | Default server name if application does not set one.
--   
--   Since 3.0.2
[settingsServerName] :: Settings -> ByteString

-- | See <tt>setMaximumBodyFlush</tt>.
--   
--   Since 3.0.3
[settingsMaximumBodyFlush] :: Settings -> Maybe Int

-- | Specify usage of the PROXY protocol.
--   
--   Since 3.0.5.
[settingsProxyProtocol] :: Settings -> ProxyProtocol

-- | Size of bytes read to prevent Slowloris protection. Default value:
--   2048
--   
--   Since 3.1.2.
[settingsSlowlorisSize] :: Settings -> Int

-- | Whether to enable HTTP2 ALPN/upgrades. Default: True
--   
--   Since 3.1.7.
[settingsHTTP2Enabled] :: Settings -> Bool

-- | A log function. Default: no action.
--   
--   Since 3.X.X.
[settingsLogger] :: Settings -> Request -> Status -> Maybe Integer -> IO ()

-- | A HTTP/2 server push log function. Default: no action.
--   
--   Since 3.X.X.
[settingsServerPushLogger] :: Settings -> Request -> ByteString -> Integer -> IO ()

-- | An optional timeout to limit the time (in seconds) waiting for a
--   graceful shutdown of the web server.
--   
--   Since 3.2.8
[settingsGracefulShutdownTimeout] :: Settings -> Maybe Int

-- | Specify usage of the PROXY protocol.
data ProxyProtocol

-- | See <tt>setProxyProtocolNone</tt>.
ProxyProtocolNone :: ProxyProtocol

-- | See <tt>setProxyProtocolRequired</tt>.
ProxyProtocolRequired :: ProxyProtocol

-- | See <tt>setProxyProtocolOptional</tt>.
ProxyProtocolOptional :: ProxyProtocol

-- | The connection setup action would be expensive. A good example is
--   initialization of TLS. So, this converts the connection setup action
--   to the connection maker which will be executed after forking a new
--   worker thread. Then this calls <a>runSettingsConnectionMaker</a> with
--   the connection maker. This allows the expensive computations to be
--   performed in a separate worker thread instead of the main server loop.
--   
--   Since 1.3.5
runSettingsConnection :: Settings -> IO (Connection, SockAddr) -> Application -> IO ()

-- | This modifies the connection maker so that it returns <a>TCP</a> for
--   <a>Transport</a> (i.e. plain HTTP) then calls
--   <a>runSettingsConnectionMakerSecure</a>.
runSettingsConnectionMaker :: Settings -> IO (IO Connection, SockAddr) -> Application -> IO ()

-- | The core run function which takes <a>Settings</a>, a connection maker
--   and <a>Application</a>. The connection maker can return a connection
--   of either plain HTTP or HTTP over TLS.
--   
--   Since 2.1.4
runSettingsConnectionMakerSecure :: Settings -> IO (IO (Connection, Transport), SockAddr) -> Application -> IO ()

-- | What kind of transport is used for this connection?
data Transport

-- | Plain channel: TCP
TCP :: Transport

-- | Encrypted channel: TLS or SSL
TLS :: Int -> Int -> Maybe ByteString -> Word16 -> Transport
[tlsMajorVersion] :: Transport -> Int
[tlsMinorVersion] :: Transport -> Int

-- | The result of Application Layer Protocol Negociation in RFC 7301
[tlsNegotiatedProtocol] :: Transport -> Maybe ByteString
[tlsChiperID] :: Transport -> Word16

-- | Data type to manipulate IO actions for connections. This is used to
--   abstract IO actions for plain HTTP and HTTP over TLS.
data Connection
Connection :: ([ByteString] -> IO ()) -> (ByteString -> IO ()) -> SendFile -> IO () -> IO () -> Recv -> RecvBuf -> Buffer -> BufSize -> Connection

-- | This is not used at this moment.
[connSendMany] :: Connection -> [ByteString] -> IO ()

-- | The sending function.
[connSendAll] :: Connection -> ByteString -> IO ()

-- | The sending function for files in HTTP/1.1.
[connSendFile] :: Connection -> SendFile

-- | The connection closing function. Warp guarantees it will only be
--   called once. Other functions (like <a>connRecv</a>) may be called
--   after <a>connClose</a> is called.
[connClose] :: Connection -> IO ()

-- | Free any buffers allocated. Warp guarantees it will only be called
--   once, and no other functions will be called after it.
[connFree] :: Connection -> IO ()

-- | The connection receiving function. This returns "" for EOF.
[connRecv] :: Connection -> Recv

-- | The connection receiving function. This tries to fill the buffer. This
--   returns when the buffer is filled or reaches EOF.
[connRecvBuf] :: Connection -> RecvBuf

-- | The write buffer.
[connWriteBuffer] :: Connection -> Buffer

-- | The size of the write buffer.
[connBufferSize] :: Connection -> BufSize

-- | Creating <a>Connection</a> for plain HTTP based on a given socket.
socketConnection :: Socket -> IO Connection

-- | Type for the action to receive input data
type Recv = IO ByteString

-- | Type for the action to receive input data with a buffer. The result
--   boolean indicates whether or not the buffer is fully filled.
type RecvBuf = Buffer -> BufSize -> IO Bool

-- | This function returns a receiving function based on two receiving
--   functions. The returned function efficiently manages received data
--   which is initialized by the first argument. The returned function may
--   allocate a byte string with malloc().
makePlainReceiveN :: Socket -> ByteString -> IO (BufSize -> IO ByteString)

-- | Type for buffer
type Buffer = Ptr Word8

-- | Type for buffer size
type BufSize = Int

-- | The default size of the write buffer: 16384 (2^14 = 1024 * 16). This
--   is the maximum size of TLS record. This is also the maximum size of
--   HTTP/2 frame payload (excluding frame header).
bufferSize :: BufSize

-- | Allocating a buffer with malloc().
allocateBuffer :: Int -> IO Buffer

-- | Releasing a buffer with free().
freeBuffer :: Buffer -> IO ()

-- | Copying the bytestring to the buffer. This function returns the point
--   where the next copy should start.
copy :: Buffer -> ByteString -> IO Buffer

-- | Data type to abstract file identifiers. On Unix, a file descriptor
--   would be specified to make use of the file descriptor cache.
--   
--   Since: 3.1.0
data FileId
FileId :: FilePath -> Maybe Fd -> FileId
[fileIdPath] :: FileId -> FilePath
[fileIdFd] :: FileId -> Maybe Fd

-- | fileid, offset, length, hook action, HTTP headers
--   
--   Since: 3.1.0
type SendFile = FileId -> Integer -> Integer -> IO () -> [ByteString] -> IO ()

-- | Function to send a file based on sendfile() for Linux/Mac/FreeBSD.
--   This makes use of the file descriptor cache. For other OSes, this is
--   identical to <a>readSendFile</a>.
--   
--   Since: 3.1.0
sendFile :: Socket -> Buffer -> BufSize -> (ByteString -> IO ()) -> SendFile

-- | Function to send a file based on pread()/send() for Unix. This makes
--   use of the file descriptor cache. For Windows, this is emulated by
--   <tt>Handle</tt>.
--   
--   Since: 3.1.0
readSendFile :: Buffer -> BufSize -> (ByteString -> IO ()) -> SendFile

-- | The version of Warp.
warpVersion :: String
data InternalInfo
InternalInfo :: Handle -> Manager -> IO GMTDate -> (FilePath -> IO (Maybe Fd, Refresh)) -> (FilePath -> IO FileInfo) -> InternalInfo
[threadHandle] :: InternalInfo -> Handle
[timeoutManager] :: InternalInfo -> Manager
[getDate] :: InternalInfo -> IO GMTDate
[getFd] :: InternalInfo -> FilePath -> IO (Maybe Fd, Refresh)
[getFileInfo] :: InternalInfo -> FilePath -> IO FileInfo

-- | The type for header value used with <tt>HeaderName</tt>.
type HeaderValue = ByteString

-- | Array for a set of HTTP headers.
type IndexedHeader = Array Int (Maybe HeaderValue)

-- | The size for <a>IndexedHeader</a> for HTTP Request. From 0 to this
--   corresponds to "Content-Length", "Transfer-Encoding", "Expect",
--   "Connection", "Range", "Host", "If-Modified-Since",
--   "If-Unmodified-Since" and "If-Range".
requestMaxIndex :: Int

-- | A timeout manager
type Manager = Reaper [Handle] Handle

-- | An action to be performed on timeout.
type TimeoutAction = IO ()

-- | A handle used by <a>Manager</a>
data Handle

-- | Creating timeout manager which works every N micro seconds where N is
--   the first argument.
initialize :: Int -> IO Manager

-- | Stopping timeout manager with onTimeout fired.
stopManager :: Manager -> IO ()

-- | Killing timeout manager immediately without firing onTimeout.
killManager :: Manager -> IO ()

-- | Call the inner function with a timeout manager.
withManager :: Int -> (Manager -> IO a) -> IO a

-- | Registering a timeout action.
register :: Manager -> TimeoutAction -> IO Handle

-- | Registering a timeout action of killing this thread.
registerKillThread :: Manager -> TimeoutAction -> IO Handle

-- | Setting the state to active. <a>Manager</a> turns active to inactive
--   repeatedly.
tickle :: Handle -> IO ()

-- | Setting the state to canceled. <a>Manager</a> eventually removes this
--   without timeout action.
cancel :: Handle -> IO ()

-- | Setting the state to paused. <a>Manager</a> does not change the value.
pause :: Handle -> IO ()

-- | Setting the paused state to active. This is an alias to <a>tickle</a>.
resume :: Handle -> IO ()
data TimeoutThread
TimeoutThread :: TimeoutThread

-- | Creating <a>MutableFdCache</a> and executing the action in the second
--   argument. The first argument is a cache duration in second.
withFdCache :: Int -> ((Hash -> FilePath -> IO (Maybe Fd, Refresh)) -> IO a) -> IO a
data Fd :: *

-- | An action to activate a Fd cache entry.
type Refresh = IO ()
openFile :: FilePath -> IO Fd
closeFile :: Fd -> IO ()
setFileCloseOnExec :: Fd -> IO ()

-- | File information.
data FileInfo
FileInfo :: !FilePath -> !Integer -> HTTPDate -> ByteString -> FileInfo
[fileInfoName] :: FileInfo -> !FilePath
[fileInfoSize] :: FileInfo -> !Integer

-- | Modification time
[fileInfoTime] :: FileInfo -> HTTPDate

-- | Modification time in the GMT format
[fileInfoDate] :: FileInfo -> ByteString
type Hash = Int

-- | Creating a file information cache and executing the action in the
--   second argument. The first argument is a cache duration in second.
withFileInfoCache :: Int -> ((Hash -> FilePath -> IO FileInfo) -> IO a) -> IO a

-- | Getting the file information corresponding to the file.
getInfo :: FilePath -> IO FileInfo

-- | Creating <tt>DateCache</tt> and executing the action.
withDateCache :: (IO GMTDate -> IO a) -> IO a

-- | The type of the Date header value.
type GMTDate = ByteString

-- | Type for input streaming.
data Source

-- | Receiving a HTTP request from <a>Connection</a> and parsing its header
--   to create <a>Request</a>.
recvRequest :: Bool -> Settings -> Connection -> InternalInfo1 -> SockAddr -> Source -> IO (Request, Maybe (IORef Int), IndexedHeader, IO ByteString, InternalInfo)

-- | Sending a HTTP response to <a>Connection</a> according to
--   <a>Response</a>.
--   
--   Applications/middlewares MUST provide a proper <a>ResponseHeaders</a>.
--   so that inconsistency does not happen. No header is deleted by this
--   function.
--   
--   Especially, Applications/middlewares MUST provide a proper
--   Content-Type. They MUST NOT provide Content-Length, Content-Range, and
--   Transfer-Encoding because they are inserted, when necessary,
--   regardless they already exist. This function does not insert
--   Content-Encoding. It's middleware's responsibility.
--   
--   The Date and Server header is added if not exist in HTTP response
--   header.
--   
--   There are three basic APIs to create <a>Response</a>:
--   
--   <ul>
--   <li><i><a>responseBuilder</a> :: <a>Status</a> -&gt;
--   <a>ResponseHeaders</a> -&gt; <a>Builder</a> -&gt; <a>Response</a></i>
--   HTTP response body is created from <a>Builder</a>. Transfer-Encoding:
--   chunked is used in HTTP/1.1.</li>
--   <li><i><a>responseStream</a> :: <a>Status</a> -&gt;
--   <a>ResponseHeaders</a> -&gt; <a>StreamingBody</a> -&gt;
--   <a>Response</a></i> HTTP response body is created from <a>Builder</a>.
--   Transfer-Encoding: chunked is used in HTTP/1.1.</li>
--   <li><i><a>responseRaw</a> :: (<a>IO</a> <a>ByteString</a> -&gt;
--   (<a>ByteString</a> -&gt; <a>IO</a> ()) -&gt; <a>IO</a> ()) -&gt;
--   <a>Response</a> -&gt; <a>Response</a></i> No header is added and no
--   Transfer-Encoding: is applied.</li>
--   <li><i><a>responseFile</a> :: <a>Status</a> -&gt;
--   <a>ResponseHeaders</a> -&gt; <a>FilePath</a> -&gt; <a>Maybe</a>
--   <a>FilePart</a> -&gt; <a>Response</a></i> HTTP response body is sent
--   (by sendfile(), if possible) for GET method. HTTP response body is not
--   sent by HEAD method. Content-Length and Content-Range are
--   automatically added into the HTTP response header if necessary. If
--   Content-Length and Content-Range exist in the HTTP response header,
--   they would cause inconsistency. "Accept-Ranges: bytes" is also
--   inserted.</li>
--   </ul>
--   
--   Applications are categorized into simple and sophisticated.
--   Sophisticated applications should specify <a>Just</a> to <a>Maybe</a>
--   <a>FilePart</a>. They should treat the conditional request by
--   themselves. A proper <tt>Status</tt> (200 or 206) must be provided.
--   
--   Simple applications should specify <a>Nothing</a> to <a>Maybe</a>
--   <a>FilePart</a>. The size of the specified file is obtained by disk
--   access or from the file infor cache. If-Modified-Since,
--   If-Unmodified-Since, If-Range and Range are processed. Since a proper
--   status is chosen, <tt>Status</tt> is ignored. Last-Modified is
--   inserted.
sendResponse :: Settings -> Connection -> InternalInfo -> Request -> IndexedHeader -> IO ByteString -> Response -> IO Bool

-- | Set flag FileCloseOnExec flag on a socket (on Unix)
--   
--   Copied from:
--   <a>https://github.com/mzero/plush/blob/master/src/Plush/Server/Warp.hs</a>
setSocketCloseOnExec :: Socket -> IO ()
windowsThreadBlockHack :: IO a -> IO a


-- | A fast, light-weight HTTP server handler for WAI.
--   
--   HTTP/1.0, HTTP/1.1 and HTTP/2 are supported. For HTTP/2, Warp supports
--   direct and ALPN (in TLS) but not upgrade.
--   
--   Note on slowloris timeouts: to prevent slowloris attacks, timeouts are
--   used at various points in request receiving and response sending. One
--   interesting corner case is partial request body consumption; in that
--   case, Warp's timeout handling is still in effect, and the timeout will
--   not be triggered again. Therefore, it is recommended that once you
--   start consuming the request body, you either:
--   
--   <ul>
--   <li>consume the entire body promptly</li>
--   <li>call the <a>pauseTimeout</a> function</li>
--   </ul>
--   
--   For more information, see
--   <a>https://github.com/yesodweb/wai/issues/351</a>.
module Network.Wai.Handler.Warp

-- | Run an <a>Application</a> on the given port. This calls
--   <a>runSettings</a> with <a>defaultSettings</a>.
run :: Port -> Application -> IO ()

-- | Run an <a>Application</a> on the port present in the <tt>PORT</tt>
--   environment variable. Uses the <a>Port</a> given when the variable is
--   unset. This calls <a>runSettings</a> with <a>defaultSettings</a>.
--   
--   Since 3.0.9
runEnv :: Port -> Application -> IO ()

-- | Run an <a>Application</a> with the given <a>Settings</a>. This opens a
--   listen socket on the port defined in <a>Settings</a> and calls
--   <a>runSettingsSocket</a>.
runSettings :: Settings -> Application -> IO ()

-- | This installs a shutdown handler for the given socket and calls
--   <a>runSettingsConnection</a> with the default connection setup action
--   which handles plain (non-cipher) HTTP. When the listen socket in the
--   second argument is closed, all live connections are gracefully shut
--   down.
--   
--   The supplied socket can be a Unix named socket, which can be used when
--   reverse HTTP proxying into your application.
--   
--   Note that the <a>settingsPort</a> will still be passed to
--   <a>Application</a>s via the <tt>serverPort</tt> record.
runSettingsSocket :: Settings -> Socket -> Application -> IO ()

-- | Various Warp server settings. This is purposely kept as an abstract
--   data type so that new settings can be added without breaking backwards
--   compatibility. In order to create a <a>Settings</a> value, use
--   <a>defaultSettings</a> and the various 'set' functions to modify
--   individual fields. For example:
--   
--   <pre>
--   setTimeout 20 defaultSettings
--   </pre>
data Settings

-- | The default settings for the Warp server. See the individual settings
--   for the default value.
defaultSettings :: Settings

-- | Port to listen on. Default value: 3000
--   
--   Since 2.1.0
setPort :: Port -> Settings -> Settings

-- | Interface to bind to. Default value: HostIPv4
--   
--   Since 2.1.0
setHost :: HostPreference -> Settings -> Settings

-- | What to do with exceptions thrown by either the application or server.
--   Default: <a>defaultOnException</a>
--   
--   Since 2.1.0
setOnException :: (Maybe Request -> SomeException -> IO ()) -> Settings -> Settings

-- | A function to create a <a>Response</a> when an exception occurs.
--   Default: <a>defaultOnExceptionResponse</a>
--   
--   Note that an application can handle its own exceptions without
--   interfering with Warp:
--   
--   <pre>
--   myApp :: Application
--   myApp request respond = innerApp `catch` onError
--     where
--       onError = respond . response500 request
--   
--   response500 :: Request -&gt; SomeException -&gt; Response
--   response500 req someEx = responseLBS status500 -- ...
--   </pre>
--   
--   Since 2.1.0
setOnExceptionResponse :: (SomeException -> Response) -> Settings -> Settings

-- | What to do when a connection is opened. When <a>False</a> is returned,
--   the connection is closed immediately. Otherwise, the connection is
--   going on. Default: always returns <a>True</a>.
--   
--   Since 2.1.0
setOnOpen :: (SockAddr -> IO Bool) -> Settings -> Settings

-- | What to do when a connection is closed. Default: do nothing.
--   
--   Since 2.1.0
setOnClose :: (SockAddr -> IO ()) -> Settings -> Settings

-- | Timeout value in seconds. Default value: 30
--   
--   Since 2.1.0
setTimeout :: Int -> Settings -> Settings

-- | Use an existing timeout manager instead of spawning a new one. If
--   used, <a>settingsTimeout</a> is ignored.
--   
--   Since 2.1.0
setManager :: Manager -> Settings -> Settings

-- | Cache duration time of file descriptors in seconds. 0 means that the
--   cache mechanism is not used.
--   
--   The FD cache is an optimization that is useful for servers dealing
--   with static files. However, if files are being modified, it can cause
--   incorrect results in some cases. Therefore, we disable it by default.
--   If you know that your files will be static or you prefer performance
--   to file consistency, it's recommended to turn this on; a reasonable
--   value for those cases is 10. Enabling this cache results in drastic
--   performance improvement for file transfers.
--   
--   Default value: 0, was previously 10
--   
--   Since 3.0.13
setFdCacheDuration :: Int -> Settings -> Settings

-- | Cache duration time of file information in seconds. 0 means that the
--   cache mechanism is not used.
--   
--   The file information cache is an optimization that is useful for
--   servers dealing with static files. However, if files are being
--   modified, it can cause incorrect results in some cases. Therefore, we
--   disable it by default. If you know that your files will be static or
--   you prefer performance to file consistency, it's recommended to turn
--   this on; a reasonable value for those cases is 10. Enabling this cache
--   results in drastic performance improvement for file transfers.
--   
--   Default value: 0
setFileInfoCacheDuration :: Int -> Settings -> Settings

-- | Code to run after the listening socket is ready but before entering
--   the main event loop. Useful for signaling to tests that they can start
--   running, or to drop permissions after binding to a restricted port.
--   
--   Default: do nothing.
--   
--   Since 2.1.0
setBeforeMainLoop :: IO () -> Settings -> Settings

-- | Perform no parsing on the rawPathInfo.
--   
--   This is useful for writing HTTP proxies.
--   
--   Default: False
--   
--   Since 2.1.0
setNoParsePath :: Bool -> Settings -> Settings

-- | A code to install shutdown handler.
--   
--   For instance, this code should set up a UNIX signal handler. The
--   handler should call the first argument, which closes the listen
--   socket, at shutdown.
--   
--   Example usage:
--   
--   <pre>
--   settings :: IO () -&gt; <a>Settings</a>
--   settings shutdownAction = <a>setInstallShutdownHandler</a> shutdownHandler <a>defaultSettings</a>
--     <b>where</b>
--       shutdownHandler closeSocket =
--         void $ <a>installHandler</a> <a>sigTERM</a> (<a>Catch</a> $ shutdownAction &gt;&gt; closeSocket) <a>Nothing</a>
--   </pre>
--   
--   Default: does not install any code.
--   
--   Since 3.0.1
setInstallShutdownHandler :: (IO () -> IO ()) -> Settings -> Settings

-- | Default server name to be sent as the "Server:" header if an
--   application does not set one. If an empty string is set, the "Server:"
--   header is not sent. This is true even if an application set one.
--   
--   Since 3.0.2
setServerName :: ByteString -> Settings -> Settings

-- | The maximum number of bytes to flush from an unconsumed request body.
--   
--   By default, Warp does not flush the request body so that, if a large
--   body is present, the connection is simply terminated instead of
--   wasting time and bandwidth on transmitting it. However, some clients
--   do not deal with that situation well. You can either change this
--   setting to <tt>Nothing</tt> to flush the entire body in all cases, or
--   in your application ensure that you always consume the entire request
--   body.
--   
--   Default: 8192 bytes.
--   
--   Since 3.0.3
setMaximumBodyFlush :: Maybe Int -> Settings -> Settings

-- | Code to fork a new thread to accept a connection.
--   
--   This may be useful if you need OS bound threads, or if you wish to
--   develop an alternative threading model.
--   
--   Default: void . forkIOWithUnmask
--   
--   Since 3.0.4
setFork :: (((forall a. IO a -> IO a) -> IO ()) -> IO ()) -> Settings -> Settings

-- | Do not use the PROXY protocol.
--   
--   Since 3.0.5
setProxyProtocolNone :: Settings -> Settings

-- | Require PROXY header.
--   
--   This is for cases where a "dumb" TCP/SSL proxy is being used, which
--   cannot add an <tt>X-Forwarded-For</tt> HTTP header field but has
--   enabled support for the PROXY protocol.
--   
--   See <a>http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt</a>
--   and
--   <a>http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/TerminologyandKeyConcepts.html#proxy-protocol</a>.
--   
--   Only the human-readable header format (version 1) is supported. The
--   binary header format (version 2) is <i>not</i> supported.
--   
--   Since 3.0.5
setProxyProtocolRequired :: Settings -> Settings

-- | Use the PROXY header if it exists, but also accept connections without
--   the header. See <a>setProxyProtocolRequired</a>.
--   
--   WARNING: This is contrary to the PROXY protocol specification and
--   using it can indicate a security problem with your architecture if the
--   web server is directly accessable to the public, since it would allow
--   easy IP address spoofing. However, it can be useful in some cases,
--   such as if a load balancer health check uses regular HTTP without the
--   PROXY header, but proxied connections <i>do</i> include the PROXY
--   header.
--   
--   Since 3.0.5
setProxyProtocolOptional :: Settings -> Settings

-- | Size in bytes read to prevent Slowloris attacks. Default value: 2048
--   
--   Since 3.1.2
setSlowlorisSize :: Int -> Settings -> Settings

-- | Disable HTTP2.
--   
--   Since 3.1.7
setHTTP2Disabled :: Settings -> Settings

-- | Setting a log function.
--   
--   Since 3.X.X
setLogger :: (Request -> Status -> Maybe Integer -> IO ()) -> Settings -> Settings

-- | Setting a log function for HTTP/2 server push.
--   
--   Since: 3.2.7
setServerPushLogger :: (Request -> ByteString -> Integer -> IO ()) -> Settings -> Settings

-- | Set the graceful shutdown timeout. A timeout of <a>Nothing</a> will
--   wait indefinitely, and a number, if provided, will be treated as
--   seconds to wait for requests to finish, before shutting down the
--   server entirely.
--   
--   Since 3.2.8
setGracefulShutdownTimeout :: Maybe Int -> Settings -> Settings

-- | Get the listening port.
--   
--   Since 2.1.1
getPort :: Settings -> Port

-- | Get the interface to bind to.
--   
--   Since 2.1.1
getHost :: Settings -> HostPreference

-- | Get the action on opening connection.
getOnOpen :: Settings -> SockAddr -> IO Bool

-- | Get the action on closeing connection.
getOnClose :: Settings -> SockAddr -> IO ()

-- | Get the exception handler.
getOnException :: Settings -> Maybe Request -> SomeException -> IO ()

-- | Get the graceful shutdown timeout
--   
--   Since 3.2.8
getGracefulShutdownTimeout :: Settings -> Maybe Int

-- | Printing an exception to standard error if
--   <a>defaultShouldDisplayException</a> returns <a>True</a>.
--   
--   Since: 3.1.0
defaultOnException :: Maybe Request -> SomeException -> IO ()

-- | Apply the logic provided by <a>defaultOnException</a> to determine if
--   an exception should be shown or not. The goal is to hide exceptions
--   which occur under the normal course of the web server running.
--   
--   Since 2.1.3
defaultShouldDisplayException :: SomeException -> Bool

-- | Sending 400 for bad requests. Sending 500 for internal server errors.
--   
--   Since: 3.1.0
defaultOnExceptionResponse :: SomeException -> Response

-- | Exception handler for the debugging purpose. 500, text/plain, a showed
--   exception.
--   
--   Since: 2.0.3.2
exceptionResponseForDebug :: SomeException -> Response

-- | Which host to bind.
--   
--   Note: The <tt>IsString</tt> instance recognizes the following special
--   values:
--   
--   <ul>
--   <li><tt>*</tt> means <tt>HostAny</tt> - "any IPv4 or IPv6
--   hostname"</li>
--   <li><tt>*4</tt> means <tt>HostIPv4</tt> - "any IPv4 or IPv6 hostname,
--   IPv4 preferred"</li>
--   <li><tt>!4</tt> means <tt>HostIPv4Only</tt> - "any IPv4 hostname"</li>
--   <li><tt>*6</tt> means <tt>HostIPv6</tt>@ - "any IPv4 or IPv6 hostname,
--   IPv6 preferred"</li>
--   <li><tt>!6</tt> means <tt>HostIPv6Only</tt> - "any IPv6 hostname"</li>
--   </ul>
--   
--   Note that the permissive <tt>*</tt> values allow binding to an IPv4 or
--   an IPv6 hostname, which means you might be able to successfully bind
--   to a port more times than you expect (eg once on the IPv4 localhost
--   127.0.0.1 and again on the IPv6 localhost 0:0:0:0:0:0:0:1).
--   
--   Any other value is treated as a hostname. As an example, to bind to
--   the IPv4 local host only, use "127.0.0.1".
data HostPreference :: *

-- | TCP port number.
type Port = Int

-- | Error types for bad <tt>Request</tt>.
data InvalidRequest
NotEnoughLines :: [String] -> InvalidRequest
BadFirstLine :: String -> InvalidRequest
NonHttp :: InvalidRequest
IncompleteHeaders :: InvalidRequest
ConnectionClosedByPeer :: InvalidRequest
OverLargeHeader :: InvalidRequest
BadProxyHeader :: String -> InvalidRequest

-- | Explicitly pause the slowloris timeout.
--   
--   This is useful for cases where you partially consume a request body.
--   For more information, see
--   <a>https://github.com/yesodweb/wai/issues/351</a>
--   
--   Since 3.0.10
pauseTimeout :: Request -> IO ()

-- | File information.
data FileInfo
FileInfo :: !FilePath -> !Integer -> HTTPDate -> ByteString -> FileInfo
[fileInfoName] :: FileInfo -> !FilePath
[fileInfoSize] :: FileInfo -> !Integer

-- | Modification time
[fileInfoTime] :: FileInfo -> HTTPDate

-- | Modification time in the GMT format
[fileInfoDate] :: FileInfo -> ByteString

-- | Getting file information of the target file.
--   
--   This function first uses a stat(2) or similar system call to obtain
--   information of the target file, then registers it into the internal
--   cache. From the next time, the information is obtained from the cache.
--   This reduces the overhead to call the system call. The internal cache
--   is refreshed every duration specified by
--   <a>setFileInfoCacheDuration</a>.
--   
--   This function throws an <a>IO</a> exception if the information is not
--   available. For instance, the target file does not exist. If this
--   function is used an a Request generated by a WAI backend besides Warp,
--   it also throws an <a>IO</a> exception.
--   
--   Since 3.1.10
getFileInfo :: Request -> FilePath -> IO FileInfo

-- | Runs the given <a>Application</a> on a free port. Passes the port to
--   the given operation and executes it, while the <a>Application</a> is
--   running. Shuts down the server before returning.
withApplication :: IO Application -> (Port -> IO a) -> IO a

-- | <a>withApplication</a> with given <a>Settings</a>. This will ignore
--   the port value set by <tt>setPort</tt> in <a>Settings</a>.
withApplicationSettings :: Settings -> IO Application -> (Port -> IO a) -> IO a

-- | Same as <a>withApplication</a> but with different exception handling:
--   If the given <a>Application</a> throws an exception,
--   <a>testWithApplication</a> will re-throw the exception to the calling
--   thread, possibly interrupting the execution of the given operation.
--   
--   This is handy for running tests against an <a>Application</a> over a
--   real network port. When running tests, it's useful to let exceptions
--   thrown by your <a>Application</a> propagate to the main thread of the
--   test-suite.
--   
--   <b>The exception handling makes this function unsuitable for use in
--   production.</b> Use <a>withApplication</a> instead.
testWithApplication :: IO Application -> (Port -> IO a) -> IO a

-- | <a>testWithApplication</a> with given <a>Settings</a>.
testWithApplicationSettings :: Settings -> IO Application -> (Port -> IO a) -> IO a

-- | Opens a socket on a free port and returns both port and socket.
openFreePort :: IO (Port, Socket)

-- | The version of Warp.
warpVersion :: String

-- | HTTP/2 specific data.
--   
--   Since: 3.2.7
data HTTP2Data

-- | Accessor for <a>PushPromise</a> in <a>HTTP2Data</a>.
--   
--   Since: 3.2.7
http2dataPushPromise :: HTTP2Data -> [PushPromise]
http2dataTrailers :: HTTP2Data -> ResponseHeaders

-- | Default HTTP/2 specific data.
--   
--   Since: 3.2.7
defaultHTTP2Data :: HTTP2Data

-- | Getting <a>HTTP2Data</a> through vault of the request. Warp uses this
--   to receive <a>HTTP2Data</a> from <a>Middleware</a>.
--   
--   Since: 3.2.7
getHTTP2Data :: Request -> IO (Maybe HTTP2Data)

-- | Setting <a>HTTP2Data</a> through vault of the request.
--   <a>Application</a> or <a>Middleware</a> should use this.
--   
--   Since: 3.2.7
setHTTP2Data :: Request -> Maybe HTTP2Data -> IO ()

-- | Modifying <a>HTTP2Data</a> through vault of the request.
--   <a>Application</a> or <a>Middleware</a> should use this.
--   
--   Since: 3.2.8
modifyHTTP2Data :: Request -> (Maybe HTTP2Data -> Maybe HTTP2Data) -> IO ()

-- | HTTP/2 push promise or sever push.
--   
--   Since: 3.2.7
data PushPromise

-- | Accessor for a URL path in <a>PushPromise</a>. E.g.
--   "/style/default.css".
--   
--   Since: 3.2.7
promisedPath :: PushPromise -> ByteString

-- | Accessor for <a>FilePath</a> in <a>PushPromise</a>. E.g.
--   "FILE_PATH/default.css".
--   
--   Since: 3.2.7
promisedFile :: PushPromise -> FilePath

-- | Accessor for <a>ResponseHeaders</a> in <a>PushPromise</a>
--   "content-type" must be specified. Default value: [].
--   
--   Since: 3.2.7
promisedResponseHeaders :: PushPromise -> ResponseHeaders

-- | Accessor for <a>Weight</a> in <a>PushPromise</a>. Default value: 16.
--   
--   Since: 3.2.7
promisedWeight :: PushPromise -> Weight

-- | Default push promise.
--   
--   Since: 3.2.7
defaultPushPromise :: PushPromise