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

Safe Haskell | None
Language | Haskell2010

Network.Wai.Middleware.Static

Contents

- Middlewares
- 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
- 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 String
- getMimeType :: FilePath -> MimeType

# Middlewares

static :: 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. Disables caching.

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

staticPolicy :: Policy -> Middleware #

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 #

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 #

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 #

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 #

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

# Cache Control

data CachingStrategy #

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 #

Meta information about a file to calculate cache headers

Constructors

FileMeta |
Fields fm_lastModified :: !ByteString fm_etag :: !ByteString fm_fileName :: FilePath

Instances

Eq FileMeta # |
Methods (==) :: FileMeta -> FileMeta -> Bool # (/=) :: FileMeta -> FileMeta -> Bool #
Show FileMeta # |
Methods showsPrec :: Int -> FileMeta -> ShowS # show :: FileMeta -> String # showList :: [FileMeta] -> ShowS #

initCaching :: CachingStrategy -> IO CacheContainer #

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

data CacheContainer #

Container caching file meta information. Create using `initCaching`

# Policies

data Policy #

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

Instances

Semigroup Policy # | Note: '(<>)' == `>->` (policy sequencing)
Methods (<>) :: Policy -> Policy -> Policy # sconcat :: NonEmpty Policy -> Policy # stimes :: Integral b => b -> Policy -> Policy #
Monoid Policy # | Note: `mempty` == `policy Just` (the always accepting policy) `mappend` == `>->` (policy sequencing)
Methods mempty :: Policy # mappend :: Policy -> Policy -> Policy # mconcat :: [Policy] -> Policy #

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

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

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

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

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

Lift a function into a `Policy`

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

Lift a predicate into a `Policy`

addBase :: String -> Policy #

Add a base path to the URI

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

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

addSlash :: Policy #

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

    staticPolicy addSlash

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

contains :: String -> Policy #

Accept only URIs containing given string

hasPrefix :: String -> Policy #

Accept only URIs with given prefix

hasSuffix :: String -> Policy #

Accept only URIs with given suffix

noDots :: Policy #

Reject URIs containing ".."

isNotAbsolute :: Policy #

Reject URIs that are absolute paths

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

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

Run a policy

# MIME types

getMimeType :: FilePath -> MimeType #

Guess MIME type from file extension