cce0f59 · servant · git.iko.soy

git.iko.soy/servant

on master help sign in

Merge pull request #658 from haskell-servant/file-serving

cce0f59Oleg Grenrus10 years ago

doc/tutorial/Javascript.lhs+1−1

compare with master

unifiedsplit

@@ -136,7 +136,7 @@ server = randomPoint

136

137server' :: Server API'

138server' = server

139− :<|> serveDirectory "static"

139+ :<|> serveDirectoryFileServer "static"

140

141app :: Application

142app = serve api' server'

doc/tutorial/Server.lhs+7−3

@@ -787,10 +787,10 @@ directory serving WAI application, namely:

787

788``` haskell ignore

789-- exported by Servant and Servant.Server

790−serveDirectory :: FilePath -> Server Raw

790+serveDirectoryWebApp :: FilePath -> Server Raw

791```

792

793−`serveDirectory`'s argument must be a path to a valid directory.

793+`serveDirectoryWebApp`'s argument must be a path to a valid directory.

794

795Here's an example API that will serve some static files:

796

@@ -807,7 +807,7 @@ staticAPI = Proxy

807

808``` haskell

809server7 :: Server StaticAPI

810−server7 = serveDirectory "static-files"

810+server7 = serveDirectoryWebApp "static-files"

811

812app3 :: Application

813app3 = serve staticAPI server7

@@ -821,6 +821,10 @@ In other words: If a client requests `/static/foo.txt`, the server will look for

821`./static-files/foo.txt`. If that file exists it'll succeed and serve the file.

822If it doesn't exist, the handler will fail with a `404` status code.

823

824+`serveDirectoryWebApp` uses some standard settings that fit the use case of

825+serving static files for most web apps. You can find out about the other

826+options in the documentation of the `Servant.Utils.StaticFiles` module.

827+

824## Nested APIs

828## Nested APIs

825

829

826Let's see how you can define APIs in a modular way, while avoiding repetition.

830Let's see how you can define APIs in a modular way, while avoiding repetition.

servant-server/CHANGELOG.md+6−1

@@ -4,9 +4,14 @@

4* Add `err422` Unprocessable Entity

5 ([#646](https://github.com/haskell-servant/servant/pull/646))

7−* `Handler` is not abstract datatype. Migration hint: change `throwE` to `throwError`.

7+* `Handler` is now an abstract datatype. Migration hint: change `throwE` to `throwError`.

8 ([#641](https://github.com/haskell-servant/servant/issues/641))

10+* Deprecate `serveDirectory` and introduce `serveDirectoryFileServer`,

11+ `serveDirectoryWebApp`, `serveDirectoryWebAppLookup`, `serveDirectoryEmbedded`

12+ and `serveDirectoryWith` which offer 4 default options and a more flexible

13+ one for serving static files.

14+

100.7.1

150.7.1

11------

16------

servant-server/src/Servant/Utils/StaticFiles.hs+55−14

@@ -1,20 +1,29 @@

1{-# 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.

3--

4−-- - 'serveDirectory' lets you serve anything that lives under a particular

4+-- The most common needs for a web application are covered by

5−-- directory on your filesystem.

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.

6−module Servant.Utils.StaticFiles (

8+module Servant.Utils.StaticFiles

7− serveDirectory,

9+ ( serveDirectoryWebApp

10+ , serveDirectoryWebAppLookup

11+ , serveDirectoryFileServer

12+ , serveDirectoryEmbedded

13+ , serveDirectoryWith

14+ , -- * Deprecated

15+ serveDirectory

8− ) where

16+ ) where

9−

17+

18+import Data.ByteString (ByteString)

10−import Network.Wai.Application.Static (defaultFileServerSettings,

19+import Network.Wai.Application.Static

11− staticApp)

12import Servant.API.Raw (Raw)

20import Servant.API.Raw (Raw)

13import Servant.Server (Server)

21import Servant.Server (Server)

14import System.FilePath (addTrailingPathSeparator)

22import System.FilePath (addTrailingPathSeparator)

15#if !MIN_VERSION_wai_app_static(3,1,0)

23#if !MIN_VERSION_wai_app_static(3,1,0)

16import Filesystem.Path.CurrentOS (decodeString)

24import Filesystem.Path.CurrentOS (decodeString)

17#endif

25#endif

26+import WaiAppStatic.Storage.Filesystem (ETagLookup)

19-- | Serve anything under the specified directory as a 'Raw' endpoint.

28-- | Serve anything under the specified directory as a 'Raw' endpoint.

20--

29--

@@ -22,7 +31,7 @@ import Filesystem.Path.CurrentOS (decodeString)

22-- type MyApi = "static" :> Raw

31-- type MyApi = "static" :> Raw

23--

32--

24-- server :: Server MyApi

33-- server :: Server MyApi

25−-- server = serveDirectory "\/var\/www"

34+-- server = serveDirectoryWebApp "\/var\/www"

26-- @

35-- @

27--

36--

28-- would capture any request to @\/static\/\<something>@ and look for

37-- would capture any request to @\/static\/\<something>@ and look for

@@ -33,13 +42,45 @@ import Filesystem.Path.CurrentOS (decodeString)

33--

42--

34-- If your goal is to serve HTML, CSS and Javascript files that use the rest of the API

43-- If your goal is to serve HTML, CSS and Javascript files that use the rest of the API

35-- as a webapp backend, you will most likely not want the static files to be hidden

44-- 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'

37-- handler in the last position, because /servant/ will try to match the handlers

46-- handler in the last position, because /servant/ will try to match the handlers

38-- in order.

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

39serveDirectory :: FilePath -> Server Raw

76serveDirectory :: FilePath -> Server Raw

40−serveDirectory =

77+serveDirectory = serveDirectoryFileServer

78+{-# DEPRECATED serveDirectory "Use serveDirectoryFileServer instead" #-}

79+

80+fixPath :: FilePath -> FilePath

81+fixPath =

41#if MIN_VERSION_wai_app_static(3,1,0)

82#if MIN_VERSION_wai_app_static(3,1,0)

42− staticApp . defaultFileServerSettings . addTrailingPathSeparator

83+ addTrailingPathSeparator

43#else

84#else

44− staticApp . defaultFileServerSettings . decodeString . addTrailingPathSeparator

85+ decodeString . addTrailingPathSeparator

45#endif

86#endif

servant-server/test/Servant/Utils/StaticFilesSpec.hs+2−2

@@ -18,7 +18,7 @@ import Test.Hspec.Wai (get, shouldRespondWith, with)

18import Servant.API ((:<|>) ((:<|>)), Capture, Get, Raw, (:>), JSON)

19import Servant.Server (Server, serve)

20import Servant.ServerSpec (Person (Person))

21−import Servant.Utils.StaticFiles (serveDirectory)

21+import Servant.Utils.StaticFiles (serveDirectoryFileServer)

23type Api =

24 "dummy_api" :> Capture "person_name" String :> Get '[JSON] Person

@@ -34,7 +34,7 @@ app = serve api server

34server :: Server Api

35server =

36 (\ name_ -> return (Person name_ 42))

37− :<|> serveDirectory "static"

37+ :<|> serveDirectoryFileServer "static"

39withStaticFiles :: IO () -> IO ()

40withStaticFiles action = withSystemTempDirectory "servant-test" $ \ tmpDir ->