git.iko.soy/servant
on d64c232 help sign in
servant/servant-server/src/Servant/Server/StaticFiles.hs
83 lines 3.4 kB history raw
1{-# LANGUAGE CPP #-}
2-- | This module defines server-side handlers that lets you serve static files.
3--
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.
8module Servant.Server.StaticFiles
9 ( serveDirectoryWebApp
10 , serveDirectoryWebAppLookup
11 , serveDirectoryFileServer
12 , serveDirectoryEmbedded
13 , serveDirectoryWith
14 , -- * Deprecated
15 serveDirectory
16 ) where
18import Data.ByteString
19 (ByteString)
20import Network.Wai.Application.Static
21import Servant.API.Raw
22 (Raw)
23import Servant.Server
24 (ServerT, Tagged (..))
25import System.FilePath
26 (addTrailingPathSeparator)
27import WaiAppStatic.Storage.Filesystem
28 (ETagLookup)
30-- | Serve anything under the specified directory as a 'Raw' endpoint.
31--
32-- @
33-- type MyApi = "static" :> Raw
34--
35-- server :: Server MyApi
36-- server = serveDirectoryWebApp "\/var\/www"
37-- @
38--
39-- would capture any request to @\/static\/\<something>@ and look for
40-- @\<something>@ under @\/var\/www@.
41--
42-- It will do its best to guess the MIME type for that file, based on the extension,
43-- and send an appropriate /Content-Type/ header if possible.
44--
45-- If your goal is to serve HTML, CSS and Javascript files that use the rest of the API
46-- as a webapp backend, you will most likely not want the static files to be hidden
47-- behind a /\/static\// prefix. In that case, remember to put the 'serveDirectoryWebApp'
48-- handler in the last position, because /servant/ will try to match the handlers
49-- in order.
50--
51-- Corresponds to the `defaultWebAppSettings` `StaticSettings` value.
52serveDirectoryWebApp :: FilePath -> ServerT Raw m
53serveDirectoryWebApp = serveDirectoryWith . defaultWebAppSettings . fixPath
55-- | Same as 'serveDirectoryWebApp', but uses `defaultFileServerSettings`.
56serveDirectoryFileServer :: FilePath -> ServerT Raw m
57serveDirectoryFileServer = serveDirectoryWith . defaultFileServerSettings . fixPath
59-- | Same as 'serveDirectoryWebApp', but uses 'webAppSettingsWithLookup'.
60serveDirectoryWebAppLookup :: ETagLookup -> FilePath -> ServerT Raw m
61serveDirectoryWebAppLookup etag =
62 serveDirectoryWith . flip webAppSettingsWithLookup etag . fixPath
64-- | Uses 'embeddedSettings'.
65serveDirectoryEmbedded :: [(FilePath, ByteString)] -> ServerT Raw m
66serveDirectoryEmbedded files = serveDirectoryWith (embeddedSettings files)
68-- | Alias for 'staticApp'. Lets you serve a directory
69-- with arbitrary 'StaticSettings'. Useful when you want
70-- particular settings not covered by the four other
71-- variants. This is the most flexible method.
72serveDirectoryWith :: StaticSettings -> ServerT Raw m
73serveDirectoryWith = Tagged . staticApp
75-- | Same as 'serveDirectoryFileServer'. It used to be the only
76-- file serving function in servant pre-0.10 and will be kept
77-- around for a few versions, but is deprecated.
78serveDirectory :: FilePath -> ServerT Raw m
79serveDirectory = serveDirectoryFileServer
80{-# DEPRECATED serveDirectory "Use serveDirectoryFileServer instead" #-}
82fixPath :: FilePath -> FilePath
83fixPath = addTrailingPathSeparator