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


-- | A fast, iteratee-based, epoll-enabled web server for the Snap Framework
--   
--   Snap is a simple and fast web development framework and server written
--   in Haskell. For more information or to download the latest version,
--   you can visit the Snap project website at
--   <a>http://snapframework.com/</a>.
--   
--   The Snap HTTP server is a high performance, epoll-enabled,
--   iteratee-based web server library written in Haskell. Together with
--   the <tt>snap-core</tt> library upon which it depends, it provides a
--   clean and efficient Haskell programming interface to the HTTP
--   protocol.
@package snap-server
@version 0.8.1.1

module System.FastLogger

-- | Holds the state for a logger.
data Logger

-- | Prepares a log message with the time prepended.
timestampedLogEntry :: ByteString -> IO ByteString

-- | Prepares a log message in "combined" format.
combinedLogEntry :: ByteString -> Maybe ByteString -> ByteString -> Int -> Maybe Int64 -> Maybe ByteString -> ByteString -> IO ByteString

-- | Creates a new logger, logging to the given file. If the file argument
--   is "-", then log to stdout; if it's "stderr" then we log to stderr,
--   otherwise we log to a regular file in append mode. The file is closed
--   and re-opened every 15 minutes to facilitate external log rotation.
newLogger :: FilePath -> IO Logger

-- | Like <a>newLogger</a>, but uses a custom error action if the logger
--   needs to print an error message of its own (for instance, if it can't
--   open the output file.)
newLoggerWithCustomErrorFunction :: (ByteString -> IO ()) -> FilePath -> IO Logger

-- | Sends out a log message verbatim with a newline appended. Note: if you
--   want a fancy log message you'll have to format it yourself (or use
--   <a>combinedLogEntry</a>).
logMsg :: Logger -> ByteString -> IO ()

-- | Kills a logger thread, causing any unwritten contents to be flushed
--   out to disk
stopLogger :: Logger -> IO ()


-- | This module exports the <a>Config</a> datatype, which you can use to
--   configure the Snap HTTP server.
module Snap.Http.Server.Config

-- | A record type which represents partial configurations (for
--   <tt>httpServe</tt>) by wrapping all of its fields in a <a>Maybe</a>.
--   Values of this type are usually constructed via its <a>Monoid</a>
--   instance by doing something like:
--   
--   <pre>
--   setPort 1234 mempty
--   </pre>
--   
--   Any fields which are unspecified in the <a>Config</a> passed to
--   <tt>httpServe</tt> (and this is the norm) are filled in with default
--   values from <a>defaultConfig</a>.
data Config m a

-- | This datatype allows you to override which backend (either simple or
--   libev) to use. Most users will not want to set this, preferring to
--   rely on the compile-type default.
--   
--   Note that if you specify the libev backend and have not compiled in
--   support for it, your server will fail at runtime.
data ConfigBackend
ConfigSimpleBackend :: ConfigBackend
ConfigLibEvBackend :: ConfigBackend

-- | Data type representing the configuration of a logging target
data ConfigLog

-- | no logging
ConfigNoLog :: ConfigLog

-- | log to text file
ConfigFileLog :: FilePath -> ConfigLog

-- | log custom IO handler
ConfigIoLog :: (ByteString -> IO ()) -> ConfigLog

-- | Returns a completely empty <a>Config</a>. Equivalent to <a>mempty</a>
--   from <tt>Config'</tt>s <a>Monoid</a> instance.
emptyConfig :: Config m a

-- | These are the default values for the options
defaultConfig :: MonadSnap m => Config m a

-- | Returns a <a>Config</a> obtained from parsing command-line options,
--   using the default Snap <a>OptDescr</a> set.
--   
--   On Unix systems, the locale is read from the <tt>LANG</tt> environment
--   variable.
commandLineConfig :: MonadSnap m => Config m a -> IO (Config m a)

-- | Returns a <a>Config</a> obtained from parsing command-line options,
--   using the default Snap <a>OptDescr</a> set as well as a list of user
--   OptDescrs. User OptDescrs use the "other" field (accessible using
--   <a>getOther</a> and <a>setOther</a>) to store additional command-line
--   option state. These are combined using a user-defined combining
--   function.
--   
--   On Unix systems, the locale is read from the <tt>LANG</tt> environment
--   variable.
extendedCommandLineConfig :: MonadSnap m => [OptDescr (Maybe (Config m a))] -> (a -> a -> a) -> Config m a -> IO (Config m a)
completeConfig :: MonadSnap m => Config m a -> IO (Config m a)

-- | Returns a description of the snap command line options suitable for
--   use with <a>System.Console.GetOpt</a>.
optDescrs :: MonadSnap m => Config m a -> [OptDescr (Maybe (Config m a))]
fmapOpt :: (a -> b) -> OptDescr a -> OptDescr b

