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


-- | WAI application for static serving
--   
--   Also provides some helper functions and datatypes for use outside of
--   WAI.
@package wai-app-static
@version 1.3.1.2

module WaiAppStatic.Types

-- | An individual component of a path, or of a filepath.
--   
--   This is the core type used by wai-app-static for doing lookups. It
--   provides a smart constructor to avoid the possibility of constructing
--   unsafe path segments (though <tt>unsafeToPiece</tt> can get around
--   that as necessary).
--   
--   Individual file lookup backends must know how to convert from a
--   <tt>Piece</tt> to their storage system.
data Piece

-- | Smart constructor for a <tt>Piece</tt>. Won't allow unsafe components,
--   such as pieces beginning with a period or containing a slash. This
--   <i>will</i>, however, allow null pieces.
toPiece :: Text -> Maybe Piece
fromPiece :: Piece -> Text

-- | Construct a <tt>Piece</tt> without input validation.
unsafeToPiece :: Text -> Piece

-- | Request coming from a user. Corresponds to <tt>pathInfo</tt>.
type Pieces = [Piece]

-- | Call <tt>toPiece</tt> on a list.
--   
--   <pre>
--   toPieces = mapM toPiece
--   </pre>
toPieces :: [Text] -> Maybe Pieces

-- | Values for the max-age component of the cache-control response header.
data MaxAge

-- | no cache-control set
NoMaxAge :: MaxAge

-- | set to the given number of seconds
MaxAgeSeconds :: Int -> MaxAge

-- | essentially infinite caching; in reality, probably one year
MaxAgeForever :: MaxAge

-- | Just the name of a folder.
type FolderName = Piece

-- | Represent contents of a single folder, which can be itself either a
--   file or a folder.
data Folder
Folder :: [Either FolderName File] -> Folder
folderContents :: Folder -> [Either FolderName File]

-- | Information on an individual file.
data File
File :: Int -> (Status -> ResponseHeaders -> Response) -> Piece -> IO (Maybe ByteString) -> Maybe EpochTime -> File

-- | Size of file in bytes
fileGetSize :: File -> Int

-- | How to construct a WAI response for this file. Some files are stored
--   on the filesystem and can use <tt>ResponseFile</tt>, while others are
--   stored in memory and should use <tt>ResponseBuilder</tt>.
fileToResponse :: File -> Status -> ResponseHeaders -> Response

-- | Last component of the filename.
fileName :: File -> Piece

-- | Calculate a hash of the contents of this file, such as for etag.
fileGetHash :: File -> IO (Maybe ByteString)

-- | Last modified time, used for both display in listings and
--   if-modified-since.
fileGetModified :: File -> Maybe EpochTime

-- | Result of looking up a file in some storage backend.
--   
--   The lookup is either a file or folder, or does not exist.
data LookupResult
LRFile :: File -> LookupResult
LRFolder :: Folder -> LookupResult
LRNotFound :: LookupResult

-- | How to construct a directory listing page for the given request path
--   and the resulting folder.
type Listing = Pieces -> Folder -> IO Builder

-- | All of the settings available to users for tweaking wai-app-static.
--   
--   Note that you should use the settings type approach for modifying
--   values. See <a>http://www.yesodweb.com/book/settings-types</a> for
--   more information.
data StaticSettings
StaticSettings :: (Pieces -> IO LookupResult) -> (File -> IO MimeType) -> [Piece] -> Maybe Listing -> MaxAge -> (Pieces -> ByteString -> ByteString) -> Bool -> Bool -> StaticSettings

-- | Lookup a single file or folder. This is how you can control storage
--   backend (filesystem, embedded, etc) and where to lookup.
ssLookupFile :: StaticSettings -> Pieces -> IO LookupResult

-- | Determine the mime type of the given file. Note that this function
--   lives in <tt>IO</tt> in case you want to perform more complicated
--   mimetype analysis, such as via the <tt>file</tt> utility.
ssGetMimeType :: StaticSettings -> File -> IO MimeType

-- | Ordered list of filenames to be used for indices. If the user requests
--   a folder, and a file with the given name is found in that folder, that
--   file is served. This supercedes any directory listing.
ssIndices :: StaticSettings -> [Piece]

-- | How to perform a directory listing. Optional. Will be used when the
--   user requested a folder.
ssListing :: StaticSettings -> Maybe Listing

-- | Value to provide for max age in the cache-control.
ssMaxAge :: StaticSettings -> MaxAge

-- | Given a requested path and a new destination, construct a string that
--   will go there. Default implementation will use relative paths.
ssMkRedirect :: StaticSettings -> Pieces -> ByteString -> ByteString

-- | If <tt>True</tt>, send a redirect to the user when a folder is
--   requested and an index page should be displayed. When <tt>False</tt>,
--   display the content immediately.
ssRedirectToIndex :: StaticSettings -> Bool

-- | Prefer usage of etag caching to last-modified caching.
ssUseHash :: StaticSettings -> Bool
instance Show Piece
instance Eq Piece
instance Ord Piece

module WaiAppStatic.Listing

-- | Provides a default directory listing, suitable for most apps.
--   
--   Code below taken from Happstack:
--   <a>http://patch-tag.com/r/mae/happstack/snapshot/current/content/pretty/happstack-server/src/Happstack/Server/FileServe/BuildingBlocks.hs</a>
defaultListing :: Listing


-- | Access files on the filesystem.
module WaiAppStatic.Storage.Filesystem

-- | How to calculate etags. Can perform filesystem reads on each call, or
--   use some caching mechanism.
type ETagLookup = FilePath -> IO (Maybe ByteString)

-- | Settings optimized for a web application. Files will have aggressive
--   caching applied and hashes calculated, and indices and listings are
--   disabled.
defaultWebAppSettings :: FilePath -> StaticSettings

-- | Settings optimized for a file server. More conservative caching will
--   be applied, and indices and listings are enabled.
defaultFileServerSettings :: FilePath -> StaticSettings

-- | Same as <tt>defaultWebAppSettings</tt>, but additionally uses a
--   specialized <tt>ETagLookup</tt> in place of the standard one. This can
--   allow you to cache your hash values, or even precompute them.
webAppSettingsWithLookup :: FilePath -> ETagLookup -> StaticSettings


-- | Lookup files stored in memory instead of from the filesystem.
module WaiAppStatic.Storage.Embedded

-- | Serve the list of path/content pairs directly from memory.
embeddedSettings :: [(FilePath, ByteString)] -> StaticSettings


-- | Static file serving for WAI.
module Network.Wai.Application.Static

-- | Turn a <tt>StaticSettings</tt> into a WAI application.
staticApp :: StaticSettings -> Application

-- | Settings optimized for a web application. Files will have aggressive
--   caching applied and hashes calculated, and indices and listings are
--   disabled.
defaultWebAppSettings :: FilePath -> StaticSettings

-- | Same as <tt>defaultWebAppSettings</tt>, but additionally uses a
--   specialized <tt>ETagLookup</tt> in place of the standard one. This can
--   allow you to cache your hash values, or even precompute them.
webAppSettingsWithLookup :: FilePath -> ETagLookup -> StaticSettings

-- | Settings optimized for a file server. More conservative caching will
--   be applied, and indices and listings are enabled.
defaultFileServerSettings :: FilePath -> StaticSettings

-- | Serve the list of path/content pairs directly from memory.
embeddedSettings :: [(FilePath, ByteString)] -> StaticSettings

-- | All of the settings available to users for tweaking wai-app-static.
--   
--   Note that you should use the settings type approach for modifying
--   values. See <a>http://www.yesodweb.com/book/settings-types</a> for
--   more information.
data StaticSettings

-- | Lookup a single file or folder. This is how you can control storage
--   backend (filesystem, embedded, etc) and where to lookup.
ssLookupFile :: StaticSettings -> Pieces -> IO LookupResult

-- | Given a requested path and a new destination, construct a string that
--   will go there. Default implementation will use relative paths.
ssMkRedirect :: StaticSettings -> Pieces -> ByteString -> ByteString

-- | Determine the mime type of the given file. Note that this function
--   lives in <tt>IO</tt> in case you want to perform more complicated
--   mimetype analysis, such as via the <tt>file</tt> utility.
ssGetMimeType :: StaticSettings -> File -> IO MimeType

-- | How to perform a directory listing. Optional. Will be used when the
--   user requested a folder.
ssListing :: StaticSettings -> Maybe Listing

-- | Ordered list of filenames to be used for indices. If the user requests
--   a folder, and a file with the given name is found in that folder, that
--   file is served. This supercedes any directory listing.
ssIndices :: StaticSettings -> [Piece]

-- | Value to provide for max age in the cache-control.
ssMaxAge :: StaticSettings -> MaxAge

-- | If <tt>True</tt>, send a redirect to the user when a folder is
--   requested and an index page should be displayed. When <tt>False</tt>,
--   display the content immediately.
ssRedirectToIndex :: StaticSettings -> Bool
