-- 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.
--   
--   <ul>
--   <li><i>WAI</i> <a>http://hackage.haskell.org/package/wai</a></li>
--   </ul>
@package wai-middleware-static
@version 0.8.1


-- | Serve static files, subject to a policy that can filter or modify
--   incoming URIs. The flow is:
--   
--   incoming request URI ==&gt; policies ==&gt; exists? ==&gt; 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 <a>noDots</a> and
--   <a>isNotAbsolute</a> policy by default.
static :: Middleware

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

-- | Serve static files subject to a <a>Policy</a>. Unlike <a>static</a>
--   and <a>staticPolicy</a>, 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 <a>CachingStrategy</a>.
--   
--   Note: for security reasons, this uses the <a>noDots</a> and
--   <a>isNotAbsolute</a> policy by default.
static' :: CacheContainer -> Middleware

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

-- | Serve static files subject to a <a>Policy</a>. Unlike <a>static</a>
--   and <a>staticPolicy</a>, this has no policies enabled by default, and
--   is hence insecure. Also allows to set a <a>CachingStrategy</a>.
unsafeStaticPolicy' :: CacheContainer -> Policy -> Middleware

-- | 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
--   <a>http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/</a>
--   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
--   <a>initCaching</a>
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
--   <a>mappend</a>)
(>->) :: Policy -> Policy -> Policy
infixr 5 >->

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

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

-- | Add a base path to the URI
--   
--   <pre>
--   staticPolicy (addBase "/home/user/files")
--   </pre>
--   
--   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.
--   
--   <pre>
--   staticPolicy addSlash
--   </pre>
--   
--   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.
--   
--   <pre>
--   staticPolicy (only [("foo/bar", "/home/user/files/bar")])
--   </pre>
--   
--   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 String

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