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


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


-- | Apache style logger for WAI applications.
--   
--   An example:
--   
--   <pre>
--   {-# 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 -&gt;
--       run 3000 $ logApp aplogger
--   
--   logApp :: ApacheLogger -&gt; 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
--   </pre>
module Network.Wai.Logger

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

-- | Executing a function which takes <a>ApacheLogger</a>. This
--   <a>ApacheLogger</a> 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 <a>ApacheLogger</a> according to <a>LogType</a>.
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 <tt>X-Real-IP</tt> or <tt>X-Forwarded-For</tt> in the HTTP
--   header.
--   
--   This picks either <tt>X-Real-IP</tt> or <tt>X-Forwarded-For</tt>
--   depending on which of these headers comes first in the ordered list of
--   request headers.
--   
--   If the <tt>X-Forwarded-For</tt> 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 <a>FromHeader</a>, 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 <a>Request</a>. The returned <a>ByteString</a> is
--   used as the IP source address.
FromRequest :: (Request -> ByteString) -> IPAddrSource
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
data FileLogSpec
FileLogSpec :: FilePath -> Integer -> Int -> FileLogSpec
[log_file] :: FileLogSpec -> FilePath
[log_file_size] :: FileLogSpec -> Integer
[log_backup_number] :: FileLogSpec -> Int

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

-- | Returning <a>DateCacheGetter</a> and <a>DateCacheUpdater</a>.
--   
--   Note: Since version 2.1.2, this function uses the auto-update package
--   internally, and therefore the <tt>DateCacheUpdater</tt> 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 <a>ZonedDate</a>.
type DateCacheGetter = IO ZonedDate

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