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


-- | A fast, light-weight web server for WAI applications.
--   
--   The premier WAI handler. For more information, see
--   <a>http://steve.vinoski.net/blog/2011/05/01/warp-a-haskell-web-server/</a>.
--   
--   Changelog
--   
--   <ul>
--   <li><i>3.0.0</i> WAI no longer uses conduit for its streaming
--   interface.</li>
--   <li><i>2.1.0</i> The <tt>onOpen</tt> and <tt>onClose</tt> settings now
--   provide the <tt>SockAddr</tt> of the client, and <tt>onOpen</tt> can
--   return a <tt>Bool</tt> which will close the connection. The
--   <tt>responseRaw</tt> response has been added, which provides a more
--   elegant way to handle WebSockets than the previous
--   <tt>settingsIntercept</tt>. The old settings accessors have been
--   deprecated in favor of new setters, which will allow settings changes
--   to be made in the future without breaking backwards
--   compatibility.</li>
--   <li><i>2.0.0</i> ResourceT is not used anymore. Request and Response
--   is now abstract data types. To use their constructors, Internal module
--   should be imported.</li>
--   <li><i>1.3.9</i> Support for byte range requests.</li>
--   <li><i>1.3.7</i> Sockets now have FD_CLOEXEC set on them. This
--   behavior is more secure, and the change should not affect the vast
--   majority of use cases. However, it appeared that this is buggy and is
--   fixed in 2.0.0.</li>
--   </ul>
@package warp
@version 3.0.0.5

module Network.Wai.Handler.Warp.Buffer
type Buffer = Ptr Word8
type BufSize = Int
bufferSize :: BufSize
allocateBuffer :: Int -> IO Buffer
freeBuffer :: Buffer -> IO ()
toBlazeBuffer :: Buffer -> BufSize -> IO Buffer


-- | In order to provide slowloris protection, Warp provides timeout
--   handlers. We follow these rules:
--   
--   <ul>
--   <li>A timeout is created when a connection is opened.</li>
--   <li>When all request headers are read, the timeout is tickled.</li>
--   <li>Every time at least 2048 bytes of the request body are read, the
--   timeout is tickled.</li>
--   <li>The timeout is paused while executing user code. This will apply
--   to both the application itself, and a ResponseSource response. The
--   timeout is resumed as soon as we return from user code.</li>
--   <li>Every time data is successfully sent to the client, the timeout is
--   tickled.</li>
--   </ul>
module Network.Wai.Handler.Warp.Timeout

-- | A timeout manager
data Manager

-- | 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.
stopManager :: 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 -> 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
instance Typeable TimeoutThread
instance Show TimeoutThread
instance Exception TimeoutThread

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 :: Int -> HostPreference -> (Maybe Request -> SomeException -> IO ()) -> (SomeException -> Response) -> (SockAddr -> IO Bool) -> (SockAddr -> IO ()) -> Int -> Maybe Manager -> Int -> IO () -> Bool -> Settings

-- | Port to listen on. Default value: 3000

-- | <i>Deprecated: Use setPort instead</i>
settingsPort :: Settings -> Int

-- | Default value: HostIPv4

-- | <i>Deprecated: Use setHost instead</i>
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.

-- | <i>Deprecated: Use setOnException instead</i>
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

-- | <i>Deprecated: Use setOnExceptionResponse instead</i>
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>.

-- | <i>Deprecated: Use setOnOpen instead</i>
settingsOnOpen :: Settings -> SockAddr -> IO Bool

-- | What to do when a connection is close. Default: do nothing.

-- | <i>Deprecated: Use setOnClose instead</i>
settingsOnClose :: Settings -> SockAddr -> IO ()

-- | Timeout value in seconds. Default value: 30

-- | <i>Deprecated: Use setTimeout instead</i>
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>

-- | <i>Deprecated: Use setManager instead</i>
settingsManager :: Settings -> Maybe Manager

-- | Cache duratoin time of file descriptors in seconds. 0 means that the
--   cache mechanism is not used. Default value: 10

-- | <i>Deprecated: Use setFdCacheDuration instead</i>
settingsFdCacheDuration :: 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

-- | <i>Deprecated: Use setBeforeMainLoop instead</i>
settingsBeforeMainLoop :: Settings -> IO ()

-- | Perform no parsing on the rawPathInfo.
--   
--   This is useful for writing HTTP proxies.
--   
--   Default: False
--   
--   Since 2.0.3

-- | <i>Deprecated: Use setNoParsePath instead</i>
settingsNoParsePath :: Settings -> Bool
getOnOpen :: Settings -> SockAddr -> IO Bool
getOnClose :: Settings -> SockAddr -> IO ()
getOnException :: Settings -> Maybe Request -> SomeException -> IO ()


-- | A fast, light-weight HTTP server handler for WAI.
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> with the given <a>Settings</a>.
runSettings :: Settings -> Application -> IO ()

-- | Same as <a>runSettings</a>, but uses a user-supplied socket instead of
--   opening one. This allows the user to provide, for example, 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 ()

-- | Allows you to provide a function which will return a
--   <a>Connection</a>. In cases where creating the <tt>Connection</tt> can
--   be expensive, this allows the expensive computations to be performed
--   in a separate thread instead of the main server loop.
--   
--   Since 1.3.5
runSettingsConnection :: Settings -> IO (Connection, SockAddr) -> Application -> IO ()
runSettingsConnectionMaker :: Settings -> IO (IO Connection, SockAddr) -> Application -> IO ()

-- | Allows you to provide a function which will return a function which
--   will return <a>Connection</a>.
--   
--   Since 2.1.4
runSettingsConnectionMakerSecure :: Settings -> IO (IO (Connection, Bool), SockAddr) -> 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 :: Int -> 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: ignore server-generated exceptions (see
--   <a>InvalidRequest</a>) and print application-generated applications to
--   stderr.
--   
--   Since 2.1.0
setOnException :: (Maybe Request -> SomeException -> IO ()) -> Settings -> Settings

-- | A function to create a <a>Response</a> when an exception occurs.
--   
--   Default: 500, text/plain, "Something went wrong"
--   
--   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. Default value: 10
setFdCacheDuration :: 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

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

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

-- | Port to listen on. Default value: 3000

-- | <i>Deprecated: Use setPort instead</i>
settingsPort :: Settings -> Int

-- | Default value: HostIPv4

-- | <i>Deprecated: Use setHost instead</i>
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.

-- | <i>Deprecated: Use setOnException instead</i>
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

-- | <i>Deprecated: Use setOnExceptionResponse instead</i>
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>.

-- | <i>Deprecated: Use setOnOpen instead</i>
settingsOnOpen :: Settings -> SockAddr -> IO Bool

-- | What to do when a connection is close. Default: do nothing.

-- | <i>Deprecated: Use setOnClose instead</i>
settingsOnClose :: Settings -> SockAddr -> IO ()

-- | Timeout value in seconds. Default value: 30

-- | <i>Deprecated: Use setTimeout instead</i>
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>

-- | <i>Deprecated: Use setManager instead</i>
settingsManager :: Settings -> Maybe Manager

-- | Cache duratoin time of file descriptors in seconds. 0 means that the
--   cache mechanism is not used. Default value: 10

-- | <i>Deprecated: Use setFdCacheDuration instead</i>
settingsFdCacheDuration :: 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

-- | <i>Deprecated: Use setBeforeMainLoop instead</i>
settingsBeforeMainLoop :: Settings -> IO ()

-- | Perform no parsing on the rawPathInfo.
--   
--   This is useful for writing HTTP proxies.
--   
--   Default: False
--   
--   Since 2.0.3

-- | <i>Deprecated: Use setNoParsePath instead</i>
settingsNoParsePath :: Settings -> Bool

-- | Default implementation of <a>settingsOnExceptionResponse</a> for the
--   debugging purpose. 500, text/plain, a showed exception.
exceptionResponseForDebug :: SomeException -> Response

-- | Apply the logic provided by <a>defaultExceptionHandler</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

-- | Which host to bind.
--   
--   Note: The <tt>IsString</tt> instance recognizes the following special
--   values:
--   
--   <ul>
--   <li><tt>*</tt> means <tt>HostAny</tt></li>
--   <li><tt>*4</tt> means <tt>HostIPv4</tt></li>
--   <li><tt>!4</tt> means <tt>HostIPv4Only</tt></li>
--   <li><tt>*6</tt> means <tt>HostIPv6</tt></li>
--   <li><tt>!6</tt> means <tt>HostIPv6Only</tt></li>
--   </ul>
--   
--   Any other values 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

-- | Whether or not <a>ConnSendFileOverride</a> in <a>Connection</a> can be
--   overridden. This is a kind of hack to keep the signature of
--   <a>Connection</a> clean.
data ConnSendFileOverride

-- | Don't override
NotOverride :: ConnSendFileOverride

-- | Override with this <a>Socket</a>
Override :: Socket -> ConnSendFileOverride

-- | Data type to manipulate IO actions for connections.
data Connection
Connection :: ([ByteString] -> IO ()) -> (ByteString -> IO ()) -> (FilePath -> Integer -> Integer -> IO () -> [ByteString] -> IO ()) -> IO () -> IO ByteString -> Buffer -> Buffer -> BufSize -> ConnSendFileOverride -> Connection
connSendMany :: Connection -> [ByteString] -> IO ()
connSendAll :: Connection -> ByteString -> IO ()

-- | filepath, offset, length, hook action, HTTP headers
connSendFile :: Connection -> FilePath -> Integer -> Integer -> IO () -> [ByteString] -> IO ()
connClose :: Connection -> IO ()
connRecv :: Connection -> IO ByteString
connReadBuffer :: Connection -> Buffer
connWriteBuffer :: Connection -> Buffer
connBufferSize :: Connection -> BufSize
connSendFileOverride :: Connection -> ConnSendFileOverride

-- | Default action value for <a>Connection</a>.
socketConnection :: Socket -> IO Connection

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

-- | Internal information.
data InternalInfo
InternalInfo :: Handle -> Maybe MutableFdCache -> DateCache -> InternalInfo
threadHandle :: InternalInfo -> Handle
fdCacher :: InternalInfo -> Maybe MutableFdCache
dateCacher :: InternalInfo -> DateCache

-- | The type for header value used with <a>HeaderName</a>.
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", and "Host".
requestMaxIndex :: Int

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

-- | Getting <a>Fd</a> and <a>Refresh</a> from the mutable Fd cacher.
getFd :: MutableFdCache -> FilePath -> IO (Fd, Refresh)

-- | Mutable Fd cacher.
data MutableFdCache

-- | An action to activate a Fd cache entry.
type Refresh = IO ()

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

-- | Getting <a>GMTDate</a> based on <a>DateCache</a>.
getDate :: DateCache -> IO GMTDate

-- | The type of the cache of the Date header value.
data DateCache

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

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

-- | Sending a HTTP response to <a>Connection</a> according to
--   <a>Response</a>.
--   
--   Applications/middlewares MUST specify a proper <a>ResponseHeaders</a>.
--   so that inconsistency does not happen. No header is deleted by this
--   function.
--   
--   Especially, Applications/middlewares MUST take care of 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>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(). Applications are categorized into simple and
--   sophisticated. 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. Then Range is handled. Sophisticated
--   applications should specify <a>Just</a> to <a>Maybe</a>
--   <a>FilePart</a>. They should treat Range (and If-Range) by
--   thierselves. In both cases, Content-Length and Content-Range (if
--   necessary) are automatically added into the HTTP response header. If
--   Content-Length and Content-Range exist in the HTTP response header,
--   they would cause inconsistency. Status is also changed to 206 if
--   necessary.</li>
--   <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>Source</a>. Typically,
--   Transfer-Encoding: chunked is used. If Content-Length is specified,
--   Transfer-Encoding: chunked is not used.</li>
--   <li><i><tt>responseSource</tt> :: <a>Status</a> -&gt;
--   <a>ResponseHeaders</a> -&gt; <a>Source</a> <a>IO</a> (<tt>Flush</tt>
--   <a>Builder</a>) -&gt; <a>Response</a></i> HTTP response body is
--   created from <a>Builder</a>. Typically, Transfer-Encoding: chunked is
--   used. If Content-Length is specified, Transfer-Encoding: chunked is
--   not used.</li>
--   </ul>
sendResponse :: Connection -> InternalInfo -> Request -> IndexedHeader -> IO ByteString -> Response -> IO Bool
