@@ -1,20 +1,29 @@
11{-# LANGUAGE CPP #-}
2−-- | This module defines a sever-side handler that lets you serve static files.
2+-- | This module defines server-side handlers that lets you serve static files.
33--
4−-- - 'serveDirectory' lets you serve anything that lives under a particular
5−-- directory on your filesystem.
6−module Servant.Utils.StaticFiles (
7− serveDirectory,
8− ) where
9−
10−import Network.Wai.Application.Static (defaultFileServerSettings,
11− staticApp)
4+-- The most common needs for a web application are covered by
5+-- 'serveDirectoryWebApp`, but the other variants allow you to use
6+-- different `StaticSettings` and 'serveDirectoryWith' even allows you
7+-- to specify arbitrary 'StaticSettings' to be used for serving static files.
8+module Servant.Utils.StaticFiles
9+ ( serveDirectoryWebApp
10+ , serveDirectoryWebAppLookup
11+ , serveDirectoryFileServer
12+ , serveDirectoryEmbedded
13+ , serveDirectoryWith
14+ , -- * Deprecated
15+ serveDirectory
16+ ) where
17+
18+import Data.ByteString (ByteString)
19+import Network.Wai.Application.Static
1220import Servant.API.Raw (Raw)
1321import Servant.Server (Server)
1422import System.FilePath (addTrailingPathSeparator)
1523#if !MIN_VERSION_wai_app_static(3,1,0)
1624import Filesystem.Path.CurrentOS (decodeString)
1725#endif
26+import WaiAppStatic.Storage.Filesystem (ETagLookup)
1827
1928-- | Serve anything under the specified directory as a 'Raw' endpoint.
2029--
@@ -22,7 +31,7 @@ import Filesystem.Path.CurrentOS (decodeString)
2231-- type MyApi = "static" :> Raw
2332--
2433-- server :: Server MyApi
25−-- server = serveDirectory "\/var\/www"
34+-- server = serveDirectoryWebApp "\/var\/www"
2635-- @
2736--
2837-- would capture any request to @\/static\/\<something>@ and look for
@@ -33,13 +42,45 @@ import Filesystem.Path.CurrentOS (decodeString)
3342--
3443-- If your goal is to serve HTML, CSS and Javascript files that use the rest of the API
3544-- as a webapp backend, you will most likely not want the static files to be hidden
36−-- behind a /\/static\// prefix. In that case, remember to put the 'serveDirectory'
45+-- behind a /\/static\// prefix. In that case, remember to put the 'serveDirectoryWebApp'
3746-- handler in the last position, because /servant/ will try to match the handlers
3847-- in order.
48+--
49+-- Corresponds to the `defaultWebAppSettings` `StaticSettings` value.
50+serveDirectoryWebApp :: FilePath -> Server Raw
51+serveDirectoryWebApp = staticApp . defaultWebAppSettings . fixPath
52+
53+-- | Same as 'serveDirectoryWebApp', but uses `defaultFileServerSettings`.
54+serveDirectoryFileServer :: FilePath -> Server Raw
55+serveDirectoryFileServer = staticApp . defaultFileServerSettings . fixPath
56+
57+-- | Same as 'serveDirectoryWebApp', but uses 'webAppSettingsWithLookup'.
58+serveDirectoryWebAppLookup :: ETagLookup -> FilePath -> Server Raw
59+serveDirectoryWebAppLookup etag =
60+ staticApp . flip webAppSettingsWithLookup etag . fixPath
61+
62+-- | Uses 'embeddedSettings'.
63+serveDirectoryEmbedded :: [(FilePath, ByteString)] -> Server Raw
64+serveDirectoryEmbedded files = staticApp (embeddedSettings files)
65+
66+-- | Alias for 'staticApp'. Lets you serve a directory
67+-- with arbitrary 'StaticSettings'. Useful when you want
68+-- particular settings not covered by the four other
69+-- variants. This is the most flexible method.
70+serveDirectoryWith :: StaticSettings -> Server Raw
71+serveDirectoryWith = staticApp
72+
73+-- | Same as 'serveDirectoryFileServer'. It used to be the only
74+-- file serving function in servant pre-0.10 and will be kept
75+-- around for a few versions, but is deprecated.
3976serveDirectory :: FilePath -> Server Raw
40−serveDirectory =
77+serveDirectory = serveDirectoryFileServer
78+{-# DEPRECATED serveDirectory "Use serveDirectoryFileServer instead" #-}
79+
80+fixPath :: FilePath -> FilePath
81+fixPath =
4182#if MIN_VERSION_wai_app_static(3,1,0)
42− staticApp . defaultFileServerSettings . addTrailingPathSeparator
83+ addTrailingPathSeparator
4384#else
44− staticApp . defaultFileServerSettings . decodeString . addTrailingPathSeparator
85+ decodeString . addTrailingPathSeparator
4586#endif