-- | Path to the access log
getAccessLog :: Config m a -> Maybe ConfigLog
getBackend :: Config m a -> Maybe ConfigBackend

-- | Returns the address to bind to (for http)
getBind :: Config m a -> Maybe ByteString

-- | If set and set to True, compression is turned on when applicable
getCompression :: Config m a -> Maybe Bool
getDefaultTimeout :: Config m a -> Maybe Int

-- | A MonadSnap action to handle 500 errors
getErrorHandler :: Config m a -> Maybe (SomeException -> m ())

-- | Path to the error log
getErrorLog :: Config m a -> Maybe ConfigLog

-- | The hostname of the HTTP server. This field has the same format as an
--   HTTP <tt>Host</tt> header; if a <tt>Host</tt> header came in with the
--   request, we use that, otherwise we default to this value specified in
--   the configuration.
getHostname :: Config m a -> Maybe ByteString

-- | Gets the locale to use. Locales are used on Unix only, to set the
--   <tt>LANG</tt>/<tt>LC_ALL</tt>/etc. environment variable. For instance
--   if you set the locale to "<tt>en_US</tt>", we'll set the relevant
--   environment variables to "<tt>en_US.UTF-8</tt>".
getLocale :: Config m a -> Maybe String
getOther :: Config m a -> Maybe a

-- | Returns the port to listen on (for http)
getPort :: Config m a -> Maybe Int
getProxyType :: Config m a -> Maybe ProxyType

-- | Returns the address to bind to (for https)
getSSLBind :: Config m a -> Maybe ByteString

-- | Path to the SSL certificate file
getSSLCert :: Config m a -> Maybe FilePath

-- | Path to the SSL key file
getSSLKey :: Config m a -> Maybe FilePath

-- | Returns the port to listen on (for https)
getSSLPort :: Config m a -> Maybe Int

-- | Whether to write server status updates to stderr
getVerbose :: Config m a -> Maybe Bool
setAccessLog :: ConfigLog -> Config m a -> Config m a
setBackend :: ConfigBackend -> Config m a -> Config m a
setBind :: ByteString -> Config m a -> Config m a
setCompression :: Bool -> Config m a -> Config m a
setDefaultTimeout :: Int -> Config m a -> Config m a
setErrorHandler :: (SomeException -> m ()) -> Config m a -> Config m a
setErrorLog :: ConfigLog -> Config m a -> Config m a
setHostname :: ByteString -> Config m a -> Config m a
setLocale :: String -> Config m a -> Config m a
setOther :: a -> Config m a -> Config m a
setPort :: Int -> Config m a -> Config m a
setProxyType :: ProxyType -> Config m a -> Config m a
setSSLBind :: ByteString -> Config m a -> Config m a
setSSLCert :: FilePath -> Config m a -> Config m a
setSSLKey :: FilePath -> Config m a -> Config m a
setSSLPort :: Int -> Config m a -> Config m a
setVerbose :: Bool -> Config m a -> Config m a
instance Show ConfigBackend
instance Eq ConfigBackend
instance Typeable1 m => Typeable1 (Config m)
instance Monoid (Config m a)
instance Show (Config m a)
instance Show ConfigLog


-- | The Snap HTTP server is a high performance, epoll-enabled,
--   iteratee-based web server library written in Haskell. Together with
--   the <tt>snap-core</tt> library upon which it depends, it provides a
--   clean and efficient Haskell programming interface to the HTTP
--   protocol.
module Snap.Http.Server

-- | Starts serving HTTP requests using the given handler. This function
--   never returns; to shut down the HTTP server, kill the controlling
--   thread.
--   
--   This function is like <a>httpServe</a> except it doesn't setup
--   compression, reverse proxy address translation (via
--   <a>behindProxy</a>), or the error handler; this allows it to be used
--   from <a>MonadSnap</a>.
simpleHttpServe :: MonadSnap m => Config m a -> Snap () -> IO ()

-- | Starts serving HTTP requests using the given handler, with settings
--   from the <a>Config</a> passed in. This function never returns; to shut
--   down the HTTP server, kill the controlling thread.
httpServe :: Config Snap a -> Snap () -> IO ()

-- | Starts serving HTTP using the given handler. The configuration is read
--   from the options given on the command-line, as returned by
--   <a>commandLineConfig</a>. This function never returns; to shut down
--   the HTTP server, kill the controlling thread.
quickHttpServe :: Snap () -> IO ()

-- | A short string describing the Snap server version
snapServerVersion :: ByteString

-- | Given a string like "en_US", this sets the locale to "en_US.UTF-8".
--   This doesn't work on Windows.
setUnicodeLocale :: String -> IO ()