libghc-wai-app-static-doc 3.1.6.1-3build13 / usr / share / doc / libghc-wai-app-static-doc / html / wai-app-static.txt

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


-- | WAI application for static serving
--   
--   API docs and the README are available at
--   <a>http://www.stackage.org/package/wai-app-static</a>.
@package wai-app-static
@version 3.1.6.1

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 :: Integer -> (Status -> ResponseHeaders -> Response) -> Piece -> IO (Maybe ByteString) -> Maybe EpochTime -> File

-- | Size of file in bytes
[fileGetSize] :: File -> Integer

-- | 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 -> Bool -> Maybe Application -> 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

-- | Force a trailing slash at the end of directories
[ssAddTrailingSlash] :: StaticSettings -> Bool

-- | Optional <a>Application</a> to be used in case of 404 errors
--   
--   Since 3.1.3
[ss404Handler] :: StaticSettings -> Maybe Application
instance GHC.Classes.Ord WaiAppStatic.Types.Piece
instance GHC.Classes.Eq WaiAppStatic.Types.Piece
instance GHC.Show.Show WaiAppStatic.Types.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

module WaiAppStatic.Storage.Embedded

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

-- | An Etag is used to return 304 Not Modified responses so the client
--   does not need to download resources a second time. Usually the etag is
--   built from a hash of the content. To disable Etags, you can pass the
--   empty string. This will cause the content to be redownloaded on every
--   request.
type Etag = Text

-- | Used at compile time to hold data about an entry to embed into the
--   compiled executable.
data EmbeddableEntry
EmbeddableEntry :: Text -> MimeType -> Either (Etag, ByteString) ExpQ -> EmbeddableEntry

-- | The location where this resource should be served from. The location
--   can contain forward slashes (/) to simulate directories, but must not
--   end with a forward slash.
[eLocation] :: EmbeddableEntry -> Text

-- | The mime type.
[eMimeType] :: EmbeddableEntry -> MimeType

-- | The content itself. The content can be given as a tag and bytestring,
--   in which case the content will be embedded directly into the
--   execuatble. Alternatively, the content can be given as a template
--   haskell expression returning <tt>IO (<a>Etag</a>,
--   <a>ByteString</a>)</tt> in which case this action will be executed on
--   every request to reload the content (this is useful for a debugging
--   mode).
[eContent] :: EmbeddableEntry -> Either (Etag, ByteString) ExpQ

-- | Create a <a>StaticSettings</a> at compile time that embeds resources
--   directly into the compiled executable. The embedded resources are
--   precompressed (depending on mime type) so that during runtime the
--   resource can be served very quickly.
--   
--   Because of GHC Template Haskell stage restrictions, you must define
--   the entries in a different module than where you create the
--   <a>StaticSettings</a>. For example,
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell, QuasiQuotes, OverloadedStrings #-}
--   module A (mkEmbedded) where
--   
--   import WaiAppStatic.Storage.Embedded
--   import Crypto.Hash.MD5 (hashlazy)
--   import qualified Data.ByteString.Lazy as BL
--   import qualified Data.ByteString.Base64 as B64
--   import qualified Data.Text as T
--   import qualified Data.Text.Encoding as T
--   
--   hash :: BL.ByteString -&gt; T.Text
--   hash = T.take 8 . T.decodeUtf8 . B64.encode . hashlazy
--   
--   mkEmbedded :: IO [EmbeddableEntry]
--   mkEmbedded = do
--       file &lt;- BL.readFile "test.css"
--       let emb = EmbeddableEntry {
--                     eLocation = "somedir/test.css"
--                   , eMimeType = "text/css"
--                   , eContent  = Left (hash file, file)
--                   }
--   
--       let reload = EmbeddableEntry {
--                        eLocation = "anotherdir/test2.txt"
--                      , eMimeType = "text/plain"
--                      , eContent  = Right [| BL.readFile "test2.txt" &gt;&gt;= \c -&gt; return (hash c, c) |]
--                      }
--   
--       return [emb, reload]
--   </pre>
--   
--   The above <tt>mkEmbedded</tt> will be executed at compile time. It
--   loads the contents of test.css and computes the hash of test.css for
--   the etag. The content will be available at the URL somedir/test.css.
--   Internally, <tt>embedApp</tt> below will attempt to compress the
--   content at compile time. The compression will only happen if the
--   compressed content is shorter than the original and the mime type is
--   either text or javascript. If the content is compressed, at runtime
--   the precomputed compressed content will be served with the appropriate
--   HTTP header. If <tt>embedApp</tt> decides not to compress the content,
--   it will be served directly.
--   
--   Secondly, <tt>mkEmbedded</tt> creates a reloadable entry. This will be
--   available at the URL anotherdir/test2.txt. Whenver a request comes in
--   for anotherdir/test2.txt, the action inside the quasiquote in eContent
--   will be executed. This will re-read the test2.txt file and recompute
--   its hash.
--   
--   Finally, here is a module which uses the above action to create a
--   <a>Application</a>.
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   module B where
--   
--   import A
--   import Network.Wai (Application)
--   import Network.Wai.Application.Static (staticApp)
--   import WaiAppStatic.Storage.Embedded
--   import Network.Wai.Handler.Warp (run)
--   
--   myApp :: Application
--   myApp = staticApp $(mkSettings mkEmbedded)
--   
--   main :: IO ()
--   main = run 3000 myApp
--   </pre>
mkSettings :: IO [EmbeddableEntry] -> ExpQ


-- | 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

-- | Force a trailing slash at the end of directories
ssAddTrailingSlash :: StaticSettings -> Bool

-- | Optional <a>Application</a> to be used in case of 404 errors
--   
--   Since 3.1.3
ss404Handler :: StaticSettings -> Maybe Application


-- | Command line version of wai-app-static, used for the warp-static
--   server.
module WaiAppStatic.CmdLine

-- | Run with the given middleware and parsing options from the command
--   line.
--   
--   Since 2.0.1
runCommandLine :: (Args -> Middleware) -> IO ()
data Args
Args :: FilePath -> [FilePath] -> Int -> Bool -> Bool -> Bool -> [(String, String)] -> String -> Args
[docroot] :: Args -> FilePath
[index] :: Args -> [FilePath]
[port] :: Args -> Int
[noindex] :: Args -> Bool
[quiet] :: Args -> Bool
[verbose] :: Args -> Bool
[mime] :: Args -> [(String, String)]
[host] :: Args -> String