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

-- | A logging system for WAI
--   
--   A logging system for WAI(Web Application Interface)
@package wai-logger
@version 2.5.0

-- | Apache style logger for WAI applications.
--   
--   An example:
--   
--   
--   {-# LANGUAGE OverloadedStrings #-}
--   module Main where
--   
--   import Data.ByteString.Builder (byteString)
--   import Control.Monad.IO.Class (liftIO)
--   import qualified Data.ByteString.Char8 as BS
--   import Network.HTTP.Types (status200)
--   import Network.Wai (Application, responseBuilder)
--   import Network.Wai.Handler.Warp (run)
--   import Network.Wai.Logger (withStdoutLogger, ApacheLogger)
--   
--   main :: IO ()
--   main = withStdoutLogger $ \aplogger ->
--       run 3000 $ logApp aplogger
--   
--   logApp :: ApacheLogger -> Application
--   logApp aplogger req response = do
--       liftIO $ aplogger req status (Just len)
--       response $ responseBuilder status hdr msg
--     where
--       status = status200
--       hdr = [("Content-Type", "text/plain")]
--       pong = "PONG"
--       msg = byteString pong
--       len = fromIntegral $ BS.length pong
--   
module Network.Wai.Logger

-- | Apache style logger.
type ApacheLogger = Request -> Status -> Maybe Integer -> IO ()

-- | Executing a function which takes ApacheLogger. This
--   ApacheLogger writes log message to stdout. Each buffer (4K
--   bytes) is flushed every second.
withStdoutLogger :: (ApacheLogger -> IO a) -> IO a

-- | HTTP/2 server push logger in Apache style.
type ServerPushLogger = Request -> ByteString -> Integer -> IO ()

-- | Function set of Apache style logger.
data ApacheLoggerActions

-- | The Apache logger.
apacheLogger :: ApacheLoggerActions -> ApacheLogger

-- | The HTTP/2 server push logger.
serverpushLogger :: ApacheLoggerActions -> ServerPushLogger

-- | This is obsoleted. Rotation is done on-demand. So, this is now an
--   empty action.
logRotator :: ApacheLoggerActions -> IO ()

-- | Removing resources relating to Apache logger. E.g. flushing and
--   deallocating internal buffers.
logRemover :: ApacheLoggerActions -> IO ()

-- | Creating ApacheLogger according to LogType.
initLoggerUser :: ToLogStr user => Maybe (Request -> Maybe user) -> IPAddrSource -> LogType -> IO FormattedTime -> IO ApacheLoggerActions
initLogger :: IPAddrSource -> LogType -> IO FormattedTime -> IO ApacheLoggerActions

-- | Source from which the IP source address of the client is obtained.
data IPAddrSource

-- | From the peer address of the HTTP connection.
FromSocket :: IPAddrSource

-- | From X-Real-IP or X-Forwarded-For in the HTTP
--   header.
--   
--   This picks either X-Real-IP or X-Forwarded-For
--   depending on which of these headers comes first in the ordered list of
--   request headers.
--   
--   If the X-Forwarded-For header is picked, the value will be
--   assumed to be a comma-separated list of IP addresses. The value will
--   be parsed, and the left-most IP address will be used (which is mostly
--   likely to be the actual client IP address).
FromHeader :: IPAddrSource

-- | From a custom HTTP header, useful in proxied environment.
--   
--   The header value will be assumed to be a comma-separated list of IP
--   addresses. The value will be parsed, and the left-most IP address will
--   be used (which is mostly likely to be the actual client IP address).
--   
--   Note that this still works as expected for a single IP address.
FromHeaderCustom :: [HeaderName] -> IPAddrSource

-- | Just like FromHeader, but falls back on the peer address if
--   header is not found.
FromFallback :: IPAddrSource

-- | This gives you the most flexibility to figure out the IP source
--   address from the Request. The returned ByteString is
--   used as the IP source address.
FromRequest :: (Request -> ByteString) -> IPAddrSource

-- | Logger Type.
data LogType' a
[LogNone] :: LogType' LogStr
[LogStdout] :: BufSize -> LogType' LogStr
[LogStderr] :: BufSize -> LogType' LogStr
[LogFileNoRotate] :: FilePath -> BufSize -> LogType' LogStr
[LogFile] :: FileLogSpec -> BufSize -> LogType' LogStr
[LogFileTimedRotate] :: TimedFileLogSpec -> BufSize -> LogType' LogStr
[LogCallback] :: forall a. (a -> IO ()) -> IO () -> LogType' a
type LogType = LogType' LogStr

-- | The spec for logging files
data FileLogSpec
FileLogSpec :: FilePath -> Integer -> Int -> FileLogSpec
[log_file] :: FileLogSpec -> FilePath

-- | Max log file size (in bytes) before requiring rotation.
[log_file_size] :: FileLogSpec -> Integer

-- | Max number of rotated log files to keep around before overwriting the
--   oldest one.
[log_backup_number] :: FileLogSpec -> Int

-- | Convert SockAddr to NumericAddress. If the address is
--   IPv4-embedded IPv6 address, the IPv4 is extracted.
showSockAddr :: SockAddr -> NumericAddress
logCheck :: LogType -> IO ()

-- | Returning DateCacheGetter and DateCacheUpdater.
--   
--   Note: Since version 2.1.2, this function uses the auto-update package
--   internally, and therefore the DateCacheUpdater value returned
--   need not be called. To wit, the return value is in fact an empty
--   action.
clockDateCacher :: IO (DateCacheGetter, DateCacheUpdater)

-- | A type for zoned date.
type ZonedDate = FormattedTime

-- | Getting cached ZonedDate.
type DateCacheGetter = IO ZonedDate

-- | Updateing cached ZonedDate. This should be called every second.
--   See the source code of withStdoutLogger.
type DateCacheUpdater = IO ()
