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

-- | WAI middleware that serves requests to static files.
--   
--   WAI middleware that intercepts requests to static files and serves
--   them if they exist.
--   
--   
--   
- WAI http://hackage.haskell.org/package/wai
--   
@package wai-middleware-static
@version 0.9.3

-- | Serve static files, subject to a policy that can filter or modify
--   incoming URIs. The flow is:
--   
--   incoming request URI ==> policies ==> exists? ==> respond
--   
--   If any of the polices fail, or the file doesn't exist, then the
--   middleware gives up and calls the inner application. If the file is
--   found, the middleware chooses a content type based on the file
--   extension and returns the file contents as the response.
module Network.Wai.Middleware.Static

-- | Serve static files out of the application root (current directory). If
--   file is found, it is streamed to the client and no further middleware
--   is run. Disables caching.
--   
--   Note: for security reasons, this uses the noDots and
--   isNotAbsolute policy by default.
static :: Middleware

-- | Serve static files subject to a Policy. Disables caching.
--   
--   Note: for security reasons, this uses the noDots and
--   isNotAbsolute policy by default.
staticPolicy :: Policy -> Middleware

-- | Serve static files subject to a Policy. Unlike static
--   and staticPolicy, this has no policies enabled by default and
--   is hence insecure. Disables caching.
unsafeStaticPolicy :: Policy -> Middleware

-- | Serve static files out of the application root (current directory). If
--   file is found, it is streamed to the client and no further middleware
--   is run. Allows a CachingStrategy.
--   
--   Note: for security reasons, this uses the noDots and
--   isNotAbsolute policy by default.

-- | Deprecated: Use staticWithOptions instead. This function
--   will be removed in the next major release.
static' :: CacheContainer -> Middleware

-- | Serve static files subject to a Policy using a specified
--   CachingStrategy
--   
--   Note: for security reasons, this uses the noDots and
--   isNotAbsolute policy by default.

-- | Deprecated: Use staticPolicyWithOptions instead. This
--   function will be removed in the next major release.
staticPolicy' :: CacheContainer -> Policy -> Middleware

-- | Serve static files subject to a Policy. Unlike static
--   and staticPolicy, this has no policies enabled by default, and
--   is hence insecure. Also allows to set a CachingStrategy.

-- | Deprecated: Use unsafeStaticPolicyWithOptions instead. This
--   function will be removed in the next major release.
unsafeStaticPolicy' :: CacheContainer -> Policy -> Middleware

-- | Serve static files out of the application root (current directory). If
--   file is found, it is streamed to the client and no further middleware
--   is run. Takes Options.
--   
--   Note: for security reasons, this uses the noDots and
--   isNotAbsolute policy by default.
staticWithOptions :: Options -> Middleware

-- | Serve static files subject to a Policy using specified
--   Options
--   
--   Note: for security reasons, this uses the noDots and
--   isNotAbsolute policy by default.
staticPolicyWithOptions :: Options -> Policy -> Middleware

-- | Serve static files subject to a Policy. Unlike
--   staticWithOptions and staticPolicyWithOptions, this has
--   no policies enabled by default and is hence insecure. Takes
--   Options.
unsafeStaticPolicyWithOptions :: Options -> Policy -> Middleware

-- | Options for staticWithOptions Middleware.
--   
--   Options can be set using record syntax on defaultOptions with
--   the fields below.
data Options

-- | Cache container to use
cacheContainer :: Options -> CacheContainer

-- | Compute MimeType from file name
mimeTypes :: Options -> FilePath -> MimeType

-- | Default options.
--   
--   
--   Options
--   { cacheContainer = CacheContainerEmpty -- no caching
--   , mimeTypes      = getMimeType         -- use defaultMimeLookup from Mime
--   }
--   
defaultOptions :: Options

-- | A cache strategy which should be used to serve content matching a
--   policy. Meta information is cached for a maxium of 100 seconds before
--   being recomputed.
data CachingStrategy

-- | Do not send any caching headers
NoCaching :: CachingStrategy

-- | Send common caching headers for public (non dynamic) static files
PublicStaticCaching :: CachingStrategy

-- | Compute caching headers using the user specified function. See
--   http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/
--   for a detailed guide
CustomCaching :: (FileMeta -> RequestHeaders) -> CachingStrategy

-- | Meta information about a file to calculate cache headers
data FileMeta
FileMeta :: !ByteString -> !ByteString -> FilePath -> FileMeta
[fm_lastModified] :: FileMeta -> !ByteString
[fm_etag] :: FileMeta -> !ByteString
[fm_fileName] :: FileMeta -> FilePath

-- | Initialize caching. This should only be done once per application
--   launch.
initCaching :: CachingStrategy -> IO CacheContainer

-- | Container caching file meta information. Create using
--   initCaching
data CacheContainer

-- | Take an incoming URI and optionally modify or filter it. The result
--   will be treated as a filepath.
data Policy

-- | Choose between two policies. If the first fails, run the second.
(<|>) :: Policy -> Policy -> Policy
infixr 4 <|>

-- | Sequence two policies. They are run from left to right. (Note: this is
--   mappend)
(>->) :: Policy -> Policy -> Policy
infixr 5 >->

-- | Lift a function into a Policy
policy :: (String -> Maybe String) -> Policy

-- | Lift a predicate into a Policy
predicate :: (String -> Bool) -> Policy

-- | Add a base path to the URI
--   
--   
--   staticPolicy (addBase "/home/user/files")
--   
--   
--   GET "foo/bar" looks for "/home/user/files/foo/bar"
addBase :: String -> Policy

-- | Add an initial slash to to the URI, if not already present.
--   
--   
--   staticPolicy addSlash
--   
--   
--   GET "foo/bar" looks for "/foo/bar"
addSlash :: Policy

-- | Accept only URIs containing given string
contains :: String -> Policy

-- | Accept only URIs with given prefix
hasPrefix :: String -> Policy

-- | Accept only URIs with given suffix
hasSuffix :: String -> Policy

-- | Reject URIs containing ".."
noDots :: Policy

-- | Reject URIs that are absolute paths
isNotAbsolute :: Policy

-- | Use URI as the key to an association list, rejecting those not found.
--   The policy result is the matching value.
--   
--   
--   staticPolicy (only [("foo/bar", "/home/user/files/bar")])
--   
--   
--   GET "foo/bar" looks for "/home/user/files/bar" GET "baz/bar" doesn't
--   match anything
only :: [(String, String)] -> Policy

-- | Run a policy
tryPolicy :: Policy -> String -> Maybe FilePath

-- | Guess MIME type from file extension
getMimeType :: FilePath -> MimeType
instance GHC.Classes.Eq Network.Wai.Middleware.Static.FileMeta
instance GHC.Internal.Base.Monoid Network.Wai.Middleware.Static.Policy
instance GHC.Internal.Base.Semigroup Network.Wai.Middleware.Static.Policy
instance GHC.Internal.Show.Show Network.Wai.Middleware.Static.FileMeta
