wai-middleware-static-0.9.3: WAI middleware that serves requests to static files.

Safe Haskell | None
Language | Haskell2010

Network.Wai.Middleware.Static

Contents

- Middlewares
- Options
- Cache Control
- Policies
- Utilities
- MIME types

Description

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.

Synopsis

- static :: Middleware
- staticPolicy :: Policy -> Middleware
- unsafeStaticPolicy :: Policy -> Middleware
- static' :: CacheContainer -> Middleware
- staticPolicy' :: CacheContainer -> Policy -> Middleware
- unsafeStaticPolicy' :: CacheContainer -> Policy -> Middleware
- staticWithOptions :: Options -> Middleware
- staticPolicyWithOptions :: Options -> Policy -> Middleware
- unsafeStaticPolicyWithOptions :: Options -> Policy -> Middleware
- data Options
- cacheContainer :: Options -> CacheContainer
- mimeTypes :: Options -> FilePath -> MimeType
- defaultOptions :: Options
- data CachingStrategy
  - = NoCaching
  - | PublicStaticCaching
  - | CustomCaching (FileMeta -> RequestHeaders)
- data FileMeta = FileMeta {
  - fm_lastModified :: !ByteString
  - fm_etag :: !ByteString
  - fm_fileName :: FilePath
  }
- initCaching :: CachingStrategy -> IO CacheContainer
- data CacheContainer
- data Policy
- (<|>) :: Policy -> Policy -> Policy
- (>->) :: Policy -> Policy -> Policy
- policy :: (String -> Maybe String) -> Policy
- predicate :: (String -> Bool) -> Policy
- addBase :: String -> Policy
- addSlash :: Policy
- contains :: String -> Policy
- hasPrefix :: String -> Policy
- hasSuffix :: String -> Policy
- noDots :: Policy
- isNotAbsolute :: Policy
- only :: [(String, String)] -> Policy
- tryPolicy :: Policy -> String -> Maybe FilePath
- getMimeType :: FilePath -> MimeType

# Middlewares

static :: Middleware Source #

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.

staticPolicy :: Policy -> Middleware Source #

Serve static files subject to a `Policy`. Disables caching.

Note: for security reasons, this uses the `noDots` and `isNotAbsolute` policy by default.

unsafeStaticPolicy :: Policy -> Middleware Source #

Serve static files subject to a `Policy`. Unlike `static` and `staticPolicy`, this has no policies enabled by default and is hence insecure. Disables caching.

static' :: CacheContainer -> Middleware Source #

Deprecated: Use `staticWithOptions` instead. This function will be removed in the next major release.

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.

staticPolicy' :: CacheContainer -> Policy -> Middleware Source #

Deprecated: Use `staticPolicyWithOptions` instead. This function will be removed in the next major release.

Serve static files subject to a `Policy` using a specified `CachingStrategy`

Note: for security reasons, this uses the `noDots` and `isNotAbsolute` policy by default.

unsafeStaticPolicy' :: CacheContainer -> Policy -> Middleware Source #

Deprecated: Use `unsafeStaticPolicyWithOptions` instead. This function will be removed in the next major release.

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

staticWithOptions :: Options -> Middleware Source #

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.

staticPolicyWithOptions :: Options -> Policy -> Middleware Source #

Serve static files subject to a `Policy` using specified `Options`

Note: for security reasons, this uses the `noDots` and `isNotAbsolute` policy by default.

unsafeStaticPolicyWithOptions :: Options -> Policy -> Middleware Source #

Serve static files subject to a `Policy`. Unlike `staticWithOptions` and `staticPolicyWithOptions`, this has no policies enabled by default and is hence insecure. Takes `Options`.

# Options

data Options Source #

Options for `staticWithOptions` `Middleware`.

Options can be set using record syntax on `defaultOptions` with the fields below.

cacheContainer :: Options -> CacheContainer Source #

Cache container to use

mimeTypes :: Options -> FilePath -> MimeType Source #

Compute MimeType from file name

defaultOptions :: Options Source #

Default options.

    Options
    { cacheContainer = CacheContainerEmpty -- no caching
    , mimeTypes      = getMimeType         -- use defaultMimeLookup from Mime
    }

# Cache Control

data CachingStrategy Source #

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.

Constructors

NoCaching | Do not send any caching headers
PublicStaticCaching | Send common caching headers for public (non dynamic) static files
CustomCaching (FileMeta -> RequestHeaders) | Compute caching headers using the user specified function. See http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/ for a detailed guide

data FileMeta Source #

Meta information about a file to calculate cache headers

Constructors

FileMeta |

Fields

- fm_lastModified :: !ByteString
- fm_etag :: !ByteString
- fm_fileName :: FilePath

#### Instances

Instances details

Show FileMeta Source # |
Instance details Defined in Network.Wai.Middleware.Static Methods showsPrec :: Int -> FileMeta -> ShowS Source # show :: FileMeta -> String Source # showList :: [FileMeta] -> ShowS Source #
Eq FileMeta Source # |
Instance details Defined in Network.Wai.Middleware.Static Methods (==) :: FileMeta -> FileMeta -> Bool Source # (/=) :: FileMeta -> FileMeta -> Bool Source #

initCaching :: CachingStrategy -> IO CacheContainer Source #

Initialize caching. This should only be done once per application launch.

data CacheContainer Source #

Container caching file meta information. Create using `initCaching`

# Policies

data Policy Source #

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

#### Instances

Instances details

Monoid Policy Source # | Note: `mempty` == `policy Just` (the always accepting policy) `mappend` == `>->` (policy sequencing)
Instance details Defined in Network.Wai.Middleware.Static Methods mempty :: Policy Source # mappend :: Policy -> Policy -> Policy Source # mconcat :: [Policy] -> Policy Source #
Semigroup Policy Source # | Note: `(<>)` == `>->` (policy sequencing)
Instance details Defined in Network.Wai.Middleware.Static Methods (<>) :: Policy -> Policy -> Policy Source # sconcat :: NonEmpty Policy -> Policy Source # stimes :: Integral b => b -> Policy -> Policy Source #

(<|>) :: Policy -> Policy -> Policy infixr 4 Source #

Choose between two policies. If the first fails, run the second.

(>->) :: Policy -> Policy -> Policy infixr 5 Source #

Sequence two policies. They are run from left to right. (Note: this is `mappend`)

policy :: (String -> Maybe String) -> Policy Source #

Lift a function into a `Policy`

predicate :: (String -> Bool) -> Policy Source #

Lift a predicate into a `Policy`

addBase :: String -> Policy Source #

Add a base path to the URI

    staticPolicy (addBase "/home/user/files")

GET "foo/bar" looks for "/home/user/files/foo/bar"

addSlash :: Policy Source #

Add an initial slash to to the URI, if not already present.

    staticPolicy addSlash

GET "foo/bar" looks for "/foo/bar"

contains :: String -> Policy Source #

Accept only URIs containing given string

hasPrefix :: String -> Policy Source #

Accept only URIs with given prefix

hasSuffix :: String -> Policy Source #

Accept only URIs with given suffix

noDots :: Policy Source #

Reject URIs containing ".."

isNotAbsolute :: Policy Source #

Reject URIs that are absolute paths

only :: [(String, String)] -> Policy Source #

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

# Utilities

tryPolicy :: Policy -> String -> Maybe FilePath Source #

Run a policy

# MIME types

getMimeType :: FilePath -> MimeType Source #

Guess MIME type from file extension