Debian Codegraph @

Network/Wai/Middleware/Static.hs

raw
1 {-# LANGUAGE CPP, OverloadedStrings #-}
2 -- | Serve static files, subject to a policy that can filter or
3 -- modify incoming URIs. The flow is:
4 --
5 -- incoming request URI ==> policies ==> exists? ==> respond
6 --
7 -- If any of the polices fail, or the file doesn't
8 -- exist, then the middleware gives up and calls the inner application.
9 -- If the file is found, the middleware chooses a content type based
10 -- on the file extension and returns the file contents as the response.
11 module Network.Wai.Middleware.Static
12 ( -- * Middlewares
13 static, staticPolicy, unsafeStaticPolicy
14 , static', staticPolicy', unsafeStaticPolicy'
15 , staticWithOptions, staticPolicyWithOptions, unsafeStaticPolicyWithOptions
16 , -- * Options
17 Options, cacheContainer, mimeTypes, defaultOptions
18 , -- * Cache Control
19 CachingStrategy(..), FileMeta(..), initCaching, CacheContainer
20 , -- * Policies
21 Policy, (<|>), (>->), policy, predicate
22 , addBase, addSlash, contains, hasPrefix, hasSuffix, noDots, isNotAbsolute, only
23 , -- * Utilities
24 tryPolicy
25 , -- * MIME types
26 getMimeType
27 ) where
28
29 import Caching.ExpiringCacheMap.HashECM (newECMIO, lookupECM, CacheSettings(..), consistentDuration)
30 import Control.Monad
31 import qualified Crypto.Hash.SHA1 as SHA1
32 import qualified Data.ByteString.Base16 as Base16
33 import qualified Data.List as L
34 #if !(MIN_VERSION_base(4,11,0))
35 import Data.Semigroup (Semigroup(..))
36 #endif
37 import Data.Time
38 import Data.Time.Clock.POSIX
39 import Network.HTTP.Types
40 import Network.Mime (MimeType, defaultMimeLookup)
41 import Network.Wai
42 import System.Directory (doesFileExist, getModificationTime)
43 -- import Crypto.Hash.Algorithms
44 -- import Crypto.Hash
45 -- import Data.ByteArray.Encoding
46 import qualified Data.ByteString as BS
47 import qualified Data.ByteString.Char8 as BSC
48 import qualified Data.ByteString.Lazy as BSL
49 import qualified Data.Text as T
50 import qualified System.FilePath as FP
51
52 -- | Take an incoming URI and optionally modify or filter it.
53 -- The result will be treated as a filepath.
54 newtype Policy = Policy { tryPolicy :: String -> Maybe FilePath -- ^ Run a policy
55 }
56
57 -- | Options for 'staticWithOptions' 'Middleware'.
58 --
59 -- Options can be set using record syntax on 'defaultOptions' with the fields below.
60 data Options = Options { cacheContainer :: CacheContainer -- ^ Cache container to use
61 , mimeTypes :: FilePath -> MimeType -- ^ Compute MimeType from file name
62 }
63
64 -- | Default options.
65 --
66 -- @
67 -- 'Options'
68 -- { 'cacheContainer' = 'CacheContainerEmpty' -- no caching
69 -- , 'mimeTypes' = 'getMimeType' -- use 'defaultMimeLookup' from 'Network.Mime'
70 -- }
71 -- @
72 defaultOptions :: Options
73 defaultOptions = Options { cacheContainer = CacheContainerEmpty, mimeTypes = getMimeType }
74
75 -- | A cache strategy which should be used to
76 -- serve content matching a policy. Meta information is cached for a maxium of
77 -- 100 seconds before being recomputed.
78 data CachingStrategy
79 -- | Do not send any caching headers
80 = NoCaching
81 -- | Send common caching headers for public (non dynamic) static files
82 | PublicStaticCaching
83 -- | Compute caching headers using the user specified function.
84 -- See <http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/> for a detailed guide
85 | CustomCaching (FileMeta -> RequestHeaders)
86
87 -- | Note:
88 -- '(<>)' == @>->@ (policy sequencing)
89 instance Semigroup Policy where
90 p1 <> p2 = policy (maybe Nothing (tryPolicy p2) . tryPolicy p1)
91
92 -- | Note:
93 -- 'mempty' == @policy Just@ (the always accepting policy)
94 -- 'mappend' == @>->@ (policy sequencing)
95 instance Monoid Policy where
96 mempty = policy Just
97 mappend = (<>)
98
99 -- | Lift a function into a 'Policy'
100 policy :: (String -> Maybe String) -> Policy
101 policy = Policy
102
103 -- | Lift a predicate into a 'Policy'
104 predicate :: (String -> Bool) -> Policy
105 predicate p = policy (\s -> if p s then Just s else Nothing)
106
107 -- | Sequence two policies. They are run from left to right. (Note: this is `mappend`)
108 infixr 5 >->
109 (>->) :: Policy -> Policy -> Policy
110 (>->) = (<>)
111
112 -- | Choose between two policies. If the first fails, run the second.
113 infixr 4 <|>
114 (<|>) :: Policy -> Policy -> Policy
115 p1 <|> p2 = policy (\s -> maybe (tryPolicy p2 s) Just (tryPolicy p1 s))
116
117 -- | Add a base path to the URI
118 --
119 -- > staticPolicy (addBase "/home/user/files")
120 --
121 -- GET \"foo\/bar\" looks for \"\/home\/user\/files\/foo\/bar\"
122 --
123 addBase :: String -> Policy
124 addBase b = policy (Just . (b FP.</>))
125
126 -- | Add an initial slash to to the URI, if not already present.
127 --
128 -- > staticPolicy addSlash
129 --
130 -- GET \"foo\/bar\" looks for \"\/foo\/bar\"
131 addSlash :: Policy
132 addSlash = policy slashOpt
133 where slashOpt s@('/':_) = Just s
134 slashOpt s = Just ('/':s)
135
136 -- | Accept only URIs with given suffix
137 hasSuffix :: String -> Policy
138 hasSuffix = predicate . L.isSuffixOf
139
140 -- | Accept only URIs with given prefix
141 hasPrefix :: String -> Policy
142 hasPrefix = predicate . L.isPrefixOf
143
144 -- | Accept only URIs containing given string
145 contains :: String -> Policy
146 contains = predicate . L.isInfixOf
147
148 -- | Reject URIs containing \"..\"
149 noDots :: Policy
150 noDots = predicate (not . L.isInfixOf "..")
151
152 -- | Reject URIs that are absolute paths
153 isNotAbsolute :: Policy
154 isNotAbsolute = predicate $ not . FP.isAbsolute
155
156 -- | Use URI as the key to an association list, rejecting those not found.
157 -- The policy result is the matching value.
158 --
159 -- > staticPolicy (only [("foo/bar", "/home/user/files/bar")])
160 --
161 -- GET \"foo\/bar\" looks for \"\/home\/user\/files\/bar\"
162 -- GET \"baz\/bar\" doesn't match anything
163 --
164 only :: [(String, String)] -> Policy
165 only al = policy (flip lookup al)
166
167 -- | Serve static files out of the application root (current directory).
168 -- If file is found, it is streamed to the client and no further middleware is run. Disables caching.
169 --
170 -- Note: for security reasons, this uses the 'noDots' and 'isNotAbsolute' policy by default.
171 static :: Middleware
172 static = staticPolicy mempty
173
174 -- | Serve static files out of the application root (current directory).
175 -- If file is found, it is streamed to the client and no further middleware is run. Allows a 'CachingStrategy'.
176 --
177 -- Note: for security reasons, this uses the 'noDots' and 'isNotAbsolute' policy by default.
178 {-# DEPRECATED static'
179 [ "Use 'staticWithOptions' instead. "
180 , "This function will be removed in the next major release."
181 ] #-}
182 static' :: CacheContainer -> Middleware
183 static' cc = staticPolicy' cc mempty
184
185 -- | Serve static files out of the application root (current directory).
186 -- If file is found, it is streamed to the client and no further middleware is run. Takes 'Options'.
187 --
188 -- Note: for security reasons, this uses the 'noDots' and 'isNotAbsolute' policy by default.
189 staticWithOptions :: Options -> Middleware
190 staticWithOptions options = staticPolicyWithOptions options mempty
191
192 -- | Serve static files subject to a 'Policy'. Disables caching.
193 --
194 -- Note: for security reasons, this uses the 'noDots' and 'isNotAbsolute' policy by default.
195 staticPolicy :: Policy -> Middleware
196 staticPolicy = staticPolicy' (cacheContainer defaultOptions)
197
198 -- | Serve static files subject to a 'Policy' using a specified 'CachingStrategy'
199 --
200 -- Note: for security reasons, this uses the 'noDots' and 'isNotAbsolute' policy by default.
201 {-# DEPRECATED staticPolicy'
202 [ "Use 'staticPolicyWithOptions' instead. "
203 , "This function will be removed in the next major release."
204 ] #-}
205 staticPolicy' :: CacheContainer -> Policy -> Middleware
206 staticPolicy' cc p = unsafeStaticPolicy' cc $ noDots >-> isNotAbsolute >-> p
207
208 -- | Serve static files subject to a 'Policy' using specified 'Options'
209 --
210 -- Note: for security reasons, this uses the 'noDots' and 'isNotAbsolute' policy by default.
211 staticPolicyWithOptions :: Options -> Policy -> Middleware
212 staticPolicyWithOptions options p = unsafeStaticPolicyWithOptions options $ noDots >-> isNotAbsolute >-> p
213
214 -- | Serve static files subject to a 'Policy'. Unlike 'static' and 'staticPolicy', this
215 -- has no policies enabled by default and is hence insecure. Disables caching.
216 unsafeStaticPolicy :: Policy -> Middleware
217 unsafeStaticPolicy = unsafeStaticPolicy' (cacheContainer defaultOptions)
218
219 -- | Serve static files subject to a 'Policy'. Unlike 'static' and 'staticPolicy', this
220 -- has no policies enabled by default, and is hence insecure. Also allows to set a 'CachingStrategy'.
221 {-# DEPRECATED unsafeStaticPolicy'
222 [ "Use 'unsafeStaticPolicyWithOptions' instead. "
223 , "This function will be removed in the next major release."
224 ] #-}
225 unsafeStaticPolicy' :: CacheContainer -> Policy -> Middleware
226 unsafeStaticPolicy' cc = unsafeStaticPolicyWithOptions (defaultOptions { cacheContainer = cc })
227
228 -- | Serve static files subject to a 'Policy'. Unlike 'staticWithOptions' and 'staticPolicyWithOptions',
229 -- this has no policies enabled by default and is hence insecure. Takes 'Options'.
230 unsafeStaticPolicyWithOptions :: Options -> Policy -> Middleware
231 unsafeStaticPolicyWithOptions options p app req callback =
232 maybe serveUpstream tryStaticFile mCandidateFile
233 where
234 serveUpstream :: IO ResponseReceived
235 serveUpstream = app req callback
236
237 tryStaticFile :: FilePath -> IO ResponseReceived
238 tryStaticFile fp = do
239 exists <- doesFileExist fp
240 if exists
241 then case cacheContainer options of
242 CacheContainerEmpty ->
243 sendFile fp []
244 CacheContainer _ NoCaching ->
245 sendFile fp []
246 CacheContainer getFileMeta strategy ->
247 do fileMeta <- getFileMeta fp
248 if checkNotModified fileMeta (readHeader "If-Modified-Since") (readHeader "If-None-Match")
249 then sendNotModified fileMeta strategy
250 else sendFile fp (computeHeaders fileMeta strategy)
251 else serveUpstream
252
253 mCandidateFile :: Maybe FilePath
254 mCandidateFile =
255 guard isHeadOrGet >>
256 (tryPolicy p $ T.unpack $ T.intercalate "/" $ pathInfo req)
257 where
258 method :: Method
259 method = requestMethod req
260
261 isHeadOrGet :: Bool
262 isHeadOrGet = method == methodHead || method == methodGet
263
264 readHeader header =
265 lookup header $ requestHeaders req
266 checkNotModified fm modSince etag =
267 or [ Just (fm_lastModified fm) == modSince
268 , Just (fm_etag fm) == etag
269 ]
270 computeHeaders fm cs =
271 case cs of
272 NoCaching -> []
273 PublicStaticCaching ->
274 [ ("Cache-Control", "no-transform,public,max-age=300,s-maxage=900")
275 , ("Last-Modified", fm_lastModified fm)
276 , ("ETag", fm_etag fm)
277 , ("Vary", "Accept-Encoding")
278 ]
279 CustomCaching f -> f fm
280 sendNotModified fm cs =
281 do let cacheHeaders = computeHeaders fm cs
282 callback $ responseLBS status304 cacheHeaders BSL.empty
283 sendFile fp extraHeaders =
284 do let basicHeaders =
285 [ ("Content-Type", mimeTypes options fp)
286 ]
287 headers =
288 basicHeaders ++ extraHeaders
289 callback $ responseFile status200 headers fp Nothing
290
291 -- | Container caching file meta information. Create using 'initCaching'
292 data CacheContainer
293 = CacheContainerEmpty
294 | CacheContainer (FilePath -> IO FileMeta) CachingStrategy
295
296 -- | Meta information about a file to calculate cache headers
297 data FileMeta
298 = FileMeta
299 { fm_lastModified :: !BS.ByteString
300 , fm_etag :: !BS.ByteString
301 , fm_fileName :: FilePath
302 } deriving (Show, Eq)
303
304 -- | Initialize caching. This should only be done once per application launch.
305 initCaching :: CachingStrategy -> IO CacheContainer
306 initCaching cs =
307 do let cacheAccess =
308 consistentDuration 100 $ \state fp ->
309 do fileMeta <- computeFileMeta fp
310 return $! (state, fileMeta)
311 cacheTick =
312 do time <- getPOSIXTime
313 return (round (time * 100))
314 cacheFreq = 1
315 cacheLRU =
316 CacheWithLRUList 100 100 200
317 filecache <- newECMIO cacheAccess cacheTick cacheFreq cacheLRU
318 return (CacheContainer (lookupECM filecache) cs)
319
320 computeFileMeta :: FilePath -> IO FileMeta
321 computeFileMeta fp =
322 do mtime <- getModificationTime fp
323 ct <- BSL.readFile fp
324 return $ FileMeta
325 { fm_lastModified =
326 BSC.pack $ formatTime defaultTimeLocale "%a, %d-%b-%Y %X %Z" mtime
327 , fm_etag = Base16.encode (SHA1.hashlazy ct)
328 , fm_fileName = fp
329 }
330
331 -- | Guess MIME type from file extension
332 getMimeType :: FilePath -> MimeType
333 getMimeType = defaultMimeLookup . T.pack