-- 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>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.</li>
--   </ul>
@package warp
@version 1.3.8.2


-- | 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 a Warp server with the given settings.
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 <a>serverPort</a> 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 record syntax to modify individual records.
--   For example:
--   
--   <pre>
--   defaultSettings { settingsTimeout = 20 }
--   </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
settingsPort :: Settings -> Int

-- | 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 -> SomeException -> IO ()

-- | What to do when a connection is open. Default: do nothing.
settingsOnOpen :: Settings -> IO ()

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

-- | Timeout value in seconds. Default value: 30
settingsTimeout :: Settings -> Int
settingsIntercept :: Settings -> Request -> Maybe (Source (ResourceT IO) ByteString -> Connection -> ResourceT IO ())

-- | 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 duratoin time of file descriptors in seconds. 0 means that the
--   cache mechanism is not used. Default value: 10
settingsFdCacheDuration :: Settings -> Int

-- | If <tt>True</tt>, each request/response pair will run in a separate
--   <tt>ResourceT</tt>. This provides more intuitive behavior for dynamic
--   code, but can hinder performance in high-throughput cases. File
--   servers can safely set to <tt>False</tt> for increased performance.
--   Default is <tt>True</tt>.
settingsResourceTPerRequest :: Settings -> Bool

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

-- | Server name to be sent in the Server header.
--   
--   Default: Warp/<i>version</i>
--   
--   Since 1.3.8
settingsServerName :: Settings -> ByteString

-- | 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>*6</tt> means <tt>HostIPv6</tt></li>
--   </ul>
data HostPreference :: *
HostAny :: HostPreference
HostIPv4 :: HostPreference
HostIPv6 :: HostPreference
Host :: String -> HostPreference

-- | 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>
data Connection
Connection :: ([ByteString] -> IO ()) -> (ByteString -> IO ()) -> (FilePath -> Integer -> Integer -> IO () -> [ByteString] -> Cleaner -> IO ()) -> IO () -> IO ByteString -> Connection
connSendMany :: Connection -> [ByteString] -> IO ()
connSendAll :: Connection -> ByteString -> IO ()

-- | offset, length
connSendFile :: Connection -> FilePath -> Integer -> Integer -> IO () -> [ByteString] -> Cleaner -> IO ()
connClose :: Connection -> IO ()
connRecv :: Connection -> IO ByteString
runSettingsConnection :: Settings -> IO (Connection, SockAddr) -> Application -> IO ()

-- | Allows you to provide a function which will return a
--   <tt>Connection</tt>. 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
runSettingsConnectionMaker :: Settings -> IO (IO Connection, SockAddr) -> Application -> IO ()

-- | TCP port number
type Port = Int
data InvalidRequest
NotEnoughLines :: [String] -> InvalidRequest
BadFirstLine :: String -> InvalidRequest
NonHttp :: InvalidRequest
IncompleteHeaders :: InvalidRequest
ConnectionClosedByPeer :: InvalidRequest
OverLargeHeader :: InvalidRequest

-- | A timeout manager
data Manager

-- | A handle used by <a>Manager</a>
--   
--   First field is action to be performed on timeout.
data Handle
initialize :: Int -> IO Manager

-- | Call the inner function with a timeout manager.
withManager :: Int -> (Manager -> IO a) -> IO a
register :: Manager -> IO () -> IO Handle
registerKillThread :: Manager -> IO Handle
pause :: Handle -> IO ()
resume :: Handle -> IO ()
cancel :: Handle -> IO ()
parseRequest :: Connection -> Port -> SockAddr -> Source (ResourceT IO) ByteString -> ResourceT IO (Request, IO (ResumableSource (ResourceT IO) ByteString))
sendResponse :: Settings -> Cleaner -> Request -> Connection -> Response -> ResourceT IO Bool

-- | A dummy <tt>Cleaner</tt>, intended for applications making use of the
--   low-level request parsing and rendering functions.
--   
--   Since 1.3.4
dummyCleaner :: Cleaner

-- | Default action value for <a>Connection</a>
socketConnection :: Socket -> Connection
warpVersion :: String
