Network.Wai.Middleware.Static

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.

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

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

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

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

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

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

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

Options for staticWithOptions Middleware.

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

cacheContainer :: Options -> CacheContainer

Cache container to use

mimeTypes :: Options -> FilePath -> MimeType

Compute MimeType from file name

defaultOptions :: Options

Default options.

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

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

Show FileMeta

Defined in Network.Wai.Middleware.Static

Methods

showsPrec :: Int -> FileMeta -> ShowS

show :: FileMeta -> String

showList :: [FileMeta] -> ShowS

Eq FileMeta

Defined in Network.Wai.Middleware.Static

Methods

(==) :: FileMeta -> FileMeta -> Bool

(/=) :: FileMeta -> FileMeta -> Bool

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

Monoid Policy

Note: mempty == policy Just (the always accepting policy) mappend == >-> (policy sequencing)

Defined in Network.Wai.Middleware.Static

Methods

mempty :: Policy

mappend :: Policy -> Policy -> Policy

mconcat :: [Policy] -> Policy

Semigroup Policy

Note: (<>) == >-> (policy sequencing)

Defined in Network.Wai.Middleware.Static

Methods

(<>) :: Policy -> Policy -> Policy

sconcat :: NonEmpty Policy -> Policy

stimes :: Integral b => b -> 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 FilePath

Run a policy

MIME types

getMimeType :: FilePath -> MimeType

Guess MIME type from file extension