WaiAppStatic.Types

wai-app-static-3.1.4.1: WAI application for static serving

Safe Haskell | None
Language | Haskell98

WaiAppStatic.Types

Contents

- Pieces
- Caching
- File/folder serving
- Settings

Synopsis

- data Piece
- toPiece :: Text -> Maybe Piece
- fromPiece :: Piece -> Text
- unsafeToPiece :: Text -> Piece
- type Pieces = [Piece]
- toPieces :: [Text] -> Maybe Pieces
- data MaxAge
  - = NoMaxAge
  - | MaxAgeSeconds Int
  - | MaxAgeForever
- type FolderName = Piece
- data Folder = Folder {
  - folderContents :: [Either FolderName File]
  }
- data File = File {
  - fileGetSize :: Int
  - fileToResponse :: Status -> ResponseHeaders -> Response
  - fileName :: Piece
  - fileGetHash :: IO (Maybe ByteString)
  - fileGetModified :: Maybe EpochTime
  }
- data LookupResult
  - = LRFile File
  - | LRFolder Folder
  - | LRNotFound
- type Listing = Pieces -> Folder -> IO Builder
- data StaticSettings = StaticSettings {
  - ssLookupFile :: Pieces -> IO LookupResult
  - ssGetMimeType :: File -> IO MimeType
  - ssIndices :: [Piece]
  - ssListing :: Maybe Listing
  - ssMaxAge :: MaxAge
  - ssMkRedirect :: Pieces -> ByteString -> ByteString
  - ssRedirectToIndex :: Bool
  - ssUseHash :: Bool
  - ssAddTrailingSlash :: Bool
  - ss404Handler :: Maybe Application
  }

# Pieces

data Piece

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 `unsafeToPiece` can get around that as necessary).

Individual file lookup backends must know how to convert from a `Piece` to their storage system.

Instances

Eq Piece |
Ord Piece |
Show Piece |

toPiece :: Text -> Maybe Piece

Smart constructor for a `Piece`. Won't allow unsafe components, such as pieces beginning with a period or containing a slash. This will, however, allow null pieces.

fromPiece :: Piece -> Text

unsafeToPiece :: Text -> Piece

Construct a `Piece` without input validation.

type Pieces = [Piece]

Request coming from a user. Corresponds to `pathInfo`.

toPieces :: [Text] -> Maybe Pieces

Call `toPiece` on a list.

    toPieces = mapM toPiece

# Caching

data MaxAge

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

Constructors

NoMaxAge | no cache-control set
MaxAgeSeconds Int | set to the given number of seconds
MaxAgeForever | essentially infinite caching; in reality, probably one year

# File/folder serving

type FolderName = Piece

Just the name of a folder.

data Folder

Represent contents of a single folder, which can be itself either a file or a folder.

Constructors

Folder |
Fields folderContents :: [Either FolderName File]

data File

Information on an individual file.

Constructors

File |
Fields fileGetSize :: Int Size of file in bytes fileToResponse :: Status -> ResponseHeaders -> Response How to construct a WAI response for this file. Some files are stored on the filesystem and can use `ResponseFile`, while others are stored in memory and should use `ResponseBuilder`. fileName :: Piece Last component of the filename. fileGetHash :: IO (Maybe ByteString) Calculate a hash of the contents of this file, such as for etag. fileGetModified :: Maybe EpochTime Last modified time, used for both display in listings and if-modified-since.

data LookupResult

Result of looking up a file in some storage backend.

The lookup is either a file or folder, or does not exist.

Constructors

LRFile File |
LRFolder Folder |
LRNotFound |

type Listing = Pieces -> Folder -> IO Builder

How to construct a directory listing page for the given request path and the resulting folder.

# Settings

data 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 http://www.yesodweb.com/book/settings-types for more information.

Constructors

StaticSettings |
Fields ssLookupFile :: Pieces -> IO LookupResult Lookup a single file or folder. This is how you can control storage backend (filesystem, embedded, etc) and where to lookup. ssGetMimeType :: File -> IO MimeType Determine the mime type of the given file. Note that this function lives in `IO` in case you want to perform more complicated mimetype analysis, such as via the `file` utility. ssIndices :: [Piece] 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. ssListing :: Maybe Listing How to perform a directory listing. Optional. Will be used when the user requested a folder. ssMaxAge :: MaxAge Value to provide for max age in the cache-control. ssMkRedirect :: Pieces -> ByteString -> ByteString Given a requested path and a new destination, construct a string that will go there. Default implementation will use relative paths. ssRedirectToIndex :: Bool If `True`, send a redirect to the user when a folder is requested and an index page should be displayed. When `False`, display the content immediately. ssUseHash :: Bool Prefer usage of etag caching to last-modified caching. ssAddTrailingSlash :: Bool Force a trailing slash at the end of directories ss404Handler :: Maybe Application Optional `Application` to be used in case of 404 errors Since 3.1.